@semiont/make-meaning 0.5.0 → 0.5.2

package/README.md

@@ -8,7 +8,7 @@
 
 **Making meaning from resources through actors, context assembly, and relationship reasoning.**
 
-This package implements the actor model from [ARCHITECTURE.md](../../docs/ARCHITECTURE.md). It owns the **Knowledge Base** and the actors that interface with it:
+This package implements the actor model from [ACTOR-MODEL.md](../../docs/system/ACTOR-MODEL.md). It owns the **Knowledge Base** and the actors that interface with it:
 
 - **Stower** (write) — the single write gateway to the Knowledge Base; handles all resource and annotation mutations and job lifecycle events
 - **Browser** (read) — handles all KB read queries: resources, annotations, events, annotation history, referenced-by lookups, entity type listing, and directory browse (merging filesystem listings with KB metadata)
@@ -115,14 +115,14 @@ graph TB
         CTM -->|query| KB
     end
 
-    BUS -->|"yield:create, yield:update, yield:mv<br/>mark:create, mark:delete, mark:update-body<br/>mark:add-entity-type, mark:archive, mark:unarchive<br/>mark:update-entity-types, job:start, job:*"| STOWER
+    BUS -->|"yield:create, yield:update, yield:mv<br/>mark:create, mark:delete, mark:update-body<br/>frame:add-entity-type, mark:archive, mark:unarchive<br/>mark:update-entity-types, job:start, job:*"| STOWER
     BUS -->|"browse:resource-requested, browse:resources-requested<br/>browse:annotations-requested, browse:annotation-requested<br/>browse:events-requested, browse:annotation-history-requested<br/>browse:referenced-by-requested, browse:entity-types-requested<br/>browse:directory-requested"| BROWSER
     BUS -->|"gather:requested<br/>gather:resource-requested"| GATHERER
     BUS -->|"match:search-requested"| MATCHER
     BUS -->|"yield:created, mark:created,<br/>mark:body-updated"| SMELTER
     BUS -->|"yield:clone-token-requested<br/>yield:clone-resource-requested<br/>yield:clone-create"| CTM
 
-    STOWER -->|"yield:created, yield:updated, yield:moved<br/>mark:created, mark:deleted, mark:body-updated<br/>mark:entity-type-added, ..."| BUS
+    STOWER -->|"yield:created, yield:updated, yield:moved<br/>mark:created, mark:deleted, mark:body-updated<br/>frame:entity-type-added, ..."| BUS
     BROWSER -->|"browse:resource-result, browse:resources-result<br/>browse:annotations-result, browse:annotation-result<br/>browse:events-result, browse:annotation-history-result<br/>browse:referenced-by-result, browse:entity-types-result<br/>browse:directory-result"| BUS
     GATHERER -->|"gather:complete, gather:failed<br/>gather:resource-complete, gather:resource-failed"| BUS
     MATCHER -->|"match:search-results, match:search-failed"| BUS

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { JobQueue } from '@semiont/jobs';
 import { SemiontProject } from '@semiont/core/node';
