@semiont/make-meaning 0.4.20 → 0.4.22

package/dist/index.d.ts

@@ -1,12 +1,13 @@
-import { JobQueue, ReferenceAnnotationWorker, GenerationWorker, HighlightAnnotationWorker, AssessmentAnnotationWorker, CommentAnnotationWorker, TagAnnotationWorker } from '@semiont/jobs';
+import { JobQueue } from '@semiont/jobs';
 import { SemiontProject } from '@semiont/core/node';
-import { GraphServiceConfig, VectorsServiceConfig, EmbeddingServiceConfig, EventBus, Logger, StoredEvent, ResourceId, AnnotationId, components, UserId, CreationMethod, ResourceAnnotations, AnnotationCategory, GraphPath, GraphConnection } from '@semiont/core';
+import { GraphServiceConfig, VectorsServiceConfig, EmbeddingServiceConfig, EventBus, Logger, StoredEvent, ResourceId, ResourceDescriptor, AnnotationId, components, ITransport, BaseUrl, ConnectionState, UserDID, EventMap, Email, GoogleCredential, RefreshToken, UserResponse, ListUsersResponse, UpdateUserRequest, UpdateUserResponse, ProgressCallback, ProgressEvent, HealthCheckResponse, StatusResponse, IContentTransport, PutBinaryRequest, AccessToken, ContentFormat as ContentFormat$1, Annotation, UserId, CreationMethod, ResourceAnnotations, AnnotationCategory, GraphPath, GraphConnection } from '@semiont/core';
 export { AssembledAnnotation, applyBodyOperations, assembleAnnotation } from '@semiont/core';
 import { EventStore, ViewStorage } from '@semiont/event-sourcing';
 import { WorkingTreeStore } from '@semiont/content';
 import { GraphDatabase } from '@semiont/graph';
-import { VectorStore, EmbeddingProvider, ChunkingConfig } from '@semiont/vectors';
+import { VectorStore, EmbeddingProvider } from '@semiont/vectors';
 import { InferenceClient } from '@semiont/inference';
