@semiont/core 0.5.9 → 0.5.11

package/dist/testing.d.ts

@@ -0,0 +1,2909 @@
+import { Observable, Subject, BehaviorSubject } from 'rxjs';
+import * as fc from 'fast-check';
+
+/**
+ * Marker for the state-unit pattern: a stateful, lifecycled object with an
+ * RxJS-shaped public surface, constructed by a factory function
+ * (`createFooStateUnit`), with internal state held in a closure.
+ *
+ * The structural contract is `dispose()` — the rest of the pattern
+ * (closure-based identity, Observable public surface, internal Subjects
+ * exposed as `.asObservable()` views, no leaked subscriptions, composition
+ * by parameter rather than ownership) is convention, made executable by the
+ * axiom harness in `@semiont/core/testing` (`assertStateUnitAxioms`).
+ *
+ * Lives in `@semiont/core` (not sdk) so every layer can share one definition
+ * without dependency cycles — `http-transport`'s `ActorStateUnit` sits below
+ * sdk and would otherwise have to re-declare it. See
+ * `packages/sdk/docs/STATE-UNITS.md` for the full pattern and rationale, and
+ * `.plans/STATE-UNIT-AXIOMS.md` for the axiom ledger.
+ */
+interface StateUnit {
+    /**
+     * Idempotent, total teardown. Completes every Subject the unit owns,
+     * unsubscribes every internal subscription, releases timers / abort
+     * controllers / network handles. Safe to call multiple times — the
+     * second call is a no-op.
+     */
+    dispose(): void;
+}
+
+/**
+ * Executable enforcement of the StateUnit pattern — the runtime twin of
+ * `packages/sdk/docs/STATE-UNITS.md` and the ledger in
+ * `.plans/STATE-UNIT-AXIOMS.md`. The `StateUnit` interface's own comment notes
+ * the pattern is convention; this file makes it executable.
+ *
+ * `assertStateUnitAxioms(spec)` runs every applicable axiom against a factory in
+ * one shot, throwing a labeled Error on the first violation (the axiom id is in
+ * the message). It is framework-agnostic on purpose — only `rxjs` + `fast-check`,
+ * no `vitest` — so it ships through `@semiont/core/testing` and any package's test
+ * runner can invoke it from a single `it(...)` per state unit. It lives in core
+ * (not sdk) so even packages below sdk (e.g. `http-transport`) can use it without
+ * a dependency cycle.
+ *
+ * Axioms (random-input dimension; fast-check):
+ *   A5        dispose() is idempotent and total (n ∈ [1,20] calls never throw)
+ *   A5b       post-dispose inertness — every public method is a no-op after dispose
+ *   A6        every pre-dispose subscriber (k ∈ [1,10]) sees `complete` on dispose
+ *   X3-runtime instance isolation — driving one instance never moves another's surfaces
+ * Structural assertions (single-shot):
+ *   A1        plain-object identity (no class instance)
+ *   X1        no raw Subject on the public surface
+ *   A7-passed disposing the unit must NOT dispose an injected dependency
+ *   A7-owned  disposing the unit MUST dispose its internally-constructed children
+ */
+
+/**
+ * A disposable stand-in for an injected dependency. Pass one as a unit's
+ * constructor arg, then list it in `setup().passedIn` so A7-passed can assert
+ * the unit never disposed it. Counts calls so A7-passed also holds under the
+ * repeated-dispose stress of A5.
+ */
+interface DisposeProbe extends StateUnit {
+    readonly disposeCount: number;
+}
+declare function disposeProbe(): DisposeProbe;
+type SetupResult<T extends StateUnit> = T | {
+    unit: T;
+    passedIn?: readonly DisposeProbe[];
+    teardown?: () => void;
+};
+interface StateUnitAxiomSpec<T extends StateUnit> {
+    /**
+     * Build a FRESH unit. Called many times (fast-check re-runs), so it must
+     * return an independent instance each call. Return the bare unit, or an object
+     * carrying the injected `passedIn` probes (A7-passed) and a `teardown` to
+     * release per-instance resources (e.g. a mock bus).
+     */
+    setup: () => SetupResult<T>;
+    /** Owned public Observables — Subjects the unit completes on dispose (A6, X3, post-dispose inertness). */
+    surfaces?: (unit: T) => readonly Observable<unknown>[];
+    /** Public input methods as zero-arg callers (A5b post-dispose, X3 drive). */
+    invocations?: (unit: T) => readonly (() => unknown)[];
+    /** Surfaces of internally-constructed children — must complete when the outer disposes (A7-owned). */
+    ownedChildSurfaces?: (unit: T) => readonly Observable<unknown>[];
+    /** fast-check run budget per property (default 30). */
+    numRuns?: number;
+}
+/**
+ * Run every applicable axiom against `spec`. Throws a labeled Error on the first
+ * violation. Axioms whose accessors are omitted are skipped (e.g. A7-passed
+ * runs only when `setup` returns `passedIn`; A6 only when `surfaces` is given).
+ */
+declare function assertStateUnitAxioms<T extends StateUnit>(spec: StateUnitAxiomSpec<T>): void;
+
+declare class SemiontError extends Error {
+    code: string;
+    details?: Record<string, unknown> | undefined;
+    constructor(message: string, code: string, details?: Record<string, unknown> | undefined);
+}
+
+interface components {
+    schemas: {
+        AcceptTermsResponse: {
+            success: boolean;
+            message: string;
+        };
+        AdminUpdateUserResponse: {
+            success: boolean;
+            user: {
+                id: string;
+                email: string;
+                name: string | null;
+                image: string | null;
+                domain: string;
+                provider: string;
+                isAdmin: boolean;
+                isActive: boolean;
+                lastLogin: string | null;
+                created: string;
+                updatedAt: string;
+            };
+        };
+        AdminUsersListResponse: {
+            success: boolean;
+            users: {
+                id: string;
+                email: string;
+                name: string | null;
+                image: string | null;
+                domain: string;
+                provider: string;
+                isAdmin: boolean;
+                isActive: boolean;
+                lastLogin: string | null;
+                created: string;
+                updatedAt: string;
+            }[];
+        };
+        AdminUserStatsResponse: {
+            success: boolean;
+            stats: {
+                totalUsers: number;
+                activeUsers: number;
+                adminUsers: number;
+                regularUsers: number;
+                domainBreakdown: {
+                    domain: string;
+                    count: number;
+                }[];
+                recentSignups: {
+                    id: string;
+                    email: string;
+                    name: string | null;
+                    created: string;
+                }[];
+            };
+        };
+        /** @description Web Annotation / W3C PROV Agent. Discriminated by @type — Person, Organization, or Software. Each branch carries fields appropriate to its kind. Software peers are first-class participants, not a sub-class of Person. */
+        Agent: ({
+            /** @constant */
+            "@type": "Person";
+            /**
+             * Format: uri
+             * @description DID-shaped identifier (e.g. did:web:host:users:email%40host)
+             */
+            "@id"?: string;
+            /** @description Display name */
+            name: string;
+            nickname?: string;
+            email?: string;
+            email_sha1?: string;
+            homepage?: string;
+        } & {
+            [key: string]: unknown;
+        }) | ({
+            /** @constant */
+            "@type": "Organization";
+            /** Format: uri */
+            "@id"?: string;
+            name: string;
+            homepage?: string;
+        } & {
+            [key: string]: unknown;
+        }) | ({
+            /** @constant */
+            "@type": "Software";
+            /**
+             * Format: uri
+             * @description DID-shaped identifier (e.g. did:web:host:agents:provider:model)
+             */
+            "@id"?: string;
+            /** @description Stable human-friendly label. Not parsed; UI composes display from structured fields. */
+            name: string;
+            /** @description Inference provider (e.g. ollama, anthropic) */
+            provider?: string;
+            /** @description Model identifier (e.g. gemma2:27b, claude-3-5-sonnet) */
+            model?: string;
+            /** @description Inference parameters (temperature, maxTokens, systemPrompt, etc.). Runtime metadata, not part of identity. */
+            parameters?: {
+                [key: string]: unknown;
+            };
+        } & {
+            [key: string]: unknown;
+        });
+        Annotation: {
+            /**
+             * @description W3C Web Annotation JSON-LD context
+             * @default http://www.w3.org/ns/anno.jsonld
+             * @enum {string}
+             */
+            "@context": "http://www.w3.org/ns/anno.jsonld";
+            /**
+             * @description W3C Annotation type
+             * @default Annotation
+             * @enum {string}
+             */
+            type: "Annotation";
+            id: string;
+            motivation: components["schemas"]["Motivation"];
+            /** @description W3C Web Annotation target - can be a simple IRI string (entire resource) or an object with source and optional selector (fragment) */
+            target: string | components["schemas"]["AnnotationTarget"];
+            /** @description W3C Web Annotation body. Optional per the W3C spec — annotations whose motivation alone is meaningful (highlighting) legitimately omit it. Present values are either a single body or a non-empty array of bodies; the prior empty-array 'stub' branch has been removed (it was a naming lie shared between highlights and never-actually-emitted stub references, and the source of the #651 reference-annotation validator bug). */
+            body?: components["schemas"]["AnnotationBody"] | components["schemas"]["AnnotationBody"][];
+            /** @description Web Annotation creator — the entity that initiated the annotation. For human-driven work this is a Person; for autonomous-agent work this is a Software peer. */
+            creator?: components["schemas"]["Agent"];
+            created?: string;
+            modified?: string;
+            /** @description Web Annotation generator — the SoftwareAgent that produced the annotation, when software was involved. Absent for purely manual annotations. Single object is the common case; array supports pipelines that combine multiple software peers. */
+            generator?: components["schemas"]["Agent"] | components["schemas"]["Agent"][];
+            /** @description PROV-O wasAttributedTo — all parties responsible for this annotation. For human-prompted AI work this combines `creator` (the Person) and `generator` (the Software). For purely manual annotations it equals `[creator]`; for autonomous-agent work it equals `[generator]` (and `creator` may be the same Software). */
+            wasAttributedTo?: components["schemas"]["Agent"] | components["schemas"]["Agent"][];
+        };
+        /** @description Phase 2: Body can be TextualBody (for entity tags, descriptions) or SpecificResource (for links) */
+        AnnotationBody: components["schemas"]["TextualBody"] | components["schemas"]["SpecificResource"];
+        AnnotationContextResponse: {
+            annotation: components["schemas"]["Annotation"];
+            context: {
+                before?: string;
+                selected: string;
+                after?: string;
+            };
+            resource: components["schemas"]["ResourceDescriptor"];
+        };
+        /** @description W3C Web Annotation target object - source is required, selector is optional */
+        AnnotationTarget: {
+            /** @description IRI of the resource being annotated */
+            source: string;
+            /** @description Optional selector to identify a specific segment of the source resource */
+            selector?: components["schemas"]["TextPositionSelector"] | components["schemas"]["TextQuoteSelector"] | components["schemas"]["SvgSelector"] | components["schemas"]["FragmentSelector"] | (components["schemas"]["TextPositionSelector"] | components["schemas"]["TextQuoteSelector"] | components["schemas"]["SvgSelector"] | components["schemas"]["FragmentSelector"])[];
+        };
+        AuthResponse: {
+            success: boolean;
+            user: {
+                id: string;
+                email: string;
+                name: string | null;
+                image: string | null;
+                domain: string;
+                isAdmin: boolean;
+            };
+            /** @description Short-lived access token (1 hour). Use as Authorization: Bearer header on API calls. */
+            token: string;
+            /** @description Long-lived refresh token (30 days). Exchange via POST /api/tokens/refresh for a fresh access token. */
+            refreshToken: string;
+            isNewUser: boolean;
+        };
+        BrowseFilesResponse: {
+            /** @description The directory path that was listed, relative to project root */
+            path: string;
+            entries: components["schemas"]["DirectoryEntry"][];
+        };
+        /** @description Emit an event on the Semiont bus. Channel names come from bus-protocol.ts; payload shape is validated against the channel's registered schema (CHANNEL_SCHEMAS). An optional scope routes resource-scoped broadcasts (e.g. mark:added, job:complete) to per-resource subscribers via eventBus.scope(scope); leave it unset for unscoped/global events. */
+        BusEmitRequest: {
+            /** @description Channel name from bus-protocol.ts EventMap */
+            channel: string;
+            /** @description Channel-specific payload, validated against CHANNEL_SCHEMAS */
+            payload: {
+                [key: string]: unknown;
+            };
+            /** @description Optional resource scope for broadcast channels (e.g. resourceId). Publishers only — frontends must never set this. */
+            scope?: string;
+        };
+        /** @description User's cookie consent preferences. `necessary` is always true — necessary cookies cannot be disabled. Timestamps and version are stamped server-side. */
+        CookieConsent: {
+            /** @enum {boolean} */
+            necessary: true;
+            analytics: boolean;
+            marketing: boolean;
+            preferences: boolean;
+            /** Format: date-time */
+            timestamp: string;
+            version: string;
+        };
+        /** @description Request body for POST /api/cookies/consent. All four preference fields must be booleans; `necessary` must be true. */
+        CookieConsentRequest: {
+            /** @enum {boolean} */
+            necessary: true;
+            analytics: boolean;
+            marketing: boolean;
+            preferences: boolean;
+        };
+        /** @description Standard envelope for cookie consent endpoints. On success `success: true` and `consent` carries the current preferences; on error `success: false` and `error` carries a human-readable message. */
+        CookieConsentResponse: {
+            success: boolean;
+            consent?: components["schemas"]["CookieConsent"];
+            error?: string;
+        };
+        /** @description GDPR data export of a user's cookie-related data. The response is returned as a file download (Content-Disposition: attachment). */
+        CookieExportResponse: {
+            user: {
+                id: string;
+                email: string;
+            };
+            consent: components["schemas"]["CookieConsent"];
+            /** Format: date-time */
+            exportDate: string;
+            dataRetentionPolicy: string;
+        };
+        DirectoryEntry: components["schemas"]["FileEntry"] | components["schemas"]["DirEntry"];
+        FileEntry: {
+            /** @enum {string} */
+            type: "file";
+            /** @description Entry name (basename) */
+            name: string;
+            /** @description Path relative to project root */
+            path: string;
+            /** @description File size in bytes */
+            size: number;
+            /**
+             * Format: date-time
+             * @description Last modified time (ISO 8601)
+             */
+            mtime: string;
+            /** @description True if this file is a tracked resource in the Knowledge Base */
+            tracked: boolean;
+            /** @description Resource ID (only when tracked is true) */
+            resourceId?: string;
+            /** @description Entity types assigned to this resource (only when tracked is true) */
+            entityTypes?: string[];
+            /** @description Number of annotations on this resource (only when tracked is true) */
+            annotationCount?: number;
+            /** @description DID of the user who created the resource (only when tracked is true) */
+            creator?: string;
+        };
+        DirEntry: {
+            /** @enum {string} */
+            type: "dir";
+            /** @description Entry name (basename) */
+            name: string;
+            /** @description Path relative to project root */
+            path: string;
+            /**
+             * Format: date-time
+             * @description Last modified time (ISO 8601)
+             */
+            mtime: string;
+        };
+        BodyOperationAdd: {
+            /** @enum {string} */
+            op: "add";
+            item: components["schemas"]["TextualBody"] | components["schemas"]["SpecificResource"];
+        };
+        BodyOperationRemove: {
+            /** @enum {string} */
+            op: "remove";
+            item: components["schemas"]["TextualBody"] | components["schemas"]["SpecificResource"];
+        };
+        BodyOperationReplace: {
+            /** @enum {string} */
+            op: "replace";
+            oldItem: components["schemas"]["TextualBody"] | components["schemas"]["SpecificResource"];
+            newItem: components["schemas"]["TextualBody"] | components["schemas"]["SpecificResource"];
+        };
+        CloneResourceWithTokenResponse: {
+            /** @description Generated clone token */
+            token: string;
+            /** @description ISO 8601 timestamp when token expires */
+            expiresAt: string;
+            resource: components["schemas"]["ResourceDescriptor"];
+        };
+        /** @description Error response for failed bus commands. Replaces native Error objects on the EventBus so payloads are serializable and OpenAPI-typed. */
+        CommandError: {
+            /** @description Optional correlation id echoed from the originating command. When present, the failure event can be matched back to the specific command that failed. */
+            correlationId?: string;
+            /** @description Human-readable error message */
+            message: string;
+            /** @description Optional additional context (stack trace, field name, etc.) */
+            details?: string;
+        };
+        /**
+         * @description Content format as a MIME type, optionally with parameters. The base type (everything before the first ';') MUST be a SupportedMediaType; parameters such as charset are preserved as metadata. Semantic validation happens in code at the create/yield boundary — there is deliberately no pattern here, the vocabulary lives in SupportedMediaType. Examples: text/plain, text/plain; charset=iso-8859-1, text/markdown; charset=windows-1252, image/png, application/pdf
+         * @example text/plain; charset=utf-8
+         */
+        ContentFormat: string;
+        /**
+         * @description Base MIME types (no parameters) admitted by Semiont. Membership is the create/yield gate — every member is storable, nameable, and uploadable. What more the system can do with a type (render, annotate, extract text, author) is curated per type in @semiont/core's media-type registry, which is keyed by this enum.
+         * @enum {string}
+         */
+        SupportedMediaType: "text/plain" | "text/markdown" | "text/html" | "text/css" | "text/csv" | "text/xml" | "application/json" | "application/xml" | "application/yaml" | "application/x-yaml" | "application/pdf" | "application/msword" | "application/vnd.openxmlformats-officedocument.wordprocessingml.document" | "application/vnd.ms-excel" | "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" | "application/vnd.ms-powerpoint" | "application/vnd.openxmlformats-officedocument.presentationml.presentation" | "application/zip" | "application/gzip" | "application/x-tar" | "application/x-7z-compressed" | "application/octet-stream" | "application/wasm" | "image/png" | "image/jpeg" | "image/gif" | "image/webp" | "image/svg+xml" | "image/bmp" | "image/tiff" | "image/x-icon" | "video/mp4" | "video/mpeg" | "video/webm" | "video/ogg" | "video/quicktime" | "video/x-msvideo" | "audio/mpeg" | "audio/wav" | "audio/ogg" | "audio/webm" | "audio/aac" | "audio/flac" | "text/javascript" | "application/javascript" | "text/x-typescript" | "application/typescript" | "text/x-python" | "text/x-java" | "text/x-c" | "text/x-c++" | "text/x-csharp" | "text/x-go" | "text/x-rust" | "text/x-ruby" | "text/x-php" | "text/x-swift" | "text/x-kotlin" | "text/x-shell" | "font/woff" | "font/woff2" | "font/ttf" | "font/otf";
+        ContextualSummaryResponse: {
+            summary: string;
+            relevantFields: {
+                [key: string]: unknown;
+            };
+            context: {
+                before?: string;
+                selected: string;
+                after?: string;
+            };
+        };
+        CreateAnnotationRequest: {
+            motivation: components["schemas"]["Motivation"];
+            target: components["schemas"]["AnnotationTarget"];
+            /** @description Optional body. Omit for annotations whose motivation alone is meaningful (highlighting) or whose user-supplied content is empty. Shape matches Annotation.body. */
+            body?: components["schemas"]["AnnotationBody"] | components["schemas"]["AnnotationBody"][];
+        };
+        /** @description Response body for POST /resources (202 Accepted). Resource creation is asynchronous — the backend writes content to disk, emits yield:create on the bus, and returns the newly-minted resourceId immediately. Consumers watch SSE domain events (yield:created) to observe the fully-persisted state. */
+        CreateResourceResponse: {
+            /** @description The id of the newly-created resource. Assigned by Stower when it persists yield:create. */
+            resourceId: string;
+        };
+        DeleteUserResponse: {
+            success: boolean;
+            message: string;
+        };
+        /** @description Progress payload emitted on the gather:annotation-progress SSE channel during LLM context gathering. */
+        GatherProgress: {
+            message?: string;
+            percentage?: number;
+        };
+        /** @description Search results payload emitted on match:search-results SSE channel. */
+        MatchSearchResult: {
+            correlationId: string;
+            referenceId: string;
+            response: (components["schemas"]["ResourceDescriptor"] & {
+                /** @description Relevance score */
+                score?: number;
+                /** @description Human-readable reason for the match */
+                matchReason?: string;
+            })[];
+        };
+        /** @description Error payload emitted on match:search-failed SSE channel. */
+        MatchSearchFailed: {
+            correlationId: string;
+            referenceId: string;
+            error: string;
+        };
+        /** @description Metadata added at persistence time. Part of every StoredEvent. Integrity is provided by git at the commit level (when gitSync is enabled), not by in-event metadata fields. */
+        EventMetadata: {
+            /** @description Monotonic position in the event log (ordering authority) */
+            sequenceNumber: number;
+            /** @description Optional correlation id propagated from a command. Lets clients match command-result events back to the POST that initiated them. Set by EventStore.appendEvent's options when a route handler passes one through. */
+            correlationId?: string;
+        };
+        /** @description Selection data for user-initiated annotations. Captures the text range and optional selector information from a user's highlight in the UI. */
+        SelectionData: {
+            /** @description The exact selected text */
+            exact: string;
+            /** @description Start character offset */
+            start: number;
+            /** @description End character offset */
+            end: number;
+            /** @description SVG selector for non-text selections (e.g. PDF regions) */
+            svgSelector?: string;
+            /** @description Fragment selector (e.g. page=2) */
+            fragmentSelector?: string;
+            /** @description Specification the fragment selector conforms to */
+            conformsTo?: string;
+            /** @description Text before the selection (for disambiguation) */
+            prefix?: string;
+            /** @description Text after the selection (for disambiguation) */
+            suffix?: string;
+        };
+        /** @description A persisted domain event with metadata. Flat shape — event fields and metadata are peers. */
+        StoredEventResponse: {
+            /** @description Unique event ID (UUID) */
+            id: string;
+            /** @description Event type (flow verb name, e.g. mark:added) */
+            type: string;
+            /**
+             * Format: date-time
+             * @description When the event occurred
+             */
+            timestamp: string;
+            /** @description DID of the user who triggered the event */
+            userId: string;
+            /** @description Resource this event affects (absent for system events) */
+            resourceId?: string;
+            /** @description Event schema version */
+            version: number;
+            /** @description Event-type-specific payload */
+            payload: {
+                [key: string]: unknown;
+            };
+            metadata: components["schemas"]["EventMetadata"];
+        };
+        /** @description Wire format emitted by GET /resources/:id/events/stream. Extends StoredEventResponse with optional enrichment fields populated from the materialized view at SSE-write time. Subscribers can read the enrichment fields directly to update local caches without an additional fetch. */
+        EnrichedResourceEvent: components["schemas"]["StoredEventResponse"] & {
+            /** @description Populated for events that mutate an annotation (mark:added, mark:body-updated, mark:removed). Carries the post-materialization annotation as it exists in the view, so subscribers can update local caches in-place without refetching. Absent for events that don't touch annotations. */
+            annotation?: components["schemas"]["Annotation"];
+        };
+        /** @description Payload for yield:created domain event */
+        ResourceCreatedPayload: {
+            name: string;
+            format: components["schemas"]["ContentFormat"];
+            /** @description SHA-256 of content */
+            contentChecksum: string;
+            contentByteSize?: number;
+            entityTypes?: string[];
+            /** @description Working-tree URI (e.g. file://docs/overview.md) */
+            storageUri?: string;
+            language?: string;
+            isDraft?: boolean;
+            generatedFrom?: {
+                resourceId: string;
+                annotationId: string;
+            };
+            generationPrompt?: string;
+            generator?: components["schemas"]["Agent"] | components["schemas"]["Agent"][];
+        };
+        /** @description Payload for yield:cloned domain event */
+        ResourceClonedPayload: {
+            name: string;
+            format: components["schemas"]["ContentFormat"];
+            contentChecksum: string;
+            contentByteSize?: number;
+            parentResourceId: string;
+            entityTypes?: string[];
+            language?: string;
+        };
+        /** @description Payload for yield:updated domain event */
+        ResourceUpdatedPayload: {
+            /** @description SHA-256 of new content */
+            contentChecksum: string;
+            contentByteSize?: number;
+        };
+        /** @description Payload for yield:moved domain event */
+        ResourceMovedPayload: {
+            /** @description Previous file:// URI */
+            fromUri: string;
+            /** @description New file:// URI */
+            toUri: string;
+        };
+        /** @description Payload for mark:archived domain event */
+        ResourceArchivedPayload: {
+            reason?: string;
+        };
+        /** @description Payload for mark:unarchived domain event (empty payload) */
+        ResourceUnarchivedPayload: Record<string, never>;
+        /** @description Payload for yield:representation-added domain event */
+        RepresentationAddedPayload: {
+            representation: components["schemas"]["Representation"];
+        };
+        /** @description Payload for yield:representation-removed domain event */
+        RepresentationRemovedPayload: {
+            /** @description Checksum of the representation to remove */
+            checksum: string;
+        };
+        /** @description Payload for mark:added domain event */
+        AnnotationAddedPayload: {
+            annotation: components["schemas"]["Annotation"];
+            /** @description SHA-256 of resource content at annotation time */
+            contentChecksum?: string;
+        };
+        /** @description Payload for mark:removed domain event */
+        AnnotationRemovedPayload: {
+            annotationId: string;
+        };
+        /** @description Payload for mark:body-updated domain event */
+        AnnotationBodyUpdatedPayload: {
+            annotationId: string;
+            operations: (components["schemas"]["BodyOperationAdd"] | components["schemas"]["BodyOperationRemove"] | components["schemas"]["BodyOperationReplace"])[];
+        };
+        /** @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;
+        };
+        /**
+         * @description Type of background job
+         * @enum {string}
+         */
+        JobType: "reference-annotation" | "generation" | "highlight-annotation" | "assessment-annotation" | "comment-annotation" | "tag-annotation";
+        /** @description Payload for job:started domain event */
+        JobStartedPayload: {
+            jobId: string;
+            jobType: components["schemas"]["JobType"];
+            /** @description Annotation this job is attached to, when applicable */
+            annotationId?: string;
+            totalSteps?: number;
+        };
+        /** @description Payload for job:progress domain event */
+        JobProgressPayload: {
+            jobId: string;
+            jobType: components["schemas"]["JobType"];
+            percentage: number;
+            /** @description Human-readable current step */
+            currentStep?: string;
+            processedSteps?: number;
+            totalSteps?: number;
+            /** @description For detection: entities found so far */
+            foundCount?: number;
+            message?: string;
+            /** @description Full progress object for extensibility */
+            progress?: {
+                [key: string]: unknown;
+            };
+        };
+        /** @description Payload for job:completed domain event */
+        JobCompletedPayload: {
+            jobId: string;
+            jobType: components["schemas"]["JobType"];
+            /** @description Annotation this job was attached to, when applicable */
+            annotationId?: string;
+            totalSteps?: number;
+            /** @description For detection: total entities found */
+            foundCount?: number;
+            /** @description For generation: ID of generated resource */
+            resultResourceId?: string;
+            /** @description For generation: URI of annotation that triggered generation */
+            annotationUri?: string;
+            message?: string;
+            /** @description Full result object for extensibility */
+            result?: {
+                [key: string]: unknown;
+            };
+        };
+        /** @description Payload for job:failed domain event */
+        JobFailedPayload: {
+            jobId: string;
+            jobType: components["schemas"]["JobType"];
+            /** @description Annotation this job was attached to, when applicable */
+            annotationId?: string;
+            error: string;
+            details?: string;
+        };
+        ErrorResponse: {
+            error: string;
+            code?: string;
+            details?: unknown;
+        };
+        EventStreamResponse: {
+            event: string;
+            data: string;
+            id?: string;
+        };
+        GetAnnotationHistoryResponse: {
+            events: components["schemas"]["StoredEventResponse"][];
+            total: number;
+            annotationId: string;
+            resourceId: string;
+        };
+        GetAnnotationResponse: {
+            annotation: components["schemas"]["Annotation"];
+            resource: components["schemas"]["ResourceDescriptor"] | null;
+            resolvedResource: components["schemas"]["ResourceDescriptor"] | null;
+        };
+        GetAnnotationsResponse: {
+            annotations: components["schemas"]["Annotation"][];
+            /** @description Total number of annotations */
+            total: number;
+            /** @description Motivation filter applied (if any) */
+            motivation?: components["schemas"]["Motivation"] | null;
+        };
+        GetEntityTypesResponse: {
+            entityTypes: string[];
+        };
+        GetEventsResponse: {
+            events: components["schemas"]["StoredEventResponse"][];
+            total: number;
+            resourceId: string;
+        };
+        GetReferencedByResponse: {
+            referencedBy: {
+                /** @description Reference annotation ID */
+                id: string;
+                /** @description Name of resource containing the reference */
+                resourceName: string;
+                target: {
+                    /** @description ID of resource containing the reference */
+                    source: string;
+                    selector: {
+                        /** @description The selected text that references this resource */
+                        exact: string;
+                    };
+                };
+            }[];
+        };
+        GetResourceByTokenResponse: {
+            sourceResource: components["schemas"]["ResourceDescriptor"];
+            /** @description ISO 8601 timestamp when token expires */
+            expiresAt: string;
+        };
+        GetResourceResponse: {
+            resource: components["schemas"]["ResourceDescriptor"];
+            /** @description All annotations for the resource (highlights, references, assessments, etc.) */
+            annotations: components["schemas"]["Annotation"][];
+            /** @description Annotations that reference this resource from other resources */
+            entityReferences: components["schemas"]["Annotation"][];
+        };
+        GetTagSchemasResponse: {
+            tagSchemas: components["schemas"]["TagSchema"][];
+        };
+        GoogleAuthRequest: {
+            access_token: string;
+        };
+        HealthResponse: {
+            status: string;
+            message: string;
+            version: string;
+            timestamp: string;
+            /** @enum {string} */
+            database: "connected" | "disconnected" | "unknown";
+            environment: string;
+        };
+        JobStatusResponse: {
+            jobId: string;
+            type: components["schemas"]["JobType"];
+            /** @enum {string} */
+            status: "pending" | "running" | "complete" | "failed" | "cancelled";
+            userId: string;
+            created: string;
+            startedAt?: string;
+            completedAt?: string;
+            error?: string;
+            progress?: unknown;
+            result?: unknown;
+        };
+        /** @description Knowledge graph gathered for an LLM context — a shared backbone in which resources AND annotations are typed nodes, connected by typed (optionally bidirectional) edges. Flattened views the matcher/generation read (connections, citedBy, siblings) are derived from these nodes/edges. */
+        KnowledgeGraph: {
+            nodes: {
+                /** @description Node identifier — a ResourceId or AnnotationId */
+                id: string;
+                /**
+                 * @description Whether this node is a resource or an annotation
+                 * @enum {string}
+                 */
+                type: "resource" | "annotation";
+                label: string;
+                /** @description Entity types on the node (resources) or carried by the annotation */
+                entityTypes?: string[];
+                metadata?: {
+                    [key: string]: unknown;
+                };
+            }[];
+            edges: {
+                source: string;
+                target: string;
+                /** @description Edge kind (e.g. citation, annotation-of, sibling) */
+                type: string;
+                /** @description Whether the connection goes both ways */
+                bidirectional?: boolean;
+                metadata?: {
+                    [key: string]: unknown;
+                };
+            }[];
+        };
+        ListResourcesResponse: {
+            resources: components["schemas"]["ResourceDescriptor"][];
+            total: number;
+            offset: number;
+            limit: number;
+        };
+        PasswordAuthRequest: {
+            /**
+             * Format: email
+             * @description User email address
+             */
+            email: string;
+            /** @description User password (minimum 8 characters) */
+            password: string;
+        };
+        /**
+         * @description Semiont-supported W3C Web Annotation motivations - https://www.w3.org/TR/annotation-vocab/#motivation
+         * @enum {string}
+         */
+        Motivation: "assessing" | "commenting" | "highlighting" | "linking" | "tagging";
+        OAuthConfigResponse: {
+            providers: {
+                name: string;
+                isConfigured: boolean;
+                clientId: string;
+            }[];
+            allowedDomains: string[];
+        };
+        /** @description A specific, byte-addressable rendition of a resource (file/asset/variant). */
+        Representation: {
+            /**
+             * Format: uri
+             * @description Stable ID for this representation.
+             */
+            "@id"?: string;
+            /** @description Type(s), e.g., schema:MediaObject. */
+            "@type"?: string | string[];
+            /** @description MIME/media type (e.g., text/markdown, image/png). */
+            mediaType: string;
+            /** @description Working-tree URI identifying where the bytes live. Only file:// is supported (e.g. file://docs/overview.md). */
+            storageUri?: string;
+            filename?: string;
+            /** @description Size of the payload in bytes. */
+            byteSize?: number;
+            /** @description Integrity hash (e.g., sha256:abcd…). */
+            checksum?: string;
+            /** @description Compression/transfer encoding if applicable. */
+            encoding?: string;
+            /** @description IETF BCP 47 language tag (e.g., en, es-ES). */
+            language?: string;
+            /** @description Pixels (images/video). */
+            width?: number;
+            /** @description Pixels (images/video). */
+            height?: number;
+            /** @description Seconds (audio/video). */
+            duration?: number;
+            /** Format: date-time */
+            created?: string;
+            /** Format: date-time */
+            modified?: string;
+            /** @description Profile/shape the bytes conform to (e.g., a JSON profile or SVG profile). */
+            conformsTo?: string | string[];
+            tags?: string[];
+            /**
+             * @description Semantics of this rendition relative to the resource (e.g., original, thumbnail, preview, derived).
+             * @enum {string}
+             */
+            rel?: "original" | "thumbnail" | "preview" | "optimized" | "derived" | "other";
+        } & {
+            [key: string]: unknown;
+        };
+        /** @description Metadata about a resource (1:1 with its URI). JSON-LD subject is @id. Link to concrete bytes via representations. */
+        ResourceDescriptor: {
+            /** @description JSON-LD context; URI, object, or array of these. */
+            "@context": string | {
+                [key: string]: unknown;
+            } | (string | {
+                [key: string]: unknown;
+            })[];
+            /** @description Canonical URI/URN of the resource being described. */
+            "@id": string;
+            /** @description Type(s) of the resource (IRIs/CURIEs via @context). */
+            "@type"?: string | string[];
+            name: string;
+            description?: string;
+            /** @description Persistent identifiers (e.g., DOI, URN). */
+            identifier?: string | string[] | ({
+                /** Format: uri */
+                "@id"?: string;
+                value?: string;
+                scheme?: string;
+            } & {
+                [key: string]: unknown;
+            });
+            /** @description Topics (IRIs or strings). */
+            about?: string | string[];
+            /** @description Equivalent/authoritative references. */
+            sameAs?: string[];
+            isPartOf?: string[];
+            hasPart?: string[];
+            /** Format: uri */
+            license?: string;
+            version?: string;
+            /** Format: date-time */
+            dateCreated?: string;
+            /** Format: date-time */
+            dateModified?: string;
+            /** @description W3C PROV - source resources this was derived from */
+            wasDerivedFrom?: string | string[];
+            /** @description W3C PROV - agents responsible for this resource */
+            wasAttributedTo?: components["schemas"]["Agent"] | components["schemas"]["Agent"][];
+            /** @description Software agent that produced or processed this resource (W3C Web Annotation model) */
+            generator?: components["schemas"]["Agent"] | components["schemas"]["Agent"][];
+            /** @description Profile/shape URI this resource description conforms to. */
+            conformsTo?: string | string[];
+            /** @description Convenience set summarizing media types across representations. */
+            availableFormats?: string[];
+            /** @description Managed or referenced byte-level renditions of this resource. */
+            representations: components["schemas"]["Representation"] | components["schemas"]["Representation"][];
+            /** @description Application-specific: Whether this resource is archived */
+            archived?: boolean;
+            /** @description Application-specific: Entity types for this resource */
+            entityTypes?: string[];
+            /** @description Application-specific: Whether this resource is a draft */
+            isDraft?: boolean;
+            /** @description Application-specific: ID of annotation that triggered generation */
+            sourceAnnotationId?: string;
+            /** @description Application-specific: ID of source resource for clones/derivatives */
+            sourceResourceId?: string;
+            /**
+             * Format: uri
+             * @description Original URI from a source knowledge base when this resource was imported
+             */
+            originatedFrom?: string;
+            /** @description Working-tree URI for this resource (e.g. file://docs/overview.md). Stable across updates and moves. */
+            storageUri?: string;
+            /** @description SHA-256 hex hash of the current content. Updated on resource.created, resource.updated, resource.cloned events. */
+            currentChecksum?: string;
+        } & {
+            [key: string]: unknown;
+        };
+        SemanticMatch: {
+            /** @description The chunk text that matched */
+            text: string;
+            /** @description Source resource ID */
+            resourceId: string;
+            /** @description Source annotation ID, if the match is from an annotation */
+            annotationId?: string;
+            /** @description Cosine similarity score (0-1) */
+            score: number;
+            /** @description Entity types on the matched passage */
+            entityTypes?: string[];
+        };
+        SpecificResource: {
+            /** @enum {string} */
+            type: "SpecificResource";
+            /** @description IRI of the target resource */
+            source: string;
+            /** @description Why this body is included */
+            purpose?: components["schemas"]["BodyPurpose"];
+        };
+        StatusResponse: {
+            status: string;
+            version: string;
+            features: {
+                semanticContent: string;
+                collaboration: string;
+                rbac: string;
+            };
+            message: string;
+            authenticatedAs?: string;
+            /** @description Name of the knowledge base project */
+            projectName?: string;
+            /** @description Current git branch of the knowledge base repository */
+            gitBranch?: string;
+        };
+        TextPositionSelector: {
+            /** @enum {string} */
+            type: "TextPositionSelector";
+            /** @description Character offset from resource start */
+            start: number;
+            /** @description Character offset from resource start */
+            end: number;
+        };
+        TextQuoteSelector: {
+            /** @enum {string} */
+            type: "TextQuoteSelector";
+            exact: string;
+            prefix?: string;
+            suffix?: string;
+        };
+        TextualBody: {
+            /** @enum {string} */
+            type: "TextualBody";
+            /** @description The text content (e.g., entity type name) */
+            value: string;
+            /** @description Why this body is included */
+            purpose?: components["schemas"]["BodyPurpose"];
+            /** @description MIME type (defaults to text/plain) */
+            format?: string;
+            /** @description BCP 47 language tag */
+            language?: string;
+        };
+        TokenRefreshRequest: {
+            /**
+             * @description Refresh token obtained during login
+             * @example eyJhbGciOiJIUzI1NiIs...
+             */
+            refreshToken: string;
+        };
+        TokenRefreshResponse: {
+            access_token: string;
+        };
+        UpdateAnnotationBodyRequest: {
+            /** @description Resource ID containing the annotation (required for O(1) Layer 3 lookup) */
+            resourceId: string;
+            /** @description Array of body modification operations to apply */
+            operations: (components["schemas"]["BodyOperationAdd"] | components["schemas"]["BodyOperationRemove"] | components["schemas"]["BodyOperationReplace"])[];
+        };
+        UpdateUserRequest: {
+            isAdmin?: boolean;
+            isActive?: boolean;
+            name?: string;
+        };
+        UpdateUserResponse: {
+            success: boolean;
+            user: {
+                id: string;
+                email: string;
+                name?: string | null;
+                image?: string | null;
+                domain: string;
+                provider: string;
+                isAdmin: boolean;
+                isActive: boolean;
+                lastLogin?: string | null;
+                created: string;
+                updatedAt: string;
+            };
+        };
+        UserResponse: {
+            id: string;
+            email: string;
+            name: string | null;
+            image: string | null;
+            domain: string;
+            provider: string;
+            isAdmin: boolean;
+            isModerator: boolean;
+            isActive: boolean;
+            termsAcceptedAt: string | null;
+            lastLogin: string | null;
+            created: string;
+            /** @description The validated JWT token string for the current session */
+            token: string;
+        };
+        /** @description Emitted when an annotation receives focus for beckoning */
+        BeckonFocusEvent: {
+            annotationId?: string;
+            resourceId?: string;
+        };
+        /** @description Emitted when an annotation is hovered over for beckoning */
+        BeckonHoverEvent: {
+            annotationId: string | null;
+        };
+        /** @description Emitted when a sparkle effect is triggered on an annotation */
+        BeckonSparkleEvent: {
+            annotationId: string;
+        };
+        /** @description Void success reply emitted on the bind:body-updated channel after bind:update-body has been applied, matched to the originating command by correlationId. */
+        BindBodyUpdated: {
+            /** @description Correlation id echoed from the originating bind:update-body command so busRequest can match the reply. */
+            correlationId: string;
+        };
+        /** @description Command payload sent on the bind:initiate bus channel to start a bind flow. */
+        BindInitiateCommand: {
+            /** @description Branded AnnotationId of the annotation being bound */
+            annotationId: string;
+            /** @description Branded ResourceId of the resource being bound to */
+            resourceId: string;
+            /** @description Default title for the bound annotation */
+            defaultTitle: string;
+            /** @description Entity types to associate with the annotation */
+            entityTypes: string[];
+        };
+        /** @description Command payload sent on the bind:update-body bus channel to modify annotation bodies. */
+        BindUpdateBodyCommand: {
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
+            /** @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;
+            /** @description Branded AnnotationId of the annotation whose body is being updated */
+            annotationId: string;
+            /** @description Branded ResourceId of the resource the annotation belongs to */
+            resourceId: string;
+            /** @description List of body mutation operations to apply */
+            operations: {
+                /**
+                 * @description The type of body operation
+                 * @enum {string}
+                 */
+                op: "add" | "remove" | "replace";
+                /** @description Body item for add operations */
+                item?: components["schemas"]["AnnotationBody"];
+                /** @description Previous body item for replace operations */
+                oldItem?: components["schemas"]["AnnotationBody"];
+                /** @description Replacement body item for replace operations */
+                newItem?: components["schemas"]["AnnotationBody"];
+            }[];
+        };
+        /**
+         * @description W3C Web Annotation body purpose vocabulary - https://www.w3.org/TR/annotation-vocab/#motivation
+         * @enum {string}
+         */
+        BodyPurpose: "assessing" | "bookmarking" | "classifying" | "commenting" | "describing" | "editing" | "highlighting" | "identifying" | "linking" | "moderating" | "questioning" | "replying" | "tagging";
+        /** @description Request to browse the KB's collaborator directory (its declared Agents) */
+        BrowseAgentsRequest: {
+            correlationId: string;
+        };
+        /** @description Result of browsing the collaborator directory */
+        BrowseAgentsResult: {
+            correlationId: string;
+            response: {
+                agents: components["schemas"]["CollaboratorEntry"][];
+            };
+        };
+        /** @description Request to browse the history of an annotation */
+        BrowseAnnotationHistoryRequest: {
+            correlationId: string;
+            resourceId: string;
+            annotationId: string;
+        };
+        /** @description Result of browsing annotation history */
+        BrowseAnnotationHistoryResult: {
+            correlationId: string;
+            response: components["schemas"]["GetAnnotationHistoryResponse"];
+        };
+        /** @description Request to browse a single annotation */
+        BrowseAnnotationRequest: {
+            correlationId: string;
+            resourceId: string;
+            annotationId: string;
+        };
+        /** @description Result of browsing a single annotation */
+        BrowseAnnotationResult: {
+            correlationId: string;
+            response: components["schemas"]["GetAnnotationResponse"];
+        };
+        /** @description Request to get contextual text around an annotation */
+        BrowseAnnotationContextRequest: {
+            correlationId: string;
+            annotationId: string;
+            resourceId: string;
+            contextBefore?: number;
+            contextAfter?: number;
+        };
+        /** @description Request to browse annotations for a resource */
+        BrowseAnnotationsRequest: {
+            correlationId: string;
+            resourceId: string;
+        };
+        /** @description Result of browsing annotations for a resource */
+        BrowseAnnotationsResult: {
+            correlationId: string;
+            response: components["schemas"]["GetAnnotationsResponse"];
+        };
+        /** @description Emitted when an annotation is clicked in the browse panel */
+        BrowseClickEvent: {
+            annotationId: string;
+            motivation: components["schemas"]["Motivation"];
+        };
+        /** @description Request to browse a directory listing */
+        BrowseDirectoryRequest: {
+            correlationId: string;
+            path: string;
+            /** @enum {string} */
+            sort?: "name" | "mtime" | "annotationCount";
+        };
+        /** @description Result of browsing a directory listing */
+        BrowseDirectoryResult: {
+            correlationId: string;
+            response: {
+                path: string;
+                entries: components["schemas"]["DirectoryEntry"][];
+            };
+        };
+        /** @description Emitted when an entity type is clicked in the browse panel */
+        BrowseEntityTypeClickedEvent: {
+            entityType: string;
+        };
+        /** @description Request to browse available entity types */
+        BrowseEntityTypesRequest: {
+            correlationId: string;
+        };
+        /** @description Result of browsing entity types */
+        BrowseEntityTypesResult: {
+            correlationId: string;
+            response: components["schemas"]["GetEntityTypesResponse"];
+        };
+        /** @description Request to browse events for a resource */
+        BrowseEventsRequest: {
+            correlationId: string;
+            resourceId: string;
+            type?: string;
+            userId?: string;
+            limit?: number;
+        };
+        /** @description Result of browsing events for a resource */
+        BrowseEventsResult: {
+            correlationId: string;
+            response: components["schemas"]["GetEventsResponse"];
+        };
+        /** @description Emitted when navigation to an external URL is requested */
+        BrowseExternalNavigateEvent: {
+            url: string;
+            resourceId?: string;
+        };
+        /** @description Emitted when a link is clicked in the browse panel */
+        BrowseLinkClickedEvent: {
+            href: string;
+            label?: string;
+        };
+        /** @description Emitted when a browse panel is opened */
+        BrowsePanelOpenEvent: {
+            panel: string;
+            scrollToAnnotationId?: string;
+            motivation?: string;
+        };
+        /** @description Emitted when a browse panel is toggled */
+        BrowsePanelToggleEvent: {
+            panel: string;
+        };
+        /** @description Request to browse annotations that reference a resource */
+        BrowseReferencedByRequest: {
+            correlationId: string;
+            resourceId: string;
+            motivation?: string;
+        };
+        /** @description Result of browsing annotations that reference a resource */
+        BrowseReferencedByResult: {
+            correlationId: string;
+            response: components["schemas"]["GetReferencedByResponse"];
+        };
+        /** @description Emitted when navigation to a reference resource is requested */
+        BrowseReferenceNavigateEvent: {
+            resourceId: string;
+        };
+        /** @description Emitted when a resource is closed in the browse panel */
+        BrowseResourceCloseEvent: {
+            resourceId: string;
+        };
+        /** @description Emitted when resources are reordered in the browse panel */
+        BrowseResourceReorderEvent: {
+            oldIndex: number;
+            newIndex: number;
+        };
+        /** @description Request to browse a single resource */
+        BrowseResourceRequest: {
+            correlationId: string;
+            resourceId: string;
+        };
+        /** @description Result of browsing a single resource */
+        BrowseResourceResult: {
+            correlationId: string;
+            response: components["schemas"]["GetResourceResponse"];
+        };
+        /** @description Request to browse resources with optional filtering and pagination */
+        BrowseResourcesRequest: {
+            correlationId: string;
+            search?: string;
+            archived?: boolean;
+            entityType?: string;
+            offset?: number;
+            limit?: number;
+        };
+        /** @description Result of browsing resources */
+        BrowseResourcesResult: {
+            correlationId: string;
+            response: components["schemas"]["ListResourcesResponse"];
+        };
+        /** @description Emitted when the browse panel requests a router navigation */
+        BrowseRouterPushEvent: {
+            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 One collaborator in the KB's directory: a W3C Agent plus, for software agents declared in the KB's worker inference config, the job types it serves. Actor-role-only agents (gatherer/matcher) and Persons omit servesJobTypes. */
+        CollaboratorEntry: {
+            agent: components["schemas"]["Agent"];
+            /** @description Job types this agent is declared to serve (from the KB's workers.* config sections). Absent for Persons and for agents declared only under actor roles. */
+            servesJobTypes?: components["schemas"]["JobType"][];
+        };
+        /** @description W3C Web Annotation FragmentSelector for media fragment identifiers (RFC 3778 for PDFs) */
+        FragmentSelector: {
+            /** @enum {string} */
+            type: "FragmentSelector";
+            /**
+             * @description Media fragment identifier (e.g., 'page=1&viewrect=100,200,50,30' for PDF)
+             * @example page=1&viewrect=100,200,50,30
+             */
+            value: string;
+            /**
+             * @description URI identifying the fragment syntax specification
+             * @example http://tools.ietf.org/rfc/rfc3778
+             */
+            conformsTo?: string;
+        };
+        /** @description Completion payload emitted on the gather:annotation-complete bus channel when annotation context gathering finishes. */
+        GatherAnnotationComplete: {
+            /** @description Client-generated correlation ID to thread the response back to the originating request */
+            correlationId: string;
+            /** @description Branded AnnotationId of the annotation whose context was gathered */
+            annotationId: string;
+            /** @description The gathered annotation context (unified GatheredContext, focus.kind:'annotation') */
+            response: components["schemas"]["GatheredContext"];
+        };
+        /** @description Request payload sent on the gather:requested bus channel to gather context for an annotation. */
+        GatherAnnotationRequest: {
+            /** @description Client-generated correlation ID to thread the response back to the originating request */
+            correlationId: string;
+            /** @description Branded AnnotationId of the annotation to gather context for */
+            annotationId: string;
+            /** @description Branded ResourceId of the resource the annotation belongs to */
+            resourceId: string;
+            /** @description Optional gathering configuration */
+            options?: {
+                /** @description Whether to include source context in the gathered result */
+                includeSourceContext?: boolean;
+                /** @description Whether to include target context in the gathered result */
+                includeTargetContext?: boolean;
+                /** @description Characters of surrounding text context to include */
+                contextWindow?: number;
+            };
+        };
+        /** @description Context gathered for a gather.* call — consumed by yield.* (generation) and the matcher. A shared base (graph, semanticContext, metadata, inferredRelationshipSummary) plus a discriminated `focus` that names the anchor: an annotation or a whole resource. */
+        GatheredContext: {
+            /** @description The gather anchor. Discriminated on `kind`. */
+            focus: {
+                /** @enum {string} */
+                kind: "annotation";
+                /** @description The annotation this context was gathered for */
+                annotation: components["schemas"]["Annotation"];
+                /** @description The resource containing the annotation */
+                sourceResource: components["schemas"]["ResourceDescriptor"];
+                /** @description Text context around the annotation target */
+                selected?: {
+                    /** @description Text appearing before the selected passage */
+                    before?: string;
+                    /** @description The selected text passage (the annotation target) */
+                    text: string;
+                    /** @description Text appearing after the selected passage */
+                    after?: string;
+                };
+                /** @description User-provided hint to supplement or replace the selected text for search and generation */
+                userHint?: string;
+                /** @description The resource the annotation links to, if it is a resolved reference. Dormant capability — produced/exposed but not yet consumed (see LINK-TARGET-CONTEXT.md). */
+                targetResource?: components["schemas"]["ResourceDescriptor"];
+                /** @description Context about the annotation's link target. Dormant — see LINK-TARGET-CONTEXT.md. */
+                targetContext?: {
+                    content: string;
+                    summary?: string;
+                };
+            } | {
+                /** @enum {string} */
+                kind: "resource";
+                /** @description The resource this context was gathered for */
+                resource: components["schemas"]["ResourceDescriptor"];
+                summary?: string;
+                suggestedReferences?: string[];
+                /** @description Resource content (included when requested) */
+                content?: {
+                    /** @description Content of the focal resource */
+                    main?: string;
+                    /** @description Map of related resource IDs to their content */
+                    related?: {
+                        [key: string]: string;
+                    };
+                };
+            };
+            /** @description Knowledge graph backbone — resources AND annotations as typed nodes. The flattened views (connections, citedBy, siblings) are derived from this. */
+            graph: components["schemas"]["KnowledgeGraph"];
+            /** @description Semantically similar passages from across the knowledge base, found via vector search */
+            semanticContext?: {
+                /** @description Passages ranked by cosine similarity to the focal text */
+                similar: components["schemas"]["SemanticMatch"][];
+                /** @description Entity types excluded from this recall — a record of how `similar` was filtered (e.g. ['Question'] so answer-generation never surfaces prior questions). Absent when no exclusion was applied. */
+                excludedEntityTypes?: string[];
+            };
+            /** @description Context metadata about the focal anchor and its source */
+            metadata: {
+                /** @description Type of source resource (e.g., 'document', 'image', 'video') */
+                resourceType?: string;
+                /** @description BCP 47 language tag of source content */
+                language?: string;
+                /** @description Entity types associated with the focal anchor */
+                entityTypes?: string[];
+                /** @description Global frequency counts for entity types (for IDF-like weighting). A KB-wide statistic, not a neighborhood property — kept here rather than on the graph. */
+                entityTypeFrequencies?: {
+                    [key: string]: number;
+                };
+            };
+            /** @description LLM-generated summary of the focal anchor's relationships in the knowledge graph */
+            inferredRelationshipSummary?: string;
+        };
+        /** @description Completion payload emitted on the gather:resource-complete bus channel when resource context gathering finishes. */
+        GatherResourceComplete: {
+            /** @description Client-generated correlation ID to thread the response back to the originating request */
+            correlationId: string;
+            /** @description Branded ResourceId of the resource whose context was gathered */
+            resourceId: string;
+            /** @description The gathered resource context (unified GatheredContext, focus.kind:'resource') */
+            response: components["schemas"]["GatheredContext"];
+        };
+        /** @description Request payload sent on the gather:resource-requested bus channel to gather context for a resource. */
+        GatherResourceRequest: {
+            /** @description Client-generated correlation ID to thread the response back to the originating request */
+            correlationId: string;
+            /** @description Branded ResourceId of the resource to gather context for */
+            resourceId: string;
+            /** @description Gathering configuration */
+            options: {
+                /** @description Depth of resource graph traversal */
+                depth: number;
+                /** @description Maximum number of related resources to include */
+                maxResources: number;
+                /** @description Whether to include resource content in the gathered result */
+                includeContent: boolean;
+                /** @description Whether to include resource summaries in the gathered result */
+                includeSummary: boolean;
+                /** @description Entity types to exclude from the semantic recall built into this context (caller-supplied; e.g. a chat consumer passes ['Question'] so prior questions never ground answer generation). Optional; default none. */
+                excludeEntityTypes?: string[];
+            };
+        };
+        /** @description Request to generate an AI summary of an annotation */
+        GatherSummaryRequest: {
+            correlationId: string;
+            annotationId: string;
+            resourceId: string;
+        };
+        /** @description Result of a completed assessment-annotation job. */
+        JobAssessmentAnnotationResult: {
+            assessmentsFound: number;
+            assessmentsCreated: number;
+        };
+        /** @description Request to cancel a job */
+        JobCancelRequest: {
+            /** @description Correlation id for request/reply matching, set by the SDK's busRequest so the confirmed-write ack/failure routes back. Absent for the local cancelRequest UI signal. */
+            correlationId?: string;
+            /** @enum {string} */
+            jobType: "annotation" | "generation";
+        };
+        /** @description Command to claim a pending job (atomic CAS: pending → running) */
+        JobClaimCommand: {
+            correlationId: string;
+            jobId: string;
+        };
+        /** @description Command to create a new job via the event bus */
+        JobCreateCommand: {
+            correlationId: string;
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
+            jobType: components["schemas"]["JobType"];
+            resourceId: string;
+            params: {
+                [key: string]: unknown;
+            };
+        };
+        /** @description Result of a job:create command */
+        JobCreatedResult: {
+            correlationId: string;
+            response: {
+                jobId: string;
+            };
+        };
+        /** @description Result of a completed comment-annotation job. */
+        JobCommentAnnotationResult: {
+            commentsFound: number;
+            commentsCreated: number;
+        };
+        /** @description Command to mark a job as complete */
+        JobCompleteCommand: {
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
+            resourceId: string;
+            jobId: string;
+            jobType: components["schemas"]["JobType"];
+            /** @description Annotation this job is attached to, when applicable. Lets the UI route completion feedback (toast, resolve state) to a specific annotation. */
+            annotationId?: string;
+            result?: components["schemas"]["JobResult"];
+        };
+        /** @description Command to mark a job as failed */
+        JobFailCommand: {
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
+            resourceId: string;
+            jobId: string;
+            jobType: components["schemas"]["JobType"];
+            /** @description Annotation this job is attached to, when applicable. Lets the UI route failure feedback (error toast, revert state) to a specific annotation. */
+            annotationId?: string;
+            error: string;
+        };
+        /** @description Result of a completed generation job. resourceId is assigned by Stower when yield:create is processed; the worker emits job:complete with only resourceName, and Stower populates resourceId on the persisted payload. */
+        JobGenerationResult: {
+            /** @description ID of the generated resource (populated by Stower, not by the worker) */
+            resourceId?: string;
+            /** @description Name of the generated resource */
+            resourceName: string;
+        };
+        /** @description Result of a completed highlight-annotation job. */
+        JobHighlightAnnotationResult: {
+            highlightsFound: number;
+            highlightsCreated: number;
+        };
+        /** @description Progress report from a running job. Common fields are stage/percentage/message; job-type-specific fields may also be present. This is the single progress shape for every job type — annotation workers and generation alike. */
+        JobProgress: {
+            /** @description Current processing stage (e.g. 'analyzing', 'creating', 'complete', 'error') */
+            stage: string;
+            /** @description Completion percentage (0-100) */
+            percentage: number;
+            /** @description Human-readable progress message */
+            message: string;
+            /** @description Annotation this job is attached to, when applicable. Echoed inside JobProgress (in addition to the outer command envelope) so consumers that only see the inner progress object (e.g. client.yield.fromAnnotation's Observable) can still route visual feedback to a specific annotation. */
+            annotationId?: string;
+            /** @description Total entity types to process (reference-annotation) */
+            totalEntityTypes?: number;
+            /** @description Entity types processed so far (reference-annotation) */
+            processedEntityTypes?: number;
+            /** @description Entities found so far (reference-annotation) */
+            entitiesFound?: number;
+            /** @description Annotations emitted so far (reference-annotation) */
+            entitiesEmitted?: number;
+            /** @description Entity type currently being processed */
+            currentEntityType?: string;
+            /** @description Reference annotation: completed entity types with per-type counts, for UI progress display */
+            completedEntityTypes?: {
+                entityType: string;
+                foundCount: number;
+            }[];
+            /** @description Categories processed (tag-annotation) */
+            processedCategories?: number;
+            /** @description Total categories (tag-annotation) */
+            totalCategories?: number;
+            /** @description Category currently being processed (tag-annotation) */
+            currentCategory?: string;
+            /** @description Echoed job parameters for display in the progress UI (e.g. entity types or categories the user asked to detect) */
+            requestParams?: {
+                label: string;
+                value: string;
+            }[];
+        };
+        /** @description Event indicating a job has been queued */
+        JobQueuedEvent: {
+            jobId: string;
+            jobType: string;
+            resourceId: string;
+            /** @description DID of the user who initiated the job (audit). */
+            userId: string;
+        };
+        /** @description Result of a completed reference-annotation job. */
+        JobReferenceAnnotationResult: {
+            /** @description Total entities found */
+            totalFound: number;
+            /** @description Total annotations emitted */
+            totalEmitted: number;
+            /** @description Number of errors encountered */
+            errors: number;
+        };
+        /** @description Command to report progress on a job */
+        JobReportProgressCommand: {
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
+            resourceId: string;
+            jobId: string;
+            jobType: components["schemas"]["JobType"];
+            /** @description Annotation this job is attached to, when applicable. Lets the UI attach progress visuals to a specific annotation (e.g. a reference whose generation is running). */
+            annotationId?: string;
+            percentage: number;
+            progress?: components["schemas"]["JobProgress"];
+        };
+        /** @description Discriminated union of all job result types. */
+        JobResult: components["schemas"]["JobGenerationResult"] | components["schemas"]["JobReferenceAnnotationResult"] | components["schemas"]["JobHighlightAnnotationResult"] | components["schemas"]["JobAssessmentAnnotationResult"] | components["schemas"]["JobCommentAnnotationResult"] | components["schemas"]["JobTagAnnotationResult"];
+        /** @description Command to start a job */
+        JobStartCommand: {
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
+            resourceId: string;
+            jobId: string;
+            jobType: components["schemas"]["JobType"];
+            /** @description Annotation this job is attached to, when applicable. Set for annotation-scoped jobs like generation (from a specific reference). Unset for resource-scoped jobs like bulk reference/tag/highlight detection. */
+            annotationId?: string;
+        };
+        /** @description Request to check the status of a job */
+        JobStatusRequest: {
+            correlationId: string;
+            jobId: string;
+        };
+        /** @description Result of a job status request */
+        JobStatusResult: {
+            correlationId: string;
+            response: components["schemas"]["JobStatusResponse"];
+        };
+        /** @description Result of a completed tag-annotation job. */
+        JobTagAnnotationResult: {
+            tagsFound: number;
+            tagsCreated: number;
+            /** @description Count of tags created per category */
+            byCategory: {
+                [key: string]: number;
+            };
+        };
+        /** @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: {
+            /** @description Correlation id for request/reply matching, set by the SDK's busRequest so the confirmed-write ack/failure routes back. Absent for in-process (bootstrap/replay/import) emits, which race the frame:entity-type-added domain event instead. */
+            correlationId?: string;
+            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: {
+            /** @description Correlation id for request/reply matching, set by the SDK's busRequest so the confirmed-write ack/failure routes back. Absent for in-process emits. */
+            correlationId?: string;
+            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 Correlation id for request/reply matching, set by the SDK's busRequest so the confirmed-write ack/failure routes back. */
+            correlationId?: string;
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
+            resourceId: string;
+            storageUri?: string;
+            keepFile?: boolean;
+            noGit?: boolean;
+        };
+        /** @description Emitted when the user requests AI assistance for a mark */
+        MarkAssistRequestEvent: {
+            /** @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;
+            motivation: components["schemas"]["Motivation"];
+            options: {
+                instructions?: string;
+                /** @enum {string} */
+                tone?: "scholarly" | "explanatory" | "conversational" | "technical" | "analytical" | "critical" | "balanced" | "constructive";
+                density?: number;
+                language?: string;
+                entityTypes?: string[];
+                includeDescriptiveReferences?: boolean;
+                schemaId?: string;
+                categories?: string[];
+            };
+        };
+        /** @description Bus command to create an annotation on a resource. */
+        MarkCreateCommand: {
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
+            /** @description Optional correlation id threaded from the originating mark:create-request. Propagated into event metadata by Stower so annotation-assembly can emit mark:create-ok after persistence completes. */
+            correlationId?: string;
+            annotation: components["schemas"]["Annotation"];
+            resourceId: string;
+        };
+        /** @description Success reply after creating an annotation, matched to the originating command by correlationId. */
+        MarkCreateOk: {
+            /** @description Correlation id echoed from the mark:create-request command so busRequest can match the reply. */
+            correlationId?: string;
+            /** @description The created annotation's identity. */
+            response: {
+                annotationId: string;
+            };
+        };
+        /** @description Raw annotation creation intent — bus handler assembles the W3C annotation */
+        MarkCreateRequest: {
+            correlationId: string;
+            resourceId: string;
+            request: components["schemas"]["CreateAnnotationRequest"];
+        };
+        /** @description Bus command to delete an annotation. */
+        MarkDeleteCommand: {
+            /** @description Correlation id for request/reply matching, set by the SDK's busRequest so the confirmed-write ack/failure routes back. */
+            correlationId?: string;
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
+            annotationId: string;
+            resourceId?: string;
+        };
+        /** @description Success reply after deleting an annotation, matched to the originating command by correlationId. */
+        MarkDeleteOk: {
+            /** @description Correlation id echoed from the mark:delete command so busRequest can match the reply. */
+            correlationId?: string;
+            /** @description The deleted annotation's identity. */
+            response: {
+                annotationId: string;
+            };
+        };
+        /** @description Emitted when the user requests a new mark (annotation) on a resource */
+        MarkRequestedEvent: {
+            /** @description The '@id' of the resource the mark belongs to (W3C target.source). Routes the event to the right viewer/state unit when a host mounts many viewers on one session. */
+            source: string;
+            /** @description One or more W3C selectors */
+            selector: components["schemas"]["TextPositionSelector"] | components["schemas"]["TextQuoteSelector"] | components["schemas"]["SvgSelector"] | components["schemas"]["FragmentSelector"] | (components["schemas"]["TextPositionSelector"] | components["schemas"]["TextQuoteSelector"] | components["schemas"]["SvgSelector"] | components["schemas"]["FragmentSelector"])[];
+            motivation: components["schemas"]["Motivation"];
+        };
+        /** @description Emitted when a mark is submitted with its annotation body */
+        MarkSubmitEvent: {
+            /** @description The '@id' of the resource the mark belongs to (W3C target.source). Routes the submit to the state unit bound to that resource — without it, N mounted units each create the annotation (N copies on N resources). */
+            source: string;
+            motivation: components["schemas"]["Motivation"];
+            /** @description One or more W3C selectors */
+            selector: components["schemas"]["TextPositionSelector"] | components["schemas"]["TextQuoteSelector"] | components["schemas"]["SvgSelector"] | components["schemas"]["FragmentSelector"] | (components["schemas"]["TextPositionSelector"] | components["schemas"]["TextQuoteSelector"] | components["schemas"]["SvgSelector"] | components["schemas"]["FragmentSelector"])[];
+            /** @description Optional body. Omit for annotations whose motivation alone is meaningful (e.g. highlighting) or whose user-supplied content is empty (e.g. an assessing annotation saved without comment text). Shape matches Annotation.body. */
+            body?: components["schemas"]["AnnotationBody"] | components["schemas"]["AnnotationBody"][];
+        };
+        /** @description Bus command to unarchive a previously archived resource. */
+        MarkUnarchiveCommand: {
+            /** @description Correlation id for request/reply matching, set by the SDK's busRequest so the confirmed-write ack/failure routes back. */
+            correlationId?: string;
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
+            resourceId: string;
+            storageUri?: string;
+        };
+        /** @description Bus command to update an annotation's body with patch operations. */
+        MarkUpdateBodyCommand: {
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
+            /** @description Correlation id threaded from the originating route through to event metadata. Lets the events-stream deliver matched results to the client that initiated the bind. */
+            correlationId?: string;
+            annotationId: string;
+            resourceId: string;
+            operations: (components["schemas"]["BodyOperationAdd"] | components["schemas"]["BodyOperationRemove"] | components["schemas"]["BodyOperationReplace"])[];
+        };
+        /** @description Bus command to replace the entity types on a resource. */
+        MarkUpdateEntityTypesCommand: {
+            /** @description Correlation id for request/reply matching, set by the SDK's busRequest so the confirmed-write ack/failure routes back. */
+            correlationId?: string;
+            resourceId: string;
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
+            currentEntityTypes: string[];
+            updatedEntityTypes: string[];
+        };
+        /** @description Request payload sent on the match:search-request bus channel to find candidate matches. */
+        MatchSearchRequest: {
+            /** @description Client-generated correlation ID to thread the response back to the originating request */
+            correlationId: string;
+            /** @description Resource ID the reference annotation belongs to. Used to scope result events on the EventBus so the events-stream delivers them to participants viewing this resource. */
+            resourceId: string;
+            /** @description Annotation ID of the reference to search candidates for */
+            referenceId: string;
+            /** @description Gathered context for the reference annotation */
+            context: components["schemas"]["GatheredContext"];
+            /** @description Maximum number of candidate results to return */
+            limit?: number;
+            /** @description Enable semantic similarity scoring in addition to keyword matching */
+            useSemanticScoring?: boolean;
+        };
+        MediaTokenRequest: {
+            /** @description The resource ID to generate a media token for */
+            resourceId: string;
+        };
+        MediaTokenResponse: {
+            /** @description Short-lived media token for use as ?token= query parameter on resource URLs */
+            token: string;
+        };
+        /** @description Emitted when the hover delay setting changes */
+        SettingsHoverDelayChangedEvent: {
+            hoverDelayMs: number;
+        };
+        /** @description Emitted when the UI locale setting changes */
+        SettingsLocaleChangedEvent: {
+            locale: string;
+        };
+        /** @description Emitted when the UI theme setting changes */
+        SettingsThemeChangedEvent: {
+            /** @enum {string} */
+            theme: "light" | "dark" | "system";
+        };
+        SvgSelector: {
+            /** @enum {string} */
+            type: "SvgSelector";
+            /** @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;
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
+            token: string;
+            name: string;
+            content: string;
+            archiveOriginal?: boolean;
+        };
+        /** @description Success response after creating a cloned resource. */
+        YieldCloneCreated: {
+            correlationId: string;
+            response: {
+                resourceId: string;
+            };
+        };
+        /** @description Bus command to request cloning a resource using a clone token. */
+        YieldCloneResourceRequest: {
+            correlationId: string;
+            token: string;
+        };
+        /** @description Bus command to request a clone token for a resource. */
+        YieldCloneTokenRequest: {
+            correlationId: string;
+            resourceId: string;
+        };
+        /** @description Bus command to create a yielded resource in the knowledge base. */
+        YieldCreateCommand: {
+            /** @description Correlation id for request/reply matching, set by busRequest so the yield:create-ok / yield:create-failed reply routes back to the awaiting caller. */
+            correlationId?: string;
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
+            name: string;
+            storageUri: string;
+            contentChecksum: string;
+            byteSize: number;
+            format: components["schemas"]["ContentFormat"];
+            language?: string;
+            entityTypes?: string[];
+            isDraft?: boolean;
+            generatedFrom?: {
+                resourceId?: string;
+                annotationId?: string;
+            };
+            generationPrompt?: string;
+            generator?: components["schemas"]["Agent"] | components["schemas"]["Agent"][];
+            noGit?: boolean;
+        };
+        /** @description Success reply after creating a yielded resource, matched to the originating command by correlationId. */
+        YieldCreateOk: {
+            /** @description Correlation id echoed from the yield:create command so busRequest can match the reply. */
+            correlationId?: string;
+            /** @description The created resource's identity. */
+            response: {
+                resourceId: string;
+            };
+        };
+        /** @description Bus command to move (rename) a yielded resource. */
+        YieldMvCommand: {
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
+            fromUri: string;
+            toUri: string;
+            noGit?: boolean;
+        };
+        /** @description Bus command to update a yielded resource's storage content. */
+        YieldUpdateCommand: {
+            /** @description Correlation id for request/reply matching, set by busRequest so the yield:update-ok / yield:update-failed reply routes back to the awaiting caller. */
+            correlationId?: string;
+            /** @description Authenticated user's DID, injected by the /bus/emit gateway. Clients do not set this. */
+            _userId?: string;
+            resourceId: string;
+            storageUri: string;
+            contentChecksum: string;
+            byteSize: number;
+            noGit?: boolean;
+        };
+        /** @description Success reply after updating a yielded resource, matched to the originating command by correlationId. */
+        YieldUpdateOk: {
+            /** @description Correlation id echoed from the yield:update command so busRequest can match the reply. */
+            correlationId?: string;
+            /** @description The updated resource's identity. */
+            response: {
+                resourceId: string;
+            };
+        };
+    };
+    responses: never;
+    parameters: never;
+    requestBodies: never;
+    headers: never;
+    pathItems: never;
+}
+
+/**
+ * Branded string types for compile-time type safety
+ *
+ * These types are zero-cost at runtime but prevent mixing
+ * different string types at compile time.
+ */
+
+type BaseUrl = string & {
+    readonly __brand: 'BaseUrl';
+};
+
+/**
+ * Branded identifier types for compile-time type safety.
+ *
+ * These types prevent mixing up resource IDs, annotation IDs, and user IDs
+ * at compile time while having zero runtime overhead.
+ *
+ * URI types (ResourceUri, AnnotationUri) are in @semiont/http-transport
+ * since they deal with HTTP URIs returned by the API.
+ */
+type ResourceId = string & {
+    readonly __brand: 'ResourceId';
+};
+type AnnotationId = string & {
+    readonly __brand: 'AnnotationId';
+};
+type UserId = string & {
+    readonly __brand: 'UserId';
+};
+
+/**
+ * Annotation types
+ */
+
+type RawAnnotation = components['schemas']['Annotation'];
+/**
+ * Domain-level Annotation type. Same shape as the OpenAPI-generated
+ * `components['schemas']['Annotation']`, but with a branded `AnnotationId`
+ * for the `id` field. Use this import everywhere the codebase refers to
+ * "an annotation"; the raw OpenAPI type is only used inside
+ * `@semiont/http-transport` at the HTTP boundary.
+ *
+ * Implemented by intersection (not `Omit`) to be robust against generator
+ * drift — if the OpenAPI schema gets `additionalProperties: true` added,
+ * `Omit` on the resulting intersection type silently drops named fields.
+ */
+type Annotation = RawAnnotation & {
+    id: AnnotationId;
+};
+
+/**
+ * Persisted Events
+ *
+ * The event types that get appended to the JSONL event log.
+ * Each maps a type string to its OpenAPI payload schema.
+ * The PersistedEvent union derives from this catalog.
+ */
+
+type AnnotationAddedPayload = components['schemas']['AnnotationAddedPayload'] & {
+    annotation: Annotation;
+};
+type AnnotationRemovedPayload = components['schemas']['AnnotationRemovedPayload'] & {
+    annotationId: AnnotationId;
+};
+type AnnotationBodyUpdatedPayload = components['schemas']['AnnotationBodyUpdatedPayload'] & {
+    annotationId: AnnotationId;
+};
+/**
+ * Maps each persisted event type string to its OpenAPI payload schema.
+ * Single source of truth for "what events get written to the log."
+ */
+type PersistedEventCatalog = {
+    'yield:created': components['schemas']['ResourceCreatedPayload'];
+    'yield:cloned': components['schemas']['ResourceClonedPayload'];
+    'yield:updated': components['schemas']['ResourceUpdatedPayload'];
+    'yield:moved': components['schemas']['ResourceMovedPayload'];
+    'yield:representation-added': components['schemas']['RepresentationAddedPayload'];
+    'yield:representation-removed': components['schemas']['RepresentationRemovedPayload'];
+    'mark:added': AnnotationAddedPayload;
+    'mark:removed': AnnotationRemovedPayload;
+    'mark:body-updated': AnnotationBodyUpdatedPayload;
+    'mark:archived': components['schemas']['ResourceArchivedPayload'];
+    'mark:unarchived': components['schemas']['ResourceUnarchivedPayload'];
+    'mark:entity-tag-added': components['schemas']['EntityTagChangedPayload'];
+    'mark:entity-tag-removed': components['schemas']['EntityTagChangedPayload'];
+    '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 = '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;
+    payload: PersistedEventCatalog[K];
+} : EventBase & {
+    type: K;
+    resourceId: ResourceId;
+    payload: PersistedEventCatalog[K];
+};
+/** The union of all persisted event types. Discriminated on `type`. */
+type PersistedEvent = {
+    [K in keyof PersistedEventCatalog]: EventOfType<K>;
+}[keyof PersistedEventCatalog];
+type PersistedEventType = PersistedEvent['type'];
+
+/**
+ * Event Base Types
+ *
+ * Core shapes for the event-sourced persistence model.
+ * EventBase is the common shape for all domain events.
+ * StoredEvent wraps an event with persistence metadata.
+ *
+ * These types are referenced by event-catalog.ts (domain events)
+ * and bus-protocol.ts (the full EventMap).
+ */
+
+/** Fields common to ALL domain events (system and resource-scoped). */
+interface EventBase {
+    id: string;
+    timestamp: string;
+    resourceId?: ResourceId;
+    userId: UserId;
+    version: number;
+}
+/** Persistence metadata attached to every stored event. */
+type EventMetadata = components['schemas']['EventMetadata'];
+/** Optional cryptographic signature on a stored event. */
+interface EventSignature {
+    algorithm: 'ed25519';
+    publicKey: string;
+    signature: string;
+    keyId?: string;
+}
+/**
+ * A domain event with persistence metadata.
+ * Flat intersection — no nesting (event.type, not event.event.type).
+ */
+type StoredEvent<T extends EventBase = PersistedEvent> = T & {
+    metadata: EventMetadata;
+    signature?: EventSignature;
+};
+
+/**
+ * Bus Protocol
+ *
+ * The complete EventMap for the RxJS EventBus. Every channel name and
+ * its payload type is defined here — domain events, commands, reads,
+ * results, SSE stream payloads, and frontend UI events.
+ *
+ * Identifier discipline: where a payload carries an annotation or
+ * resource id, the TypeScript layer narrows the OpenAPI `string` to the
+ * branded type (`AnnotationId`, `ResourceId`, `UserId`). The runtime
+ * wire shape is unchanged (brands have no runtime representation);
+ * what this buys us is that command handlers don't have to re-brand
+ * at every seam. Brand once at the entry boundary (HTTP route handler,
+ * DOM attribute read, URL param parse), not at every bus hop in
+ * between. See `.plans/BRAND-UPSTREAM.md` for the rationale.
+ *
+ * Organized by flow (verb), then by category within each flow.
+ */
+
+type MarkDeleteCommand = components['schemas']['MarkDeleteCommand'] & {
+    annotationId: AnnotationId;
+    resourceId?: ResourceId;
+};
+type MarkUpdateBodyCommand = components['schemas']['MarkUpdateBodyCommand'] & {
+    annotationId: AnnotationId;
+    resourceId: ResourceId;
+};
+type BindInitiateCommand = components['schemas']['BindInitiateCommand'] & {
+    annotationId: AnnotationId;
+    resourceId: ResourceId;
+};
+type BindUpdateBodyCommand = components['schemas']['BindUpdateBodyCommand'] & {
+    annotationId: AnnotationId;
+    resourceId: ResourceId;
+};
+/**
+ * The unified EventMap — every channel on the EventBus.
+ *
+ * Convention:
+ * - Domain events (past tense): StoredEvent<Interface> — branded types
+ * - Commands/reads/results/UI: OpenAPI schema refs — plain strings
+ * - void: UI-only signals with no payload
+ */
+type EventMap = {
+    'yield:created': StoredEvent<EventOfType<'yield:created'>>;
+    'yield:cloned': StoredEvent<EventOfType<'yield:cloned'>>;
+    'yield:updated': StoredEvent<EventOfType<'yield:updated'>>;
+    'yield:moved': StoredEvent<EventOfType<'yield:moved'>>;
+    'yield:representation-added': StoredEvent<EventOfType<'yield:representation-added'>>;
+    'yield:representation-removed': StoredEvent<EventOfType<'yield:representation-removed'>>;
+    'yield:create': components['schemas']['YieldCreateCommand'];
+    'yield:update': components['schemas']['YieldUpdateCommand'];
+    'yield:mv': components['schemas']['YieldMvCommand'];
+    'yield:clone': void;
+    'yield:clone-token-requested': components['schemas']['YieldCloneTokenRequest'];
+    'yield:clone-resource-requested': components['schemas']['YieldCloneResourceRequest'];
+    'yield:clone-create': components['schemas']['YieldCloneCreateCommand'];
+    'yield:create-ok': components['schemas']['YieldCreateOk'];
+    'yield:create-failed': components['schemas']['CommandError'];
+    'yield:update-ok': components['schemas']['YieldUpdateOk'];
+    'yield:update-failed': components['schemas']['CommandError'];
+    'yield:move-failed': {
+        fromUri: string;
+    } & components['schemas']['CommandError'];
+    'yield:clone-token-generated': {
+        correlationId: string;
+        response: components['schemas']['CloneResourceWithTokenResponse'];
+    };
+    'yield:clone-token-failed': {
+        correlationId: string;
+    } & components['schemas']['CommandError'];
+    'yield:clone-resource-result': {
+        correlationId: string;
+        response: components['schemas']['GetResourceByTokenResponse'];
+    };
+    'yield:clone-resource-failed': {
+        correlationId: string;
+    } & components['schemas']['CommandError'];
+    'yield:clone-created': components['schemas']['YieldCloneCreated'];
+    'yield:clone-create-failed': {
+        correlationId: string;
+    } & components['schemas']['CommandError'];
+    'mark:added': StoredEvent<EventOfType<'mark:added'>>;
+    'mark:removed': StoredEvent<EventOfType<'mark:removed'>>;
+    '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:archived': StoredEvent<EventOfType<'mark:archived'>>;
+    'mark:unarchived': StoredEvent<EventOfType<'mark:unarchived'>>;
+    'mark:create-request': components['schemas']['MarkCreateRequest'];
+    'mark:create': components['schemas']['MarkCreateCommand'];
+    'mark:delete': MarkDeleteCommand;
+    'mark:update-body': MarkUpdateBodyCommand;
+    'mark:archive': components['schemas']['MarkArchiveCommand'];
+    'mark:unarchive': components['schemas']['MarkUnarchiveCommand'];
+    'mark:update-entity-types': components['schemas']['MarkUpdateEntityTypesCommand'];
+    '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:archive-ok': {
+        correlationId?: string;
+    };
+    'mark:archive-failed': components['schemas']['CommandError'];
+    'mark:unarchive-ok': {
+        correlationId?: string;
+    };
+    'mark:unarchive-failed': components['schemas']['CommandError'];
+    'mark:update-entity-types-ok': {
+        correlationId?: string;
+    };
+    'mark:update-entity-types-failed': components['schemas']['CommandError'];
+    'mark:body-update-failed': components['schemas']['CommandError'];
+    'mark:select-comment': components['schemas']['SelectionData'];
+    'mark:select-tag': components['schemas']['SelectionData'];
+    'mark:select-assessment': components['schemas']['SelectionData'];
+    'mark:select-reference': components['schemas']['SelectionData'];
+    'mark:requested': components['schemas']['MarkRequestedEvent'];
+    'mark:cancel-pending': void;
+    'mark:submit': components['schemas']['MarkSubmitEvent'];
+    'mark:assist-request': components['schemas']['MarkAssistRequestEvent'];
+    'mark:assist-cancelled': void;
+    'mark:progress-dismiss': void;
+    '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-ok': {
+        correlationId?: string;
+    };
+    'frame:entity-type-add-failed': components['schemas']['CommandError'];
+    'frame:tag-schema-add-ok': {
+        correlationId?: string;
+    };
+    'frame:tag-schema-add-failed': components['schemas']['CommandError'];
+    'bind:initiate': BindInitiateCommand;
+    'bind:update-body': BindUpdateBodyCommand;
+    'bind:body-updated': components['schemas']['BindBodyUpdated'];
+    'bind:body-update-failed': components['schemas']['CommandError'];
+    'match:search-requested': components['schemas']['MatchSearchRequest'];
+    'match:search-results': components['schemas']['MatchSearchResult'];
+    'match:search-failed': components['schemas']['MatchSearchFailed'];
+    'gather:requested': components['schemas']['GatherAnnotationRequest'];
+    'gather:complete': components['schemas']['GatherAnnotationComplete'];
+    'gather:failed': {
+        correlationId: string;
+        annotationId: string;
+    } & components['schemas']['CommandError'];
+    'gather:resource-requested': components['schemas']['GatherResourceRequest'];
+    'gather:resource-complete': components['schemas']['GatherResourceComplete'];
+    'gather:resource-failed': {
+        correlationId: string;
+        resourceId: string;
+    } & components['schemas']['CommandError'];
+    'gather:summary-requested': components['schemas']['GatherSummaryRequest'];
+    'gather:summary-result': {
+        correlationId: string;
+        response: Record<string, unknown>;
+    };
+    'gather:summary-failed': {
+        correlationId: string;
+    } & components['schemas']['CommandError'];
+    'gather:annotation-progress': components['schemas']['GatherProgress'];
+    'browse:resource-requested': components['schemas']['BrowseResourceRequest'];
+    'browse:resource-result': components['schemas']['BrowseResourceResult'];
+    'browse:resource-failed': {
+        correlationId: string;
+    } & components['schemas']['CommandError'];
+    'browse:resources-requested': components['schemas']['BrowseResourcesRequest'];
+    'browse:resources-result': components['schemas']['BrowseResourcesResult'];
+    'browse:resources-failed': {
+        correlationId: string;
+    } & components['schemas']['CommandError'];
+    'browse:annotations-requested': components['schemas']['BrowseAnnotationsRequest'];
+    'browse:annotations-result': components['schemas']['BrowseAnnotationsResult'];
+    'browse:annotations-failed': {
+        correlationId: string;
+    } & components['schemas']['CommandError'];
+    'browse:annotation-requested': components['schemas']['BrowseAnnotationRequest'];
+    'browse:annotation-result': components['schemas']['BrowseAnnotationResult'];
+    'browse:annotation-failed': {
+        correlationId: string;
+    } & components['schemas']['CommandError'];
+    'browse:events-requested': components['schemas']['BrowseEventsRequest'];
+    'browse:events-result': components['schemas']['BrowseEventsResult'];
+    'browse:events-failed': {
+        correlationId: string;
+    } & components['schemas']['CommandError'];
+    'browse:annotation-history-requested': components['schemas']['BrowseAnnotationHistoryRequest'];
+    'browse:annotation-history-result': components['schemas']['BrowseAnnotationHistoryResult'];
+    'browse:annotation-history-failed': {
+        correlationId: string;
+    } & components['schemas']['CommandError'];
+    'browse:annotation-context-requested': components['schemas']['BrowseAnnotationContextRequest'];
+    'browse:annotation-context-result': {
+        correlationId: string;
+        response: Record<string, unknown>;
+    };
+    'browse:annotation-context-failed': {
+        correlationId: string;
+    } & components['schemas']['CommandError'];
+    'browse:referenced-by-requested': components['schemas']['BrowseReferencedByRequest'];
+    'browse:referenced-by-result': components['schemas']['BrowseReferencedByResult'];
+    'browse:referenced-by-failed': {
+        correlationId: string;
+    } & components['schemas']['CommandError'];
+    'browse:entity-types-requested': components['schemas']['BrowseEntityTypesRequest'];
+    'browse:entity-types-result': components['schemas']['BrowseEntityTypesResult'];
+    '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:agents-requested': components['schemas']['BrowseAgentsRequest'];
+    'browse:agents-result': components['schemas']['BrowseAgentsResult'];
+    'browse:agents-failed': {
+        correlationId: string;
+    } & components['schemas']['CommandError'];
+    'browse:directory-requested': components['schemas']['BrowseDirectoryRequest'];
+    'browse:directory-result': components['schemas']['BrowseDirectoryResult'];
+    'browse:directory-failed': {
+        correlationId: string;
+        path: string;
+    } & components['schemas']['CommandError'];
+    'browse:click': components['schemas']['BrowseClickEvent'];
+    'browse:reference-navigate': components['schemas']['BrowseReferenceNavigateEvent'];
+    'browse:entity-type-clicked': components['schemas']['BrowseEntityTypeClickedEvent'];
+    'panel:toggle': components['schemas']['BrowsePanelToggleEvent'];
+    'panel:open': components['schemas']['BrowsePanelOpenEvent'];
+    'panel:close': void;
+    'shell:sidebar-toggle': void;
+    'tabs:close': components['schemas']['BrowseResourceCloseEvent'];
+    'tabs:reorder': components['schemas']['BrowseResourceReorderEvent'];
+    'nav:link-clicked': components['schemas']['BrowseLinkClickedEvent'];
+    'nav:push': components['schemas']['BrowseRouterPushEvent'];
+    'nav:external': components['schemas']['BrowseExternalNavigateEvent'] & {
+        cancelFallback: () => void;
+    };
+    'beckon:hover': components['schemas']['BeckonHoverEvent'];
+    'beckon:focus': components['schemas']['BeckonFocusEvent'];
+    'beckon:sparkle': components['schemas']['BeckonSparkleEvent'];
+    'job:started': StoredEvent<EventOfType<'job:started'>>;
+    'job:progress': StoredEvent<EventOfType<'job:progress'>>;
+    'job:completed': StoredEvent<EventOfType<'job:completed'>>;
+    'job:failed': StoredEvent<EventOfType<'job:failed'>>;
+    'job:start': components['schemas']['JobStartCommand'];
+    'job:report-progress': components['schemas']['JobReportProgressCommand'];
+    'job:complete': components['schemas']['JobCompleteCommand'];
+    'job:fail': components['schemas']['JobFailCommand'];
+    'job:queued': components['schemas']['JobQueuedEvent'];
+    'job:cancel-requested': components['schemas']['JobCancelRequest'];
+    'job:status-requested': components['schemas']['JobStatusRequest'];
+    'job:create': components['schemas']['JobCreateCommand'];
+    'job:claim': components['schemas']['JobClaimCommand'];
+    'job:status-result': components['schemas']['JobStatusResult'];
+    'job:status-failed': {
+        correlationId: string;
+    } & components['schemas']['CommandError'];
+    'job:created': components['schemas']['JobCreatedResult'];
+    'job:create-failed': {
+        correlationId: string;
+    } & components['schemas']['CommandError'];
+    'job:claimed': {
+        correlationId: string;
+        response: Record<string, unknown>;
+    };
+    'job:claim-failed': {
+        correlationId: string;
+    } & components['schemas']['CommandError'];
+    'job:cancel-ok': {
+        correlationId?: string;
+        response: {
+            cancelled: number;
+        };
+    };
+    'job:cancel-failed': components['schemas']['CommandError'];
+    'settings:theme-changed': components['schemas']['SettingsThemeChangedEvent'];
+    'settings:line-numbers-toggled': void;
+    'settings:locale-changed': components['schemas']['SettingsLocaleChangedEvent'];
+    'settings:hover-delay-changed': components['schemas']['SettingsHoverDelayChangedEvent'];
+    'stream-connected': Record<string, never>;
+    'replay-window-exceeded': {
+        resourceId?: string;
+        lastEventId: number;
+        missedCount: number;
+        cap: number;
+        message: string;
+    };
+    /**
+     * Emitted by the `/bus/subscribe` handler when a client reconnected
+     * with `Last-Event-ID: p-<scope>-<seq>` but the server could not
+     * replay all missed persisted events for that scope (retention
+     * window exceeded, scope unknown, or request unparseable). The
+     * client should treat this as a signal to fall back to the pre-
+     * resumption contract: invalidate caches for the affected scope
+     * and re-read from scratch. Analogous to `replay-window-exceeded`
+     * but scoped to the bus gateway rather than the per-resource
+     * events stream.
+     *
+     * `scope` is the scope string the client asked about (omitted for
+     * global-persisted resumption gaps, if that path ever exists).
+     * `reason` is human-readable, for logging.
+     */
+    'bus:resume-gap': {
+        scope?: string;
+        lastSeenId?: string;
+        reason: string;
+    };
+};
+
+/**
+ * RxJS-based Event Bus
+ *
+ * Framework-agnostic event bus providing direct access to typed RxJS Subjects.
+ *
+ * Can be used in Node.js, browser, workers, CLI - anywhere RxJS runs.
+ */
+
+/**
+ * RxJS-based event bus
+ *
+ * Provides direct access to RxJS Subjects for each event type.
+ * Use standard RxJS patterns for emitting and subscribing.
+ *
+ * @example
+ * ```typescript
+ * const eventBus = new EventBus();
+ *
+ * // Emit events
+ * eventBus.get('beckon:hover').next({ annotationId: 'ann-1' });
+ *
+ * // Subscribe to events
+ * const subscription = eventBus.get('beckon:hover').subscribe(({ annotationId }) => {
+ *   console.log('Hover:', annotationId);
+ * });
+ *
+ * // Use RxJS operators
+ * import { debounceTime } from 'rxjs/operators';
+ * eventBus.get('beckon:hover')
+ *   .pipe(debounceTime(100))
+ *   .subscribe(handleHover);
+ *
+ * // Cleanup
+ * subscription.unsubscribe();
+ * eventBus.destroy();
+ * ```
+ */
+declare class EventBus {
+    private subjects;
+    private isDestroyed;
+    constructor();
+    /**
+     * Get the RxJS Subject for an event
+     *
+     * Returns a typed Subject that can be used with all RxJS operators.
+     * Subjects are created lazily on first access.
+     *
+     * @param eventName - The event name
+     * @returns The RxJS Subject for this event
+     *
+     * @example
+     * ```typescript
+     * // Emit
+     * eventBus.get('beckon:hover').next({ annotationId: 'ann-1' });
+     *
+     * // Subscribe
+     * const sub = eventBus.get('beckon:hover').subscribe(handleHover);
+     *
+     * // With operators
+     * eventBus.get('beckon:hover')
+     *   .pipe(debounceTime(100), distinctUntilChanged())
+     *   .subscribe(handleHover);
+     * ```
+     */
+    get<K extends keyof EventMap>(eventName: K): Subject<EventMap[K]>;
+    /**
+     * Get the RxJS Subject for a domain event type (PersistedEventType).
+     *
+     * Domain event channels carry `StoredEvent`. This method avoids the need
+     * for `as keyof EventMap` casts when subscribing to domain event channels
+     * using runtime `PersistedEventType` strings.
+     */
+    getDomainEvent(eventType: PersistedEventType): Subject<StoredEvent>;
+    /**
+     * Destroy the event bus and complete all subjects
+     *
+     * After calling destroy(), no new events can be emitted or subscribed to.
+     * All active subscriptions will be completed.
+     */
+    destroy(): void;
+    /**
+     * Check if the event bus has been destroyed
+     */
+    get destroyed(): boolean;
+    /**
+     * Create a resource-scoped event bus
+     *
+     * Events emitted or subscribed through the scoped bus are isolated to that resource.
+     * Internally, events are namespaced but the API remains identical to the parent bus.
+     *
+     * @param resourceId - Resource identifier to scope events to
+     * @returns A scoped event bus for this resource
+     *
+     * @example
+     * ```typescript
+     * const eventBus = new EventBus();
+     * const resource1 = eventBus.scope('resource-1');
+     * const resource2 = eventBus.scope('resource-2');
+     *
+     * // These are isolated - only resource1 subscribers will fire
+     * resource1.get('detection:progress').next({ status: 'started' });
+     * ```
+     */
+    scope(resourceId: string): ScopedEventBus;
+}
+/**
+ * Resource-scoped event bus
+ *
+ * Provides isolated event streams per resource while maintaining the same API
+ * as the parent EventBus. Events are internally namespaced by resourceId.
+ */
+declare class ScopedEventBus {
+    private parent;
+    private scopePrefix;
+    constructor(parent: EventBus, scopePrefix: string);
+    /**
+     * Get the RxJS Subject for a scoped event
+     *
+     * Returns the same type as the parent bus, but events are isolated to this scope.
+     * Internally uses namespaced keys but preserves type safety.
+     *
+     * @param event - The event name
+     * @returns The RxJS Subject for this scoped event
+     */
+    get<E extends keyof EventMap>(event: E): Subject<EventMap[E]>;
+    /** Get the RxJS Subject for a domain event type on this scoped bus. */
+    getDomainEvent(eventType: PersistedEventType): Subject<StoredEvent>;
+    /**
+     * Create a nested scope
+     *
+     * Allows hierarchical scoping like `resource-1:subsystem-a`
+     *
+     * @param subScope - Additional scope level
+     * @returns A nested scoped event bus
+     */
+    scope(subScope: string): ScopedEventBus;
+}
+
+/**
+ * Transport interfaces — the shared contract for any wire-or-local
+ * communication path consumed by `SemiontClient`. Concrete implementations
+ * live alongside the runtime they wrap (`HttpTransport` in
+ * `@semiont/http-transport`, in-process variants in `@semiont/make-meaning`,
+ * etc.).
+ *
+ * Three interfaces:
+ *
+ *   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 `docs/protocol/TRANSPORT-CONTRACT.md`.
+ */
+
+/**
+ * Six-state lifecycle for a transport's connection. Drives UI affordances
+ * (connecting spinners, reconnecting banners, etc.) and is observed via
+ * `ITransport.state$`.
+ *
+ *   initial      ─ pre-`start()`; never enters subscribers' streams
+ *                  except as the first replayed value
+ *   connecting   ─ in-flight initial open
+ *   open         ─ healthy, delivering events
+ *   reconnecting ─ open → dropped, retrying; may be transient
+ *   degraded     ─ has been reconnecting for > DEGRADED_THRESHOLD_MS;
+ *                  UI banner threshold; distinguishes brief mount-
+ *                  churn cycles from sustained disconnection
+ *   closed       ─ stop()/dispose() called; terminal
+ */
+type ConnectionState = 'initial' | 'connecting' | 'open' | 'reconnecting' | 'degraded' | 'closed';
+interface ITransport {
+    /**
+     * Base URL the transport speaks to. For HTTP this is `https://host[:port]`;
+     * for in-process transports, an opaque identifier (e.g. `local://kb-id`).
+     */
+    readonly baseUrl: BaseUrl;
+    /**
+     * Publish a payload on the named channel.
+     *
+     * `resourceScope`, when set, marks the emit as a resource-scoped
+     * broadcast — only delivered to subscribers attached to that
+     * resource's scope.
+     */
+    emit<K extends keyof EventMap>(channel: K, payload: EventMap[K], resourceScope?: ResourceId): Promise<void>;
+    on<K extends keyof EventMap>(channel: K, handler: (payload: EventMap[K]) => void): () => void;
+    stream<K extends keyof EventMap>(channel: K): Observable<EventMap[K]>;
+    /**
+     * Subscribe to a resource-scoped channel set. HTTP attaches a scope to
+     * its SSE connection; in-process transports may be a no-op because
+     * local events are delivered without scoping.
+     *
+     * Returns a disposer that detaches the scope when the last subscriber
+     * unsubscribes (ref-counted).
+     *
+     * 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`).
+     */
+    subscribeToResource(resourceId: ResourceId): () => void;
+    /**
+     * Hand the given bus to the transport so the transport can publish
+     * the events it receives into it. The reference flows
+     * client → transport (the client owns the bus); transports never
+     * construct or replace it. Concrete transports decide what "receives"
+     * means: HTTP bridges every channel it observes on its SSE wire;
+     * 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;
+}
+
+declare const BUS_OPERATIONS: {
+    readonly 'bind:update-body': {
+        readonly result: "bind:body-updated";
+        readonly failure: "bind:body-update-failed";
+    };
+    readonly 'browse:resource-requested': {
+        readonly result: "browse:resource-result";
+        readonly failure: "browse:resource-failed";
+    };
+    readonly 'browse:resources-requested': {
+        readonly result: "browse:resources-result";
+        readonly failure: "browse:resources-failed";
+    };
+    readonly 'browse:annotation-requested': {
+        readonly result: "browse:annotation-result";
+        readonly failure: "browse:annotation-failed";
+    };
+    readonly 'browse:annotations-requested': {
+        readonly result: "browse:annotations-result";
+        readonly failure: "browse:annotations-failed";
+    };
+    readonly 'browse:annotation-history-requested': {
+        readonly result: "browse:annotation-history-result";
+        readonly failure: "browse:annotation-history-failed";
+    };
+    readonly 'browse:events-requested': {
+        readonly result: "browse:events-result";
+        readonly failure: "browse:events-failed";
+    };
+    readonly 'browse:referenced-by-requested': {
+        readonly result: "browse:referenced-by-result";
+        readonly failure: "browse:referenced-by-failed";
+    };
+    readonly 'browse:entity-types-requested': {
+        readonly result: "browse:entity-types-result";
+        readonly failure: "browse:entity-types-failed";
+    };
+    readonly 'browse:tag-schemas-requested': {
+        readonly result: "browse:tag-schemas-result";
+        readonly failure: "browse:tag-schemas-failed";
+    };
+    readonly 'browse:agents-requested': {
+        readonly result: "browse:agents-result";
+        readonly failure: "browse:agents-failed";
+    };
+    readonly 'browse:directory-requested': {
+        readonly result: "browse:directory-result";
+        readonly failure: "browse:directory-failed";
+    };
+    readonly 'browse:annotation-context-requested': {
+        readonly result: "browse:annotation-context-result";
+        readonly failure: "browse:annotation-context-failed";
+    };
+    readonly 'frame:add-entity-type': {
+        readonly result: "frame:entity-type-add-ok";
+        readonly failure: "frame:entity-type-add-failed";
+    };
+    readonly 'frame:add-tag-schema': {
+        readonly result: "frame:tag-schema-add-ok";
+        readonly failure: "frame:tag-schema-add-failed";
+    };
+    readonly 'gather:requested': {
+        readonly result: "gather:complete";
+        readonly failure: "gather:failed";
+        readonly progress: "gather:annotation-progress";
+    };
+    readonly 'gather:resource-requested': {
+        readonly result: "gather:resource-complete";
+        readonly failure: "gather:resource-failed";
+    };
+    readonly 'gather:summary-requested': {
+        readonly result: "gather:summary-result";
+        readonly failure: "gather:summary-failed";
+    };
+    readonly 'job:create': {
+        readonly result: "job:created";
+        readonly failure: "job:create-failed";
+    };
+    readonly 'job:status-requested': {
+        readonly result: "job:status-result";
+        readonly failure: "job:status-failed";
+    };
+    readonly 'job:cancel-requested': {
+        readonly result: "job:cancel-ok";
+        readonly failure: "job:cancel-failed";
+    };
+    readonly 'job:claim': {
+        readonly result: "job:claimed";
+        readonly failure: "job:claim-failed";
+    };
+    readonly 'mark:create-request': {
+        readonly result: "mark:create-ok";
+        readonly failure: "mark:create-failed";
+    };
+    readonly 'mark:delete': {
+        readonly result: "mark:delete-ok";
+        readonly failure: "mark:delete-failed";
+    };
+    readonly 'mark:archive': {
+        readonly result: "mark:archive-ok";
+        readonly failure: "mark:archive-failed";
+    };
+    readonly 'mark:unarchive': {
+        readonly result: "mark:unarchive-ok";
+        readonly failure: "mark:unarchive-failed";
+    };
+    readonly 'mark:update-entity-types': {
+        readonly result: "mark:update-entity-types-ok";
+        readonly failure: "mark:update-entity-types-failed";
+    };
+    readonly 'match:search-requested': {
+        readonly result: "match:search-results";
+        readonly failure: "match:search-failed";
+    };
+    readonly 'yield:create': {
+        readonly result: "yield:create-ok";
+        readonly failure: "yield:create-failed";
+    };
+    readonly 'yield:update': {
+        readonly result: "yield:update-ok";
+        readonly failure: "yield:update-failed";
+    };
+    readonly 'yield:clone-create': {
+        readonly result: "yield:clone-created";
+        readonly failure: "yield:clone-create-failed";
+    };
+    readonly 'yield:clone-resource-requested': {
+        readonly result: "yield:clone-resource-result";
+        readonly failure: "yield:clone-resource-failed";
+    };
+    readonly 'yield:clone-token-requested': {
+        readonly result: "yield:clone-token-generated";
+        readonly failure: "yield:clone-token-failed";
+    };
+};
+/** The request-channel key of a registered operation — what `busRequest` takes. */
+type BusOperationKey = keyof typeof BUS_OPERATIONS;
+
+/**
+ * FaultyTransport — a seeded, scriptable `ITransport` simulator for the
+ * liveness axioms (`.plans/LIVENESS-AXIOMS.md`). fast-check draws a fault
+ * schedule; the transport applies one `FaultAction` per request-channel emit
+ * and synthesizes replies from the `BUS_OPERATIONS` registry, so real
+ * compositions (`busRequest`, SWR caches, live queries) run unmodified against
+ * generated wire behavior no hand-written test names.
+ *
+ * Home is core (not sdk/test-utils) for the same reason as
+ * `assertStateUnitAxioms`: it needs only core types, and every layer —
+ * including `http-transport`, below sdk — can consume it via
+ * `@semiont/core/testing` without a dependency cycle.
+ *
+ * Deterministic-by-construction: no `Date.now`, no randomness of its own —
+ * all variation comes in through the schedule (fast-check owns the seed).
+ * Time is real `setTimeout` at millisecond scale; properties pass a small
+ * explicit `timeoutMs` to `busRequest`, so nothing waits 30 s.
+ */
+
+/** One wire behavior, applied to a single request-channel emit. */
+type FaultAction = {
+    kind: 'deliver';
+} | {
+    kind: 'drop-reply';
+} | {
+    kind: 'delay';
+    ms: number;
+} | {
+    kind: 'duplicate-reply';
+} | {
+    kind: 'reject-emit';
+};
+/**
+ * Scope-contention behavior of `subscribeToResource`:
+ * `single-slot-throw` mirrors today's HttpTransport (one distinct scope at a
+ * time; a second distinct scope throws); `multi` mirrors the
+ * post-MULTI-RESOURCE-SCOPE world. The same properties run under both so the
+ * migration can't silently change liveness behavior.
+ */
+type ScopeModel = 'single-slot-throw' | 'multi';
+/** requestLog entry — one per request-channel emit, in arrival order. */
+interface RequestLogEntry {
+    channel: BusOperationKey;
+    /** The action the schedule assigned to this emit. */
+    action: FaultAction;
+    correlationId: string | undefined;
+    /**
+     * Request identity for retry accounting: channel + payload minus the
+     * per-issue fields (`correlationId`, `_trace`, `_userId`). Two emits with
+     * the same key are the same logical request re-issued.
+     */
+    retryKey: string;
+}
+interface FaultyTransportConfig {
+    /**
+     * The i-th request-channel emit applies `schedule[i % schedule.length]`.
+     * Empty/omitted → every request delivers.
+     */
+    schedule?: readonly FaultAction[];
+    /** Default `'single-slot-throw'` (today's HttpTransport). */
+    scopeModel?: ScopeModel;
+    /**
+     * Synthesize the `response` value for a delivered reply. Return `undefined`
+     * for a void ack (`{ correlationId }` only). Default: `{}` for every op.
+     */
+    makeResponse?: (operation: BusOperationKey, payload: Record<string, unknown>) => unknown;
+}
+/** Stable request identity: channel + sorted payload minus per-issue fields. */
+declare function retryKeyOf(channel: string, payload: Record<string, unknown>): string;
+declare class FaultyTransport implements ITransport {
+    readonly baseUrl: BaseUrl;
+    readonly state$: BehaviorSubject<ConnectionState>;
+    private readonly errorsSubject;
+    readonly errors$: Observable<SemiontError>;
+    /** Every request-channel emit, in order — the L2 accounting surface. */
+    readonly requestLog: RequestLogEntry[];
+    private readonly bus;
+    private readonly schedule;
+    private readonly scopeModel;
+    private readonly makeResponse;
+    private requestCount;
+    private activeScope;
+    private scopeRefs;
+    private readonly timers;
+    private disposed;
+    constructor(cfg?: FaultyTransportConfig);
+    emit<K extends keyof EventMap>(channel: K, payload: EventMap[K], resourceScope?: ResourceId): Promise<void>;
+    on<K extends keyof EventMap>(channel: K, handler: (payload: EventMap[K]) => void): () => void;
+    stream<K extends keyof EventMap>(channel: K): Observable<EventMap[K]>;
+    subscribeToResource(rid: ResourceId): () => void;
+    bridgeInto(bus: EventBus): void;
+    dispose(): void;
+}
+
+/**
+ * Executable enforcement of the liveness axioms — the runtime twin of
+ * `.plans/LIVENESS-AXIOMS.md`, and the composition-level sibling of
+ * `assertStateUnitAxioms` (state-unit-axioms.ts). Where the StateUnit axioms
+ * make *per-unit* wrongness mechanically detectable, these make *silence*
+ * detectable: every existing enforcement tier is safety (nothing wrong is
+ * delivered); these assert liveness (something is eventually delivered).
+ *
+ * Axioms (fault-schedule dimension; fast-check):
+ *   L1  Subscriber liveness — every output emits next|error within the bound,
+ *       under any fault schedule. Error is a permitted outcome; the forbidden
+ *       fourth state is pending-forever.
+ *   L2  Request settlement — every awaited path settles within the bound;
+ *       re-issues per logical request stay within the retry budget (B14: one);
+ *       a faulted request must be re-issued or surfaced, never swallowed.
+ *   L3  Delivery across lifecycle transitions — every event written to a live
+ *       connection reaches the output exactly once, wherever a client-initiated
+ *       transition (handover / reconnect / scope change) lands. Retirement is
+ *       by drain, never by abort (TRANSPORT-HTTP.md, Abort discipline).
+ *
+ * Framework-agnostic on purpose — only `rxjs` + `fast-check`, no `vitest` — so
+ * it ships through `@semiont/core/testing` and any package's test runner can
+ * invoke it. Deterministic virtual time: properties pass a small explicit
+ * `timeoutMs` to `busRequest`; no `Date.now`, no 30 s real waits.
+ */
+
+/** What one fresh run of the composition exposes to the axioms. */
+interface LivenessScenario {
+    /**
+     * Live-query-shaped outputs. The harness subscribes each one; every
+     * subscription must see `next` or `error` within the bound (L1).
+     */
+    outputs: readonly Observable<unknown>[];
+    /**
+     * Awaited paths. Each promise must settle — resolve or reject — within the
+     * bound (L2). Rejections are fine; pending-forever is the violation.
+     */
+    settlements?: readonly Promise<unknown>[];
+    teardown?: () => void;
+}
+interface LivenessAxiomSpec {
+    /** Build a FRESH composition wired to the given transport. Called per run. */
+    setup: (transport: FaultyTransport) => LivenessScenario | Promise<LivenessScenario>;
+    /**
+     * The timeoutMs the scenario passes to `busRequest` — the bound is derived
+     * from it: (timeoutMs × (1 + retryBudget) + Σdelays) × slackFactor.
+     */
+    timeoutMs: number;
+    /** Max sanctioned re-issues per logical request (B14 budget). Default 1. */
+    retryBudget?: number;
+    /** Override the generated fault schedules (teeth tests pin one). */
+    scheduleArb?: fc.Arbitrary<readonly FaultAction[]>;
+    /** Scope model(s) to run under. Default `'single-slot-throw'`. */
+    scopeModel?: ScopeModel | 'both';
+    /** Passed through to FaultyTransport (reply synthesis). */
+    makeResponse?: (operation: string, payload: Record<string, unknown>) => unknown;
+    /** fast-check run budget (default 25 — CI-fast; crank locally). */
+    numRuns?: number;
+    /** Real-scheduler jitter headroom on the bound (default 4×). */
+    slackFactor?: number;
+}
+/** The five wire behaviors, uniformly weighted; delays stay small (≤5 ms). */
+declare function arbFaultAction(): fc.Arbitrary<FaultAction>;
+declare function arbFaultSchedule(maxLength?: number): fc.Arbitrary<readonly FaultAction[]>;
+/**
+ * Run L1 + L2 against `spec` across generated fault schedules. Throws a
+ * labeled Error (`L1: …` / `L2: …`) on the first violation.
+ */
+declare function assertLivenessAxioms(spec: LivenessAxiomSpec): Promise<void>;
+/**
+ * A connection-stream-shaped subject: something that accepts writes to the
+ * live connection, can be told to transition (handover / reconnect / scope
+ * change), and exposes the subscriber-facing output. P3 adapts the real
+ * actor's mock-connection harness to this shape; the teeth tests drive
+ * reconstructed pre-fix doubles.
+ */
+interface DeliverySubject {
+    /** Write the event with this id to the currently-live connection. */
+    write: (eventId: string) => void;
+    /** Client-initiated lifecycle transition. */
+    transition: () => void | Promise<void>;
+    /** Subscriber-facing output; each emission is a delivered event id. */
+    output$: Observable<string>;
+    /**
+     * Drain pending asynchronous delivery at end of sequence (a live connection
+     * eventually flushes). Default: one macrotask tick.
+     */
+    settle?: () => Promise<void>;
+    teardown?: () => void;
+}
+type DeliveryOp = 'write' | 'transition';
+interface DeliveryAxiomSpec {
+    /** Build a FRESH subject. Called per run. */
+    setup: () => DeliverySubject;
+    /** Override the generated op sequences (teeth tests pin one). */
+    opsArb?: fc.Arbitrary<readonly DeliveryOp[]>;
+    /** Max generated sequence length (default 12). */
+    maxOps?: number;
+    /** fast-check run budget (default 50 — these runs are cheap). */
+    numRuns?: number;
+}
+declare function arbDeliveryOps(maxOps?: number): fc.Arbitrary<readonly DeliveryOp[]>;
+/**
+ * Run L3 against `spec` across generated write/transition interleavings.
+ * Throws a labeled Error (`L3: …`) on the first violation: an event written
+ * to a live connection delivered zero times (lost — retired by abort instead
+ * of drain) or more than once (duplicate).
+ */
+declare function assertExactlyOnceDelivery(spec: DeliveryAxiomSpec): Promise<void>;
+
+export { FaultyTransport, arbDeliveryOps, arbFaultAction, arbFaultSchedule, assertExactlyOnceDelivery, assertLivenessAxioms, assertStateUnitAxioms, disposeProbe, retryKeyOf };
+export type { DeliveryAxiomSpec, DeliveryOp, DeliverySubject, DisposeProbe, FaultAction, FaultyTransportConfig, LivenessAxiomSpec, LivenessScenario, RequestLogEntry, ScopeModel, StateUnitAxiomSpec };