-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';
+import { GraphServiceConfig, VectorsServiceConfig, EmbeddingServiceConfig, EventBus, Logger, StoredEvent, ResourceId, ResourceDescriptor, AnnotationId, components, ITransport, BaseUrl, ConnectionState, SemiontError, UserDID, EventMap, IContentTransport, PutBinaryRequest, PutBinaryOptions, ContentFormat as ContentFormat$1, AccessToken, 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';
@@ -8,6 +8,7 @@ import { GraphDatabase } from '@semiont/graph';
 import { VectorStore, EmbeddingProvider } from '@semiont/vectors';
 import { InferenceClient } from '@semiont/inference';
 import { BehaviorSubject, Observable } from 'rxjs';
+import { StateUnit, WorkerBus } from '@semiont/sdk';
 import { Writable, Readable } from 'node:stream';
 
 /**
@@ -170,8 +171,8 @@ declare class GraphDBConsumer {
  * - Vectors (semantic search) — via VectorStore (optional, read-only)
  *
  * 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.
+ * via @semiont/make-meaning/smelter-main. It subscribes to domain events
+ * via the EventBus gateway, embeds content, and writes to Qdrant directly.
  */
 
 interface KnowledgeBase {
@@ -213,7 +214,7 @@ declare function createKnowledgeBase(eventStore: EventStore, project: SemiontPro
  * - mark:update-body   → annotation.body.updated              → (no result event yet)
  * - mark:archive       → resource.archived (+ file removal)   (resource-scoped, no result event)
  * - mark:unarchive     → resource.unarchived                  (resource-scoped, no result event)
- * - mark:add-entity-type → entitytype.added                   → mark:entity-type-added / mark:entity-type-add-failed
+ * - frame:add-entity-type → entitytype.added                   → frame:entity-type-added / frame:entity-type-add-failed
  * - mark:update-entity-types → entitytag.added / entitytag.removed
  * - job:start          → job.started
  * - job:complete       → job.completed
@@ -464,7 +465,7 @@ declare function startMakeMeaning(project: SemiontProject, config: MakeMeaningCo
 /**
  * LocalTransport — `ITransport` for an in-process `KnowledgeSystem`.
  *
- * Bus-ownership pattern (see `packages/core/docs/TRANSPORT-CONTRACT.md`):
+ * Bus-ownership pattern (see `docs/protocol/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.
@@ -474,15 +475,13 @@ declare function startMakeMeaning(project: SemiontProject, config: MakeMeaningCo
  *     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.
+ * LocalTransport implements `ITransport` only. Auth, admin, and exchange
+ * (`IBackendOperations`) are HTTP-shaped concepts that don't apply
+ * in-process — local mode runs as a single host-process identity supplied
+ * at construction, with no token/credential lifecycle. A `SemiontClient`
+ * built over this transport has no `.auth` / `.admin` namespaces.
  */
 
-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 —
@@ -512,6 +511,18 @@ interface LocalTransportConfig {
 declare class LocalTransport implements ITransport {
     readonly baseUrl: BaseUrl;
     readonly state$: BehaviorSubject<ConnectionState>;
+    private readonly errorsSubject;
+    /**
+     * Stream of `SemiontError` instances surfaced from transport-mediated
+     * round-trips (typed-wire methods on this transport that fail). The
+     * in-process implementation does not currently surface errors through
+     * this stream — most failures here originate inside the make-meaning
+     * actors and surface through bus channels (correlation-ID failures via
+     * `busRequest`). The Subject exists to satisfy the `ITransport`
+     * contract; future expansion (e.g. transport-level guard failures)
+     * can publish into it.
+     */
+    readonly errors$: Observable<SemiontError>;
     private readonly bus;
     private readonly userId;
     private readonly bridges;
@@ -523,30 +534,6 @@ declare class LocalTransport implements ITransport {
     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;
 }
 
@@ -568,9 +555,7 @@ declare class LocalTransport implements ITransport {
 declare class LocalContentTransport implements IContentTransport {
     private readonly ks;
     constructor(ks: KnowledgeSystem);
-    putBinary(_request: PutBinaryRequest, _options?: {
-        auth?: AccessToken;
-    }): Promise<{
+    putBinary(_request: PutBinaryRequest, _options?: PutBinaryOptions): Promise<{
         resourceId: ResourceId;
     }>;
     getBinary(resourceId: ResourceId, options?: {
@@ -657,7 +642,7 @@ declare function registerBusHandlers(eventBus: EventBus, knowledgeSystem: Knowle
  * Entity Types Bootstrap
  *
  * On startup, seeds the KB with DEFAULT_ENTITY_TYPES by emitting
- * mark:add-entity-type for each missing type. Reads the __system__ event
+ * frame:add-entity-type for each missing type. Reads the __system__ event
  * stream (the durable source of truth in .semiont/events/) to determine
  * which types already exist.
  *
@@ -673,7 +658,7 @@ declare function registerBusHandlers(eventBus: EventBus, knowledgeSystem: Knowle
 
 /**
  * Bootstrap entity types if any are missing from the event log.
- * Reads the __system__ stream to find existing mark:entity-type-added events,
+ * Reads the __system__ stream to find existing frame:entity-type-added events,
  * then emits only the missing ones.
  */
 declare function bootstrapEntityTypes(eventBus: EventBus, eventStore: EventStore, logger?: Logger): Promise<void>;
@@ -690,6 +675,36 @@ declare function bootstrapEntityTypes(eventBus: EventBus, eventStore: EventStore
  */
 declare function readEntityTypesProjection(project: SemiontProject): Promise<string[]>;
 
+/**
+ * SmelterActorStateUnit — domain-event fan-in for the Smelter worker.
+ *
+ * Subscribes to the six smelter-relevant channels on a shared bus and
+ * exposes them as a single typed `events$` stream. Transport-neutral —
+ * the caller passes a `WorkerBus` (HTTP `ActorStateUnit` today, an in-process
+ * bus shim if/when one exists). The state unit does not own the bus and does
+ * not dispose it.
+ *
+ * `start()` widens the bus's channel-subscription set to include the
+ * smelter channels. On HTTP this extends the SSE subscription URL;
+ * on an in-process bus this is a no-op (the underlying `EventBus`
+ * already delivers every emit).
+ */
+
+interface SmelterEvent {
+    type: string;
+    resourceId?: string;
+    payload: Record<string, unknown>;
+}
+interface SmelterActorStateUnitOptions {
+    bus: WorkerBus;
+}
+interface SmelterActorStateUnit extends StateUnit {
+    events$: Observable<SmelterEvent>;
+    emit(channel: string, payload: Record<string, unknown>): Promise<void>;
+    start(): void;
+}
+declare function createSmelterActorStateUnit(options: SmelterActorStateUnitOptions): SmelterActorStateUnit;
+
 /**
  * Exchange Format Manifest Types
  *
@@ -901,7 +916,7 @@ interface LinkedDataImportResult {
  *   1. Stream and decompress tar.gz entries
  *   2. Parse .semiont/manifest.jsonld → validate format
  *   3. Build blob resolver over root-level content entries
- *   4. Add entity types from manifest via mark:add-entity-type
+ *   4. Add entity types from manifest via frame:add-entity-type
  *   5. For each .semiont/resources/{id}.jsonld:
  *      a. Parse JSON-LD document
  *      b. Resolve content blob by checksum from representations
@@ -1222,4 +1237,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$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 };
+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, type SmelterActorStateUnit, type SmelterActorStateUnitOptions, type SmelterEvent, Stower, type UpdateAnnotationBodyResult, VERSION, bootstrapEntityTypes, createKnowledgeBase, createSmelterActorStateUnit, exportBackup, exportLinkedData, generateReferenceSuggestions, generateResourceSummary, importBackup, importLinkedData, isBackupManifest, readEntityTypesProjection, registerAnnotationAssemblyHandler, registerAnnotationLookupHandlers, registerBindUpdateBodyHandler, registerBusHandlers, registerJobCommandHandlers, startMakeMeaning, stopKnowledgeSystem, validateManifestVersion };