@semiont/make-meaning 0.4.14 → 0.4.15

package/README.md

@@ -14,12 +14,12 @@ This package implements the actor model from [ARCHITECTURE.md](../../docs/ARCHIT
 - **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)
 - **Gatherer** (context assembly) — assembles gathered context for annotations (`gather:requested`) and resources (`gather:resource-requested`); searches vectors for semantically similar passages (adds `semanticContext` to `GatheredContext`)
 - **Matcher** (search/link) — context-driven candidate search with multi-source retrieval, composite structural scoring, and optional LLM semantic scoring
-- **Smelter** (embed) — subscribes to resource/annotation events, chunks text, embeds via `@semiont/vectors`, persists `embedding:computed` events, and indexes into vector store (Qdrant)
+- **Smelter** (embed) — subscribes to resource/annotation events, chunks text, embeds via `@semiont/vectors`, emits `embedding:compute` commands (persisted by Stower as `embedding:computed` events), and indexes into vector store (Qdrant)
 - **CloneTokenManager** (yield) — manages clone token lifecycle for resource cloning
 
 All actors subscribe to the EventBus via RxJS pipelines. They expose only `initialize()` and `stop()` — no public business methods. Callers communicate with actors by putting events on the bus.
 
-The EventBus is a **complete interface** for all knowledge-domain operations. HTTP routes in the backend are thin wrappers that delegate to EventBus actors. The system can operate entirely without HTTP — see `EventBusClient` in `@semiont/api-client`.
+The EventBus is a **complete interface** for all knowledge-domain operations. HTTP routes in the backend are thin wrappers that delegate to EventBus actors. The `@semiont/api-client` exposes the same operations via verb-oriented namespaces (`semiont.browse`, `semiont.mark`, `semiont.gather`, etc.).
 
 ## Quick Start
 
@@ -93,7 +93,7 @@ All meaningful actions flow through the EventBus. The KB actors are reactive —
 graph TB
     Routes["Backend Routes"] -->|commands| BUS["Event Bus"]
     Workers["Job Workers"] -->|commands| BUS
-    EBC["EventBusClient"] -->|commands| BUS
+    EBC["SemiontApiClient"] -->|commands| BUS
 
     subgraph ks ["Knowledge System"]
         STOWER["Stower<br/>(write)"]
@@ -126,7 +126,7 @@ graph TB
     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
-    SMELTER -->|"embedding:computed,<br/>embedding:deleted"| BUS
+    SMELTER -->|"embedding:compute,<br/>embedding:delete"| BUS
     CTM -->|"yield:clone-token-generated<br/>yield:clone-resource-result<br/>yield:clone-created"| BUS
 
     classDef bus fill:#e8a838,stroke:#b07818,stroke-width:3px,color:#000,font-weight:bold

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { JobQueue, ReferenceAnnotationWorker, GenerationWorker, HighlightAnnotationWorker, AssessmentAnnotationWorker, CommentAnnotationWorker, TagAnnotationWorker } from '@semiont/jobs';
 import { SemiontProject } from '@semiont/core/node';
