@semiont/make-meaning 0.4.21 → 0.5.0

package/dist/index.d.ts

@@ -1,12 +1,13 @@
 import { JobQueue } from '@semiont/jobs';
 import { SemiontProject } from '@semiont/core/node';
-import { GraphServiceConfig, VectorsServiceConfig, EmbeddingServiceConfig, EventBus, Logger, StoredEvent, ResourceId, components, AnnotationId, 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 } from '@semiont/vectors';
 import { InferenceClient } from '@semiont/inference';
+import { BehaviorSubject, Observable } from 'rxjs';
 import { Writable, Readable } from 'node:stream';
 
 /**
@@ -225,10 +226,9 @@ declare function createKnowledgeBase(eventStore: EventStore, project: SemiontPro
  * 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;
@@ -279,7 +279,7 @@ declare class Stower {
  * by RPC-style services.
  */
 
-declare class Gatherer {
+declare class Gatherer$1 {
     private kb;
     private eventBus;
     private inferenceClient;
@@ -437,7 +437,7 @@ declare class CloneTokenManager {
 interface KnowledgeSystem {
     kb: KnowledgeBase;
     stower: Stower;
-    gatherer: Gatherer;
+    gatherer: Gatherer$1;
     matcher: Matcher;
     browser: Browser;
     cloneTokenManager: CloneTokenManager;
@@ -461,6 +461,198 @@ declare function startMakeMeaning(project: SemiontProject, config: MakeMeaningCo
     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
  *
@@ -652,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[];
         };
     }>>;
 }
@@ -727,20 +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'];
 type Agent$1 = components['schemas']['Agent'];
-interface UpdateResourceInput {
-    resourceId: ResourceId;
-    userId: UserId;
-    currentArchived?: boolean;
-    updatedArchived?: boolean;
-    currentEntityTypes?: string[];
-    updatedEntityTypes?: string[];
-}
 interface CreateResourceInput {
     name: string;
     storageUri: string;
@@ -764,10 +944,6 @@ 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>;
 }
 
 /**
@@ -776,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 {
     /**
@@ -813,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;
@@ -822,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.
      *
@@ -833,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>;
 }
 
 /**
@@ -861,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 {
@@ -891,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
@@ -915,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
@@ -924,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)
      */
@@ -955,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;
@@ -1048,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, 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 };