@semiont/core 0.5.1 → 0.5.3

package/dist/index.d.ts

@@ -2223,10 +2223,14 @@ 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;
         };
+        /** @description Payload for frame:tag-schema-added domain event (system-level, no resourceId — fan-out is global to the KB). */
+        TagSchemaAddedPayload: {
+            schema: components["schemas"]["TagSchema"];
+        };
         /** @description Payload for mark:entity-tag-added and mark:entity-tag-removed domain events */
         EntityTagChangedPayload: {
             entityType: string;
@@ -2353,6 +2357,9 @@ interface components {
             /** @description Annotations that reference this resource from other resources */
             entityReferences: components["schemas"]["Annotation"][];
         };
+        GetTagSchemasResponse: {
+            tagSchemas: components["schemas"]["TagSchema"][];
+        };
         GoogleAuthRequest: {
             access_token: string;
         };
@@ -2894,6 +2901,15 @@ interface components {
             path: string;
             reason?: string;
         };
+        /** @description Request to browse registered tag schemas */
+        BrowseTagSchemasRequest: {
+            correlationId: string;
+        };
+        /** @description Result of browsing tag schemas */
+        BrowseTagSchemasResult: {
+            correlationId: string;
+            response: components["schemas"]["GetTagSchemasResponse"];
+        };
         /** @description W3C Web Annotation FragmentSelector for media fragment identifiers (RFC 3778 for PDFs) */
         FragmentSelector: {
             /** @enum {string} */
@@ -3198,12 +3214,18 @@ 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;
         };
+        /** @description Bus command to register a tag schema with the KB's runtime registry. Carried on the `frame:add-tag-schema` channel — Frame is the schema-layer flow that owns vocabulary writes. Most-recent registration of a given `schema.id` wins; the projection reflects the latest content. Identical re-registrations are silent; differing content overwrites and logs a warning. */
+        FrameAddTagSchemaCommand: {
+            schema: components["schemas"]["TagSchema"];
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
+        };
         /** @description Bus command to archive a resource and optionally remove its file. */
         MarkArchiveCommand: {
             /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
@@ -3353,6 +3375,21 @@ interface components {
             /** @description SVG markup defining the region (must include xmlns attribute) */
             value: string;
         };
+        /** @description A single category within a tag schema (e.g. 'Issue' in IRAC, 'distinguished' in legal-citation-treatment). Each category carries methodology-bound semantics: a name, a description, and examples used in the LLM prompt. */
+        TagCategory: {
+            name: string;
+            description: string;
+            examples: string[];
+        };
+        /** @description A structural-analysis schema (e.g. legal-irac, scientific-imrad, argument-toulmin). Defines a methodology framework as an id, name, description, domain hint, and an ordered list of categories. KBs and their skills register schemas with the runtime registry via `frame.addTagSchema(...)` at session start. */
+        TagSchema: {
+            id: string;
+            name: string;
+            description: string;
+            /** @description Free-form domain hint (e.g. 'legal', 'scientific', 'general'). Used in the LLM prompt to tune the model's analysis voice. KB authors choose. */
+            domain: string;
+            tags: components["schemas"]["TagCategory"][];
+        };
         /** @description Bus command to create a cloned resource from a clone token. */
         YieldCloneCreateCommand: {
             correlationId: string;
@@ -3418,22 +3455,6 @@ interface components {
             toUri: string;
             noGit?: boolean;
         };
-        /** @description Bus command to request yield (generation) of a new resource from an annotation. */
-        YieldRequestCommand: {
-            /** @description Client-supplied id used to match this command to its result event(s) on the events-stream. Generated by the route handler if absent. */
-            correlationId?: string;
-            annotationId: string;
-            resourceId: string;
-            options: {
-                title: string;
-                prompt?: string;
-                language?: string;
-                temperature?: number;
-                maxTokens?: number;
-                context?: components["schemas"]["GatheredContext"];
-                storageUri: string;
-            };
-        };
         /** @description Bus command to update a yielded resource's storage content. */
         YieldUpdateCommand: {
             /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
@@ -3675,14 +3696,15 @@ 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'];
+    'frame:tag-schema-added': components['schemas']['TagSchemaAddedPayload'];
     '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' | 'frame:tag-schema-added';
 /** Extract the concrete persisted event type for a given type string. */
 type EventOfType<K extends keyof PersistedEventCatalog> = K extends SystemEventType ? EventBase & {
     type: K;
@@ -3707,7 +3729,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", "frame:tag-schema-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'>;
 
@@ -3829,7 +3851,6 @@ type EventMap = {
     'yield:moved': StoredEvent<EventOfType<'yield:moved'>>;
     'yield:representation-added': StoredEvent<EventOfType<'yield:representation-added'>>;
     'yield:representation-removed': StoredEvent<EventOfType<'yield:representation-removed'>>;
-    'yield:request': components['schemas']['YieldRequestCommand'];
     'yield:create': components['schemas']['YieldCreateCommand'];
     'yield:update': components['schemas']['YieldUpdateCommand'];
     'yield:mv': components['schemas']['YieldMvCommand'];
@@ -3868,7 +3889,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'];
@@ -3878,13 +3898,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'];
@@ -3899,6 +3917,12 @@ 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:tag-schema-added': StoredEvent<EventOfType<'frame:tag-schema-added'>>;
+    'frame:add-entity-type': components['schemas']['FrameAddEntityTypeCommand'];
+    'frame:add-tag-schema': components['schemas']['FrameAddTagSchemaCommand'];
+    'frame:entity-type-add-failed': components['schemas']['CommandError'];
+    'frame:tag-schema-add-failed': components['schemas']['CommandError'];
     'bind:initiate': BindInitiateCommand;
     'bind:update-body': BindUpdateBodyCommand;
     'bind:body-updated': components['schemas']['BindBodyUpdated'];
@@ -3978,6 +4002,11 @@ type EventMap = {
     'browse:entity-types-failed': {
         correlationId: string;
     } & components['schemas']['CommandError'];
+    'browse:tag-schemas-requested': components['schemas']['BrowseTagSchemasRequest'];
+    'browse:tag-schemas-result': components['schemas']['BrowseTagSchemasResult'];
+    'browse:tag-schemas-failed': {
+        correlationId: string;
+    } & components['schemas']['CommandError'];
     'browse:directory-requested': components['schemas']['BrowseDirectoryRequest'];
     'browse:directory-result': components['schemas']['BrowseDirectoryResult'];
     'browse:directory-failed': {
@@ -4079,7 +4108,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.
  */
 /**
@@ -4120,7 +4149,6 @@ declare const CHANNEL_SCHEMAS: {
     readonly 'yield:moved': null;
     readonly 'yield:representation-added': null;
     readonly 'yield:representation-removed': null;
-    readonly 'yield:request': "YieldRequestCommand";
     readonly 'yield:create': "YieldCreateCommand";
     readonly 'yield:update': "YieldUpdateCommand";
     readonly 'yield:mv': "YieldMvCommand";
@@ -4145,7 +4173,8 @@ 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 'frame:tag-schema-added': null;
     readonly 'mark:archived': null;
     readonly 'mark:unarchived': null;
     readonly 'mark:create-request': "MarkCreateRequest";
@@ -4155,13 +4184,15 @@ 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 'frame:add-tag-schema': "FrameAddTagSchemaCommand";
     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 'frame:tag-schema-add-failed': "CommandError";
     readonly 'mark:select-comment': "SelectionData";
     readonly 'mark:select-tag': "SelectionData";
     readonly 'mark:select-assessment': "SelectionData";
@@ -4223,6 +4254,9 @@ declare const CHANNEL_SCHEMAS: {
     readonly 'browse:entity-types-requested': "BrowseEntityTypesRequest";
     readonly 'browse:entity-types-result': "BrowseEntityTypesResult";
     readonly 'browse:entity-types-failed': null;
+    readonly 'browse:tag-schemas-requested': "BrowseTagSchemasRequest";
+    readonly 'browse:tag-schemas-result': "BrowseTagSchemasResult";
+    readonly 'browse:tag-schemas-failed': null;
     readonly 'browse:directory-requested': "BrowseDirectoryRequest";
     readonly 'browse:directory-result': "BrowseDirectoryResult";
     readonly 'browse:directory-failed': null;
@@ -5000,6 +5034,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
@@ -5007,10 +5089,15 @@ 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.
@@ -5084,6 +5171,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]`;
@@ -5118,6 +5220,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>;
@@ -5134,21 +5268,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;
@@ -5164,10 +5301,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?: {
@@ -5202,7 +5365,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:tag-schemas-result", "browse:tag-schemas-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", "frame:tag-schema-added", "beckon:focus", "beckon:sparkle", "bus:resume-gap"];
 type BridgedChannel = typeof BRIDGED_CHANNELS[number];
 
 /**
@@ -5590,6 +5753,33 @@ interface ResourceFilter {
     offset?: number;
 }
 
+/**
+ * Tag-schema type aliases.
+ *
+ * These are type-only re-exports of the OpenAPI `TagSchema` and `TagCategory`
+ * shapes. The schemas themselves do not live in `@semiont/core` — they're
+ * registered at runtime per-KB via `frame.addTagSchema(...)` against a
+ * per-KB projection. This module just exposes the shape so KB authors and
+ * skill code can type their schema literals without the OpenAPI lookup
+ * syntax (`components['schemas']['TagSchema']`).
+ */
+
+/**
+ * A structural-analysis schema (e.g. legal-irac, scientific-imrad).
+ *
+ * Defines a methodology framework as an id, name, description, domain hint,
+ * and an ordered list of categories. KBs and their skills register schemas
+ * with the runtime registry via `frame.addTagSchema(...)` at session start.
+ */
+type TagSchema = components['schemas']['TagSchema'];
+/**
+ * A single category within a {@link TagSchema} (e.g. 'Issue' in IRAC).
+ *
+ * Each category carries methodology-bound semantics: a name, a description,
+ * and examples used in the LLM prompt.
+ */
+type TagCategory = components['schemas']['TagCategory'];
+
 /**
  * Auth types
  */
@@ -5650,36 +5840,6 @@ declare function isNullish(value: unknown): value is null | undefined;
  */
 declare function isDefined<T>(value: T | null | undefined): value is T;
 
-/**
- * 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.
- */
-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>);
-}
-
 /**
  * DID (Decentralized Identifier) and W3C Agent utilities
  *
@@ -5865,4 +6025,4 @@ declare function getAllPlatformTypes(): PlatformType[];
 declare const CORE_TYPES_VERSION = "0.1.0";
 declare const SDK_VERSION = "0.1.0";
 
-export { 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 TagCategory, type TagSchema, 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 };