-import { GraphServiceConfig, VectorsServiceConfig, EmbeddingServiceConfig, Logger, StoredEvent, ResourceId, EventBus, components, AnnotationId, UserId, CreationMethod, ResourceAnnotations, AnnotationCategory, GraphPath, GraphConnection } from '@semiont/core';
+import { GraphServiceConfig, VectorsServiceConfig, EmbeddingServiceConfig, EventBus, Logger, StoredEvent, ResourceId, components, AnnotationId, 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';
@@ -77,16 +77,17 @@ interface MakeMeaningConfig {
 declare class GraphDBConsumer {
     private eventStore;
     private graphDb;
+    private coreEventBus;
     private static readonly GRAPH_RELEVANT_EVENTS;
     private static readonly BURST_WINDOW_MS;
     private static readonly MAX_BATCH_SIZE;
     private static readonly IDLE_TIMEOUT_MS;
-    private _globalSubscription;
+    private _globalSubscriptions;
     private eventSubject;
     private pipelineSubscription;
     private lastProcessed;
     private readonly logger;
-    constructor(eventStore: EventStore, graphDb: GraphDatabase, logger: Logger);
+    constructor(eventStore: EventStore, graphDb: GraphDatabase, coreEventBus: EventBus, logger: Logger);
     initialize(): Promise<void>;
     /**
      * Subscribe globally to ALL events, pre-filter to graph-relevant types,
@@ -172,7 +173,7 @@ declare class Smelter {
     private static readonly BURST_WINDOW_MS;
     private static readonly MAX_BATCH_SIZE;
     private static readonly IDLE_TIMEOUT_MS;
-    private _globalSubscription;
+    private _globalSubscriptions;
     private eventSubject;
     private pipelineSubscription;
     private readonly logger;
@@ -182,7 +183,7 @@ declare class Smelter {
     stop(): Promise<void>;
     /**
      * Rebuild the vector store from persisted embedding events in the event log.
-     * Reads all embedding.computed / embedding.deleted events and replays them.
+     * Reads all embedding:computed / embedding:deleted events and replays them.
      * Bypasses the live pipeline — reads directly from the event store.
      */
     rebuildAll(): Promise<void>;
@@ -241,11 +242,10 @@ interface KnowledgeBase {
 interface CreateKnowledgeBaseOptions {
     vectorStore?: VectorStore;
     embeddingProvider?: EmbeddingProvider;
-    eventBus?: EventBus;
     chunkingConfig?: ChunkingConfig;
     skipRebuild?: boolean;
 }
-declare function createKnowledgeBase(eventStore: EventStore, project: SemiontProject, graphDb: GraphDatabase, logger: Logger, options?: CreateKnowledgeBaseOptions): Promise<KnowledgeBase>;
+declare function createKnowledgeBase(eventStore: EventStore, project: SemiontProject, graphDb: GraphDatabase, eventBus: EventBus, logger: Logger, options?: CreateKnowledgeBaseOptions): Promise<KnowledgeBase>;
 
 /**
  * Stower Actor
@@ -277,8 +277,8 @@ declare function createKnowledgeBase(eventStore: EventStore, project: SemiontPro
  * - job:report-progress → job.progress
  * - job:complete       → job.completed
  * - job:fail           → job.failed
- * - embedding:computed  → embedding.computed   (from Smelter)
- * - embedding:deleted   → embedding.deleted    (from Smelter)
+ * - embedding:compute   → embedding.computed   (from Smelter)
+ * - embedding:delete    → embedding.deleted    (from Smelter)
  */
 
 type ResourceDescriptor$3 = components['schemas']['ResourceDescriptor'];
@@ -522,22 +522,29 @@ declare function startMakeMeaning(project: SemiontProject, config: MakeMeaningCo
 }): Promise<MakeMeaningService>;
 
 /**
- * Entity Types Bootstrap Service
+ * Entity Types Bootstrap
  *
- * On startup, checks if the entity types projection exists.
- * If not, emits mark:add-entity-type for each DEFAULT_ENTITY_TYPES entry.
- * This ensures the system has entity types available immediately after first deployment.
+ * On startup, seeds the KB with DEFAULT_ENTITY_TYPES by emitting
+ * mark: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.
+ *
+ * Idempotent: safe to call on every startup. Only emits events for types
+ * not already in the log.
+ *
+ * Future: evolve toward a migration-based model where a `system:bootstrapped`
+ * sentinel event records that first-time init completed, and `system:migrated`
+ * events record schema version upgrades (e.g., adding new default entity types
+ * in a future release). For now, scanning the small __system__ stream is simple
+ * and correct.
  */
 
 /**
- * Bootstrap entity types projection if it doesn't exist.
- * Uses a system user ID (00000000-0000-0000-0000-000000000000) for bootstrap events.
- */
-declare function bootstrapEntityTypes(eventBus: EventBus, project: SemiontProject, logger?: Logger): Promise<void>;
-/**
- * Reset the bootstrap flag (used for testing)
+ * Bootstrap entity types if any are missing from the event log.
+ * Reads the __system__ stream to find existing mark:entity-type-added events,
+ * then emits only the missing ones.
  */
-declare function resetBootstrap(): void;
+declare function bootstrapEntityTypes(eventBus: EventBus, eventStore: EventStore, logger?: Logger): Promise<void>;
 
 /**
  * Entity Types Projection Reader
@@ -640,7 +647,7 @@ declare function exportBackup(options: BackupExporterOptions, output: Writable):
  *
  * Replays parsed JSONL event streams through the EventBus.
  * Each domain event is translated to the corresponding command event
- * (e.g. resource.created → yield:create), emitted, and the result
+ * (e.g. yield:created → yield:create), emitted, and the result
  * event is awaited before proceeding (backpressure).
  *
  * Content blobs are resolved lazily via a lookup function so that
@@ -674,6 +681,7 @@ interface ReplayStats {
 
 interface BackupImporterOptions {
     eventBus: EventBus;
+    contentStore: WorkingTreeStore;
     logger?: Logger;
 }
 interface BackupImportResult {
@@ -749,6 +757,7 @@ declare function exportLinkedData(options: LinkedDataExporterOptions, output: Wr
 
 interface LinkedDataImporterOptions {
     eventBus: EventBus;
+    contentStore: WorkingTreeStore;
     userId: UserId;
     logger?: Logger;
 }
@@ -796,12 +805,13 @@ interface UpdateResourceInput {
 }
 interface CreateResourceInput {
     name: string;
-    content: Buffer;
+    storageUri: string;
+    contentChecksum: string;
+    byteSize: number;
     format: ContentFormat;
     language?: string;
     entityTypes?: string[];
     creationMethod?: CreationMethod;
-    storageUri?: string;
 }
 declare class ResourceOperations {
     /**
@@ -1084,4 +1094,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, resetBootstrap, 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, 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 };