+import { BehaviorSubject, Observable } from 'rxjs';
 import { Writable, Readable } from 'node:stream';
 
 /**
@@ -79,8 +80,7 @@ interface MakeMeaningConfig {
  * per-resource serialization — the same invariant enforced by `Smelter`,
  * `Gatherer`, and (in a different shape) `ViewManager`. See
  * `packages/core/src/serialize-per-key.ts` for the shared primitive used
- * by RPC-style services, and `.plans/PerResourceSerializer.md` for the
- * broader design that would unify the two shapes.
+ * by RPC-style services.
  */
 
 declare class GraphDBConsumer {
@@ -156,157 +156,6 @@ declare class GraphDBConsumer {
     shutdown(): Promise<void>;
 }
 
-/**
- * EmbeddingStore
- *
- * Durable file-based cache for pre-computed embedding vectors.
- * Stored under .semiont/embeddings/ — committed to git alongside events,
- * but overwritten in place rather than appended.
- *
- * File layout (same 4-hex Jump Consistent Hash sharding as events):
- *
- *   .semiont/embeddings/{ab}/{cd}/{resourceId}.jsonl
- *     Line 0: { model, dimensions }                  ← model header
- *     Line N: { chunkIndex, text, embedding[] }       ← one chunk per line
- *
- *   .semiont/embeddings/{ab}/{cd}/{annotationId}.json
- *     { model, dimensions, resourceId, text, embedding[], motivation, entityTypes }
- *
- * rebuildAll() in Smelter reads these files and upserts into Qdrant without
- * calling the embedding provider — unless the stored model doesn't match the
- * configured provider, in which case the file is re-embedded and overwritten.
- */
-
-interface StoredChunk {
-    chunkIndex: number;
-    text: string;
-    embedding: number[];
-}
-interface ResourceEmbeddingFile {
-    model: string;
-    dimensions: number;
-    chunks: StoredChunk[];
-}
-interface AnnotationEmbeddingFile {
-    model: string;
-    dimensions: number;
-    resourceId: string;
-    text: string;
-    embedding: number[];
-    motivation: string;
-    entityTypes: string[];
-}
-declare class EmbeddingStore {
-    private readonly project;
-    constructor(project: SemiontProject);
-    private resourceFilePath;
-    private annotationFilePath;
-    writeResourceChunks(resourceId: ResourceId, model: string, dimensions: number, chunks: StoredChunk[]): Promise<void>;
-    readResourceEmbeddings(resourceId: ResourceId): Promise<ResourceEmbeddingFile | null>;
-    deleteResourceEmbeddings(resourceId: ResourceId): Promise<void>;
-    writeAnnotationEmbedding(annotationId: AnnotationId, resourceId: ResourceId, model: string, dimensions: number, text: string, embedding: number[], motivation: string, entityTypes: string[]): Promise<void>;
-    readAnnotationEmbedding(annotationId: AnnotationId): Promise<AnnotationEmbeddingFile | null>;
-    deleteAnnotationEmbedding(annotationId: AnnotationId): Promise<void>;
-    /**
-     * Scan embeddings directory and return all resource IDs (from *.jsonl files).
-     */
-    getAllResourceIds(): Promise<string[]>;
-    /**
-     * Scan embeddings directory and return all annotation IDs (from *.json files).
-     */
-    getAllAnnotationIds(): Promise<string[]>;
-    private scanIds;
-}
-
-/**
- * Smelter Actor
- *
- * Takes raw content, refines it into embedding vectors, persists them to the
- * EmbeddingStore (.semiont/embeddings/), and indexes them into the VectorStore
- * (Qdrant). Peer to the Graph Consumer.
- *
- * Pipeline:
- *   1. Subscribe to resource and annotation events from the EventStore
- *   2. Chunk resource text into overlapping passages
- *   3. Embed each chunk via the configured EmbeddingProvider
- *   4. Write vectors to EmbeddingStore (overwrite-in-place, git-durable)
- *   5. Index vectors into the VectorStore (Qdrant) for fast similarity search
- *
- * Uses the same burst-buffer RxJS pipeline as GraphDBConsumer.
- *
- * ## Per-resource serialization
- *
- * Smelter processes events strictly in order per resourceId via
- * `groupBy(resourceId) + concatMap(...)`. This is the stream-consumer
- * flavor of per-resource serialization — the same invariant enforced by
- * `GraphDBConsumer`, `Gatherer`, and (in a different shape) `ViewManager`.
- * See `packages/core/src/serialize-per-key.ts` for the shared primitive
- * used by RPC-style services, and `.plans/PerResourceSerializer.md` for
- * the broader design that would unify the two shapes.
- */
-
-declare class Smelter {
-    private eventBus;
-    private vectorStore;
-    private embeddingProvider;
-    private contentStore;
-    private embeddingStore;
-    private viewStorage;
-    private static readonly SMELTER_RELEVANT_EVENTS;
-    private static readonly BURST_WINDOW_MS;
-    private static readonly MAX_BATCH_SIZE;
-    private static readonly IDLE_TIMEOUT_MS;
-    private _globalSubscriptions;
-    private eventSubject;
-    private pipelineSubscription;
-    private readonly logger;
-    private readonly chunkingConfig;
-    constructor(_eventStore: EventStore, eventBus: EventBus, vectorStore: VectorStore, embeddingProvider: EmbeddingProvider, contentStore: WorkingTreeStore, embeddingStore: EmbeddingStore, viewStorage: ViewStorage, logger: Logger, chunkingConfig?: ChunkingConfig);
-    initialize(): Promise<void>;
-    stop(): Promise<void>;
-    /**
-     * Rebuild the vector store from the EmbeddingStore (.semiont/embeddings/).
-     *
-     * For each stored file, checks whether the model matches the configured
-     * provider. On mismatch, re-embeds from the stored text and overwrites the
-     * file before upserting into Qdrant. On match, loads the stored vectors
-     * directly — no embedding provider calls needed.
-     */
-    rebuildAll(): Promise<void>;
-    private processBatch;
-    /**
-     * Batch-optimized processing for consecutive events of the same type.
-     */
-    private applyBatchByType;
-    /**
-     * Batch-embed chunks from multiple yield:created events in a single
-     * embedBatch() call, then write to EmbeddingStore and index per resource.
-     */
-    private batchResourceCreated;
-    /**
-     * Batch-embed exact texts from multiple mark:added events in a single
-     * embedBatch() call, then write to EmbeddingStore and index per annotation.
-     */
-    private batchAnnotationAdded;
-    private safeProcessEvent;
-    private processEvent;
-    private handleResourceCreated;
-    /**
-     * Re-embed a resource whose content has changed in-place.
-     *
-     * Used by yield:updated and yield:representation-added handlers. Reads the
-     * current storageUri from the materialized view (which is updated before the
-     * EventBus fires), deletes stale Qdrant vectors, and overwrites the
-     * EmbeddingStore file with fresh chunks.
-     */
-    private reembedResource;
-    private handleResourceUpdated;
-    private handleRepresentationAdded;
-    private handleResourceArchived;
-    private handleAnnotationAdded;
-    private handleAnnotationRemoved;
-}
-
 /**
  * Knowledge Base
  *
@@ -318,10 +167,11 @@ declare class Smelter {
  * - Content Store (working-tree files, URI-addressed) — via WorkingTreeStore
  * - Graph (eventually consistent relationship projection) — via GraphDatabase
  * - Graph Consumer (event-to-graph projection) — via GraphDBConsumer
- * - Vectors (semantic search) — via VectorStore (optional)
- * - Smelter (event-to-vector projection) — via Smelter (optional)
+ * - Vectors (semantic search) — via VectorStore (optional, read-only)
  *
- * The Gatherer and Matcher are the only actors that read from these stores directly.
+ * The Smelter (event-to-vector projection) runs as an external actor
+ * via @semiont/jobs/smelter-main. It subscribes to domain events via
+ * the EventBus gateway, embeds content, and writes to Qdrant directly.
  */
 
 interface KnowledgeBase {
@@ -331,13 +181,10 @@ interface KnowledgeBase {
     graph: GraphDatabase;
     graphConsumer: GraphDBConsumer;
     vectors?: VectorStore;
-    smelter?: Smelter;
     projectionsDir: string;
 }
 interface CreateKnowledgeBaseOptions {
     vectorStore?: VectorStore;
-    embeddingProvider?: EmbeddingProvider;
-    chunkingConfig?: ChunkingConfig;
     skipRebuild?: boolean;
 }
 declare function createKnowledgeBase(eventStore: EventStore, project: SemiontProject, graphDb: GraphDatabase, eventBus: EventBus, logger: Logger, options?: CreateKnowledgeBaseOptions): Promise<KnowledgeBase>;
@@ -369,15 +216,19 @@ declare function createKnowledgeBase(eventStore: EventStore, project: SemiontPro
  * - mark:add-entity-type → entitytype.added                   → mark:entity-type-added / mark:entity-type-add-failed
  * - mark:update-entity-types → entitytag.added / entitytag.removed
  * - job:start          → job.started
- * - job:report-progress → job.progress
  * - job:complete       → job.completed
  * - job:fail           → job.failed
+ *
+ * Note: `job:report-progress` is intentionally NOT persisted. Progress
+ * events are ephemeral UI feedback and would clutter the event log
+ * (historical logs show ~3× as many progress entries as start+complete
+ * combined). UI consumers subscribe to the bus directly for live
+ * progress; the event log keeps only the durable lifecycle boundaries.
  */
 
-type ResourceDescriptor$3 = components['schemas']['ResourceDescriptor'];
 interface CreateResourceResult {
     resourceId: ResourceId;
-    resource: ResourceDescriptor$3;
+    resource: ResourceDescriptor;
 }
 declare class Stower {
     private kb;
@@ -397,7 +248,6 @@ declare class Stower {
     private handleAddEntityType;
     private handleUpdateEntityTypes;
     private handleJobStart;
-    private handleJobReportProgress;
     private handleJobComplete;
     private handleJobFail;
     stop(): Promise<void>;
@@ -426,11 +276,10 @@ declare class Stower {
  * per-resource serialization — the same invariant enforced by `Smelter`,
  * `GraphDBConsumer`, and (in a different shape) `ViewManager`. See
  * `packages/core/src/serialize-per-key.ts` for the shared primitive used
- * by RPC-style services, and `.plans/PerResourceSerializer.md` for the
- * broader design that would unify the two shapes.
+ * by RPC-style services.
  */
 
-declare class Gatherer {
+declare class Gatherer$1 {
     private kb;
     private eventBus;
     private inferenceClient;
@@ -588,7 +437,7 @@ declare class CloneTokenManager {
 interface KnowledgeSystem {
     kb: KnowledgeBase;
     stower: Stower;
-    gatherer: Gatherer;
+    gatherer: Gatherer$1;
     matcher: Matcher;
     browser: Browser;
     cloneTokenManager: CloneTokenManager;
@@ -606,21 +455,204 @@ declare function stopKnowledgeSystem(ks: KnowledgeSystem): Promise<void>;
 interface MakeMeaningService {
     knowledgeSystem: KnowledgeSystem;
     jobQueue: JobQueue;
-    workers: Workers;
     stop: () => Promise<void>;
 }
-type Workers = {
-    detection: ReferenceAnnotationWorker;
-    generation: GenerationWorker;
-    highlight: HighlightAnnotationWorker;
-    assessment: AssessmentAnnotationWorker;
-    comment: CommentAnnotationWorker;
-    tag: TagAnnotationWorker;
-};
 declare function startMakeMeaning(project: SemiontProject, config: MakeMeaningConfig, eventBus: EventBus, logger: Logger, options?: {
     skipRebuild?: boolean;
 }): Promise<MakeMeaningService>;
 
+/**
+ * LocalTransport — `ITransport` for an in-process `KnowledgeSystem`.
+ *
+ * Bus-ownership pattern (see `packages/core/docs/TRANSPORT-CONTRACT.md`):
+ *   - The caller owns a make-meaning `EventBus` and passes it to both
+ *     `startMakeMeaning` and `LocalTransport` so the transport can publish
+ *     directly onto the bus the `KnowledgeSystem` actors are listening on.
+ *   - `SemiontClient` constructs its own `clientBus` and calls
+ *     `bridgeInto(clientBus)` during construction. `LocalTransport`
+ *     subscribes to every `BRIDGED_CHANNELS` entry on the make-meaning bus
+ *     and forwards each onto `clientBus`.
+ *   - The bus reference flows client → transport, never the other way.
+ *
+ * Auth, admin, and exchange methods are not implemented in Phase 2 — local
+ * mode runs as a single host-process identity supplied at construction.
+ * Calling them throws.
+ */
+
+type AuthResponse = components['schemas']['AuthResponse'];
+type TokenRefreshResponse = components['schemas']['TokenRefreshResponse'];
+type AdminUserStatsResponse = components['schemas']['AdminUserStatsResponse'];
+type OAuthConfigResponse = components['schemas']['OAuthConfigResponse'];
+interface LocalTransportConfig {
+    /**
+     * The in-process knowledge system. Lifetime is owned by the caller —
+     * `dispose()` on this transport does not stop the KnowledgeSystem.
+     */
+    knowledgeSystem: KnowledgeSystem;
+    /**
+     * The make-meaning `EventBus`. Must be the same instance passed to
+     * `startMakeMeaning` so that emits land on the bus KnowledgeSystem
+     * actors are subscribed to.
+     */
+    eventBus: EventBus;
+    /**
+     * Host-process identity. Stamped onto every emit as `_userId`, mirroring
+     * the gateway-injection convention used by `HttpTransport` (where the
+     * `/bus/emit` gateway reads the JWT subject and injects `_userId`).
+     * Handlers downstream trust nothing else.
+     */
+    userId: UserDID;
+    /**
+     * Cosmetic base URL for diagnostics and URL composition. Defaults to
+     * `local://in-process`. Local code never makes outgoing HTTP requests
+     * with it.
+     */
+    baseUrl?: BaseUrl;
+}
+declare class LocalTransport implements ITransport {
+    readonly baseUrl: BaseUrl;
+    readonly state$: BehaviorSubject<ConnectionState>;
+    private readonly bus;
+    private readonly userId;
+    private readonly bridges;
+    private readonly bridgeSubs;
+    private disposed;
+    constructor(cfg: LocalTransportConfig);
+    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(_resourceId: ResourceId): () => void;
+    bridgeInto(bus: EventBus): void;
+    authenticatePassword(_email: Email, _password: string): Promise<AuthResponse>;
+    authenticateGoogle(_credential: GoogleCredential): Promise<AuthResponse>;
+    refreshAccessToken(_token: RefreshToken): Promise<TokenRefreshResponse>;
+    logout(): Promise<void>;
+    acceptTerms(): Promise<void>;
+    getCurrentUser(): Promise<UserResponse>;
+    generateMcpToken(): Promise<{
+        token: string;
+    }>;
+    getMediaToken(_resourceId: ResourceId): Promise<{
+        token: string;
+    }>;
+    listUsers(): Promise<ListUsersResponse>;
+    getUserStats(): Promise<AdminUserStatsResponse>;
+    updateUser(_id: UserDID, _data: UpdateUserRequest): Promise<UpdateUserResponse>;
+    getOAuthConfig(): Promise<OAuthConfigResponse>;
+    backupKnowledgeBase(): Promise<Response>;
+    restoreKnowledgeBase(_file: File, _onProgress?: ProgressCallback): Promise<ProgressEvent>;
+    exportKnowledgeBase(_params?: {
+        includeArchived?: boolean;
+    }): Promise<Response>;
+    importKnowledgeBase(_file: File, _onProgress?: ProgressCallback): Promise<ProgressEvent>;
+    healthCheck(): Promise<HealthCheckResponse>;
+    getStatus(): Promise<StatusResponse>;
+    dispose(): void;
+}
+
+/**
+ * LocalContentTransport — `IContentTransport` for an in-process
+ * `KnowledgeSystem`.
+ *
+ * Reads go straight to `kb.views` (resource lookup) + `kb.content`
+ * (byte retrieval). No network, no auth — local mode runs as a single
+ * host-process identity.
+ *
+ * `putBinary` is intentionally not implemented in Phase 2: in-process
+ * resource creation is exercised through bus emits (mark/yield
+ * namespaces), not multipart upload. If a future caller needs raw
+ * binary upload from a local context, wire it through the same
+ * resource-creation pipeline the HTTP `/resources` handler uses.
+ */
+
+declare class LocalContentTransport implements IContentTransport {
+    private readonly ks;
+    constructor(ks: KnowledgeSystem);
+    putBinary(_request: PutBinaryRequest, _options?: {
+        auth?: AccessToken;
+    }): Promise<{
+        resourceId: ResourceId;
+    }>;
+    getBinary(resourceId: ResourceId, options?: {
+        accept?: ContentFormat$1 | string;
+        auth?: AccessToken;
+    }): Promise<{
+        data: ArrayBuffer;
+        contentType: string;
+    }>;
+    getBinaryStream(resourceId: ResourceId, options?: {
+        accept?: ContentFormat$1 | string;
+        auth?: AccessToken;
+    }): Promise<{
+        stream: ReadableStream<Uint8Array>;
+        contentType: string;
+    }>;
+    private loadBinary;
+    dispose(): void;
+}
+
+/**
+ * Handles `mark:create-request` — the bus command for creating an annotation.
+ *
+ * Flow:
+ *   1. Assemble the W3C annotation from the request using the injected user DID.
+ *   2. Emit `mark:create` with the correlationId threaded through.
+ *   3. Stower picks up `mark:create`, appends to the event store (threading
+ *      correlationId into event metadata), and publishes `mark:added` on the
+ *      core EventBus.
+ *   4. This handler subscribes to `mark:added` and `mark:create-failed`,
+ *      matches by correlationId, and emits `mark:create-ok` / `mark:create-failed`
+ *      to the caller only after persistence has actually completed.
+ *
+ * This is a deferred-ack pattern: the result event attests that Stower has
+ * persisted the annotation, not merely that the command was well-formed.
+ */
+declare function registerAnnotationAssemblyHandler(eventBus: EventBus, parentLogger: Logger): void;
+
+interface Gatherer {
+    generateAnnotationSummary(annId: AnnotationId, resId: ResourceId): Promise<Record<string, unknown>>;
+}
+declare function registerAnnotationLookupHandlers(eventBus: EventBus, kb: KnowledgeBase, gatherer: Gatherer, parentLogger: Logger): void;
+
+/**
+ * Handles `bind:update-body` — the Bind flow's authoritative "apply body
+ * operations to an annotation" command. Bind remains a first-class flow
+ * despite delegating persistence to Mark — the semantic distinction (Bind =
+ * reference linking, Mark = annotation CRUD) is meaningful at the UX and
+ * agent-reasoning layers even when the downstream storage event is shared.
+ *
+ * Flow:
+ *   1. Receive bind:update-body with correlationId.
+ *   2. Forward to mark:update-body with correlationId threaded through.
+ *   3. Stower persists (via EventStore.appendEvent) and publishes mark:body-updated
+ *      with correlationId in metadata.
+ *   4. This handler subscribes to mark:body-updated and mark:body-update-failed,
+ *      matches by correlationId, and emits bind:body-updated / bind:body-update-failed
+ *      so the caller learns the real outcome — not an optimistic ack.
+ */
+declare function registerBindUpdateBodyHandler(eventBus: EventBus, parentLogger: Logger): void;
+
+declare function registerJobCommandHandlers(eventBus: EventBus, jobQueue: JobQueue, parentLogger: Logger): void;
+
+/**
+ * Bus command handlers — pure bus-event translators that bridge the
+ * "request" channels callers emit (`mark:create-request`, `bind:update-body`,
+ * `job:create`, `browse:annotation-context-requested`,
+ * `gather:summary-requested`) to the underlying make-meaning pipeline
+ * (Stower, Browser, Gatherer, JobQueue).
+ *
+ * These ran in `apps/backend` historically because the HTTP gateway was
+ * the only consumer that needed them. They are not HTTP-specific — moving
+ * them here means `LocalTransport` consumers (and any future transport)
+ * get the same contract automatically.
+ */
+
+/**
+ * Register all bus command handlers on the make-meaning EventBus. Called
+ * during `startMakeMeaning` after the JobQueue and KnowledgeSystem exist.
+ */
+declare function registerBusHandlers(eventBus: EventBus, knowledgeSystem: KnowledgeSystem, jobQueue: JobQueue, logger: Logger): void;
+
 /**
  * Entity Types Bootstrap
  *
@@ -812,14 +844,12 @@ declare function importBackup(archive: Readable, options: BackupImporterOptions)
  *   {checksum}.{ext}                        - Content blobs (root level)
  */
 
-type ResourceDescriptor$2 = components['schemas']['ResourceDescriptor'];
-type Annotation$3 = components['schemas']['Annotation'];
 /** Subset of ViewStorage used by the linked-data exporter. */
 interface LinkedDataViewReader {
     getAll(): Promise<Array<{
-        resource: ResourceDescriptor$2;
+        resource: ResourceDescriptor;
         annotations: {
-            annotations: Annotation$3[];
+            annotations: Annotation[];
         };
     }>>;
 }
@@ -887,19 +917,10 @@ declare function importLinkedData(archive: Readable, options: LinkedDataImporter
  * — the Stower actor subscribes and handles persistence.
  *
  * For create: emits yield:create, awaits yield:created / yield:create-failed.
- * For archive/unarchive: emits mark:archive / mark:unarchive on scoped bus.
- * For entity type updates: emits mark:update-entity-types.
  */
 
 type ContentFormat = components['schemas']['ContentFormat'];
-interface UpdateResourceInput {
-    resourceId: ResourceId;
-    userId: UserId;
-    currentArchived?: boolean;
-    updatedArchived?: boolean;
-    currentEntityTypes?: string[];
-    updatedEntityTypes?: string[];
-}
+type Agent$1 = components['schemas']['Agent'];
 interface CreateResourceInput {
     name: string;
     storageUri: string;
@@ -909,16 +930,20 @@ interface CreateResourceInput {
     language?: string;
     entityTypes?: string[];
     creationMethod?: CreationMethod;
+    /** Provenance for AI-generated resources: source resource + annotation. */
+    generatedFrom?: {
+        resourceId?: string;
+        annotationId?: string;
+    };
+    generationPrompt?: string;
+    generator?: Agent$1 | Agent$1[];
+    isDraft?: boolean;
 }
 declare class ResourceOperations {
     /**
      * Create a new resource via EventBus → Stower
      */
     static createResource(input: CreateResourceInput, userId: UserId, eventBus: EventBus): Promise<ResourceId>;
-    /**
-     * Update resource metadata via EventBus → Stower
-     */
-    static updateResource(input: UpdateResourceInput, eventBus: EventBus): Promise<void>;
 }
 
 /**
@@ -927,20 +952,21 @@ declare class ResourceOperations {
  * Business logic for annotation CRUD operations. All writes go through the
  * EventBus — the Stower actor subscribes and handles persistence.
  *
- * - Create: emits mark:create with full annotation + userId + resourceId
- * - Update body: emits mark:update-body
- * - Delete: emits mark:delete with annotationId + userId + resourceId
+ * In-process callers pass a `UserId` to these operations; the
+ * EventBus emits stamp it onto the gateway-injection field `_userId`,
+ * matching the wire-side convention so Stower handlers see one shape
+ * regardless of where the command originated.
  */
 
 type Agent = components['schemas']['Agent'];
-type Annotation$2 = components['schemas']['Annotation'];
+
 type CreateAnnotationRequest = components['schemas']['CreateAnnotationRequest'];
 type UpdateAnnotationBodyRequest = components['schemas']['UpdateAnnotationBodyRequest'];
 interface CreateAnnotationResult {
-    annotation: Annotation$2;
+    annotation: Annotation;
 }
 interface UpdateAnnotationBodyResult {
-    annotation: Annotation$2;
+    annotation: Annotation;
 }
 declare class AnnotationOperations {
     /**
@@ -964,7 +990,6 @@ declare class AnnotationOperations {
  * Does NOT touch the graph - graph queries go through GraphContext
  */
 
-type ResourceDescriptor$1 = components['schemas']['ResourceDescriptor'];
 interface ListResourcesFilters {
     search?: string;
     archived?: boolean;
@@ -973,7 +998,7 @@ declare class ResourceContext {
     /**
      * Get resource metadata from view storage
      */
-    static getResourceMetadata(resourceId: ResourceId, kb: KnowledgeBase): Promise<ResourceDescriptor$1 | null>;
+    static getResourceMetadata(resourceId: ResourceId, kb: KnowledgeBase): Promise<ResourceDescriptor | null>;
     /**
      * List resources, optionally filtered.
      *
@@ -984,20 +1009,20 @@ declare class ResourceContext {
      * When `search` is unset, falls back to scanning all materialized views.
      * (TODO: also push the listing path through the graph for large KBs.)
      */
-    static listResources(filters: ListResourcesFilters | undefined, kb: KnowledgeBase): Promise<ResourceDescriptor$1[]>;
+    static listResources(filters: ListResourcesFilters | undefined, kb: KnowledgeBase): Promise<ResourceDescriptor[]>;
     private static sortByDateDesc;
     /**
      * Add content previews to resources (for search results)
      * Retrieves and decodes the first 200 characters of each resource's primary representation
      */
-    static addContentPreviews(resources: ResourceDescriptor$1[], kb: KnowledgeBase): Promise<Array<ResourceDescriptor$1 & {
+    static addContentPreviews(resources: ResourceDescriptor[], kb: KnowledgeBase): Promise<Array<ResourceDescriptor & {
         content: string;
     }>>;
     /**
      * Get full content for a resource
      * Retrieves and decodes the primary representation
      */
-    static getResourceContent(resource: ResourceDescriptor$1, kb: KnowledgeBase): Promise<string | undefined>;
+    static getResourceContent(resource: ResourceDescriptor, kb: KnowledgeBase): Promise<string | undefined>;
 }
 
 /**
@@ -1012,7 +1037,7 @@ declare class ResourceContext {
  */
 
 type AnnotationLLMContextResponse = components['schemas']['AnnotationLLMContextResponse'];
-type Annotation$1 = components['schemas']['Annotation'];
+
 type AnnotationContextResponse = components['schemas']['AnnotationContextResponse'];
 type ContextualSummaryResponse = components['schemas']['ContextualSummaryResponse'];
 interface BuildContextOptions {
@@ -1042,7 +1067,7 @@ declare class AnnotationContext {
      * Get all annotations
      * @returns Array of all annotation objects
      */
-    static getAllAnnotations(resourceId: ResourceId, kb: KnowledgeBase): Promise<Annotation$1[]>;
+    static getAllAnnotations(resourceId: ResourceId, kb: KnowledgeBase): Promise<Annotation[]>;
     /**
      * Enrich reference annotations with resolved document names
      * Adds _resolvedDocumentName property to annotations that link to documents
@@ -1066,7 +1091,7 @@ declare class AnnotationContext {
      * Get a single annotation by ID
      * O(1) lookup using resource ID to access view storage
      */
-    static getAnnotation(annotationId: AnnotationId, resourceId: ResourceId, kb: KnowledgeBase): Promise<Annotation$1 | null>;
+    static getAnnotation(annotationId: AnnotationId, resourceId: ResourceId, kb: KnowledgeBase): Promise<Annotation | null>;
     /**
      * List annotations with optional filtering
      * @param filters - Optional filters like resourceId and type
@@ -1075,7 +1100,7 @@ declare class AnnotationContext {
     static listAnnotations(filters: {
         resourceId?: ResourceId;
         type?: AnnotationCategory;
-    } | undefined, kb: KnowledgeBase): Promise<Annotation$1[]>;
+    } | undefined, kb: KnowledgeBase): Promise<Annotation[]>;
     /**
      * Get annotation context (selected text with surrounding context)
      */
@@ -1106,8 +1131,6 @@ declare class AnnotationContext {
  * All methods require graph traversal - must use graph database.
  */
 
-type Annotation = components['schemas']['Annotation'];
-type ResourceDescriptor = components['schemas']['ResourceDescriptor'];
 interface GraphNode {
     id: string;
     type: string;
@@ -1199,4 +1222,4 @@ declare function generateReferenceSuggestions(referenceTitle: string, client: In
 declare const PACKAGE_NAME = "@semiont/make-meaning";
 declare const VERSION = "0.1.0";
 
-export { AnnotationContext, AnnotationOperations, BACKUP_FORMAT, type BackupContentReader, type BackupEventStoreReader, type BackupExporterOptions, type BackupImportResult, type BackupImporterOptions, type BackupManifestHeader, type BackupStreamSummary, Browser, type BuildContextOptions, CloneTokenManager, type ContentBlobResolver, type CreateAnnotationResult, type CreateResourceInput, type CreateResourceResult, FORMAT_VERSION, Gatherer, GraphContext, type GraphEdge, type GraphNode, type GraphRepresentation, type KnowledgeBase, type KnowledgeSystem, LLMContext, type LLMContextOptions, type LinkedDataContentReader, type LinkedDataExporterOptions, type LinkedDataImportResult, type LinkedDataImporterOptions, type LinkedDataViewReader, type ListResourcesFilters, type MakeMeaningConfig, type MakeMeaningService, Matcher, PACKAGE_NAME, type ReplayStats, ResourceContext, ResourceOperations, Smelter, Stower, type UpdateAnnotationBodyResult, type UpdateResourceInput, VERSION, bootstrapEntityTypes, createKnowledgeBase, exportBackup, exportLinkedData, generateReferenceSuggestions, generateResourceSummary, importBackup, importLinkedData, isBackupManifest, readEntityTypesProjection, startMakeMeaning, stopKnowledgeSystem, validateManifestVersion };
+export { AnnotationContext, AnnotationOperations, BACKUP_FORMAT, type BackupContentReader, type BackupEventStoreReader, type BackupExporterOptions, type BackupImportResult, type BackupImporterOptions, type BackupManifestHeader, type BackupStreamSummary, Browser, type BuildContextOptions, CloneTokenManager, type ContentBlobResolver, type CreateAnnotationResult, type CreateResourceInput, type CreateResourceResult, FORMAT_VERSION, Gatherer$1 as Gatherer, GraphContext, type GraphEdge, type GraphNode, type GraphRepresentation, type KnowledgeBase, type KnowledgeSystem, LLMContext, type LLMContextOptions, type LinkedDataContentReader, type LinkedDataExporterOptions, type LinkedDataImportResult, type LinkedDataImporterOptions, type LinkedDataViewReader, type ListResourcesFilters, LocalContentTransport, LocalTransport, type LocalTransportConfig, type MakeMeaningConfig, type MakeMeaningService, Matcher, PACKAGE_NAME, type ReplayStats, ResourceContext, ResourceOperations, Stower, type UpdateAnnotationBodyResult, VERSION, bootstrapEntityTypes, createKnowledgeBase, exportBackup, exportLinkedData, generateReferenceSuggestions, generateResourceSummary, importBackup, importLinkedData, isBackupManifest, readEntityTypesProjection, registerAnnotationAssemblyHandler, registerAnnotationLookupHandlers, registerBindUpdateBodyHandler, registerBusHandlers, registerJobCommandHandlers, startMakeMeaning, stopKnowledgeSystem, validateManifestVersion };