@semiont/make-meaning 0.5.28 → 0.5.30

package/README.md

@@ -10,24 +10,37 @@
 
 This package implements the actor model from [ACTOR-MODEL.md](../../docs/system/ACTOR-MODEL.md). It owns the **Knowledge Base** and the seven actors that serve it.
 
-Five **access actors** mediate every read and write — the bus-facing interface of the Knowledge Base:
+**The actors no longer run in one process.** Each container entry point in this package starts the subset it owns, and the gateway constructs **none** of them — it keeps the HTTP surface, the bus door, and the job queue.
 
-- **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 and tag-schema listing, the collaborator directory (the KB's declared software agents, derived from the workers/actors inference config), 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
-- **CloneTokenManager** (yield) — manages clone token lifecycle for resource cloning
+| Service | Entry point | Actors |
+| --- | --- | --- |
+| **Archivist** | `@semiont/make-meaning/archivist-main` | Stower, Browser, CloneTokenManager |
+| **Librarian** | `@semiont/make-meaning/librarian-main` | Gatherer, Matcher |
+| **Smelter** | `@semiont/make-meaning/smelter-main` | Smelter |
+| **Weaver** | `@semiont/make-meaning/weaver-main` | Weaver |
 
-Two **projection pipelines** follow the event log to keep the eventually-consistent read models in sync — addressed by no one, replying to nothing:
+`startMakeMeaning()` still assembles the **whole** set in one process — that is what `LocalTransport`, scripts and tests use, and it is unchanged. `startMakeMeaningGateway()` is the split-topology root: same stores, no actors, a handler subset.
 
-- **Weaver** (project) — subscribes to graph-relevant domain events and projects them into the graph database; carried on the KB record (`kb.weaver`) and rebuilt from the event log at startup (`rebuildAll()`)
-- **Smelter** (embed) — standalone embedding pipeline run via `@semiont/make-meaning/smelter-main` (not started by `startMakeMeaning`); subscribes to domain events, reads content from the KB working tree via `WorkerContentTransport`, chunks text, embeds via `@semiont/vectors`, and indexes into the vector store (Qdrant). On startup it reconciles Qdrant against the KS catalog — re-embedding what's missing or stale (every upsert is stamped with the embedded bytes' checksum, so changed content is detected) and deleting orphans — so a wiped Qdrant volume, or events missed while the worker was down, recover by restarting the smelter
+### The access actors — the bus-facing interface of the Knowledge Base
 
-(The third derived read model — the materialized views — is not pipeline-maintained: the EventStore's `ViewManager` materializes views synchronously inside `appendEvent()` for a read-your-writes guarantee.)
+- **Stower** (write, *Archivist*) — the single write gateway to the Knowledge Base; handles all resource and annotation mutations and job lifecycle events. The only caller that appends events
+- **Browser** (read, *Archivist*) — handles all KB read queries: resources, annotations, events, annotation history, referenced-by lookups, entity type and tag-schema listing, the collaborator directory (the KB's declared software agents, derived from the workers/actors inference config), and directory browse (merging filesystem listings with KB metadata)
+- **Gatherer** (context assembly, *Librarian*) — 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, *Librarian*) — context-driven candidate search with multi-source retrieval, composite structural scoring, and optional LLM semantic scoring
+- **CloneTokenManager** (yield, *Archivist*) — manages clone token lifecycle for resource cloning
+
+**Stower and Browser stay together on purpose:** Stower writes the events and projections that Browser reads, so splitting them would open a cross-process read-after-write window over the same state. Git is single-writer for the same reason — the Archivist owns the working tree.
+
+### The projection pipelines — addressed by no one, replying to nothing
+
+- **Weaver** (project, *Weaver service*) — subscribes to graph-relevant domain events and projects them into the graph database. It rebuilds from the event log only on an explicit `weave:rebuild`, so a projection-shape change needs that command, not just a restart
+- **Smelter** (embed, *Smelter service*) — subscribes to domain events, reads content through `WorkerContentTransport`, chunks text, embeds via `@semiont/vectors`, and indexes into the vector store (Qdrant). It also owns anchored-text extraction. On startup it reconciles Qdrant against the KS catalog — re-embedding what's missing or stale (every upsert is stamped with the embedded bytes' checksum, so changed content is detected) and deleting orphans — so a wiped Qdrant volume, or events missed while it was down, recover by restarting it
+
+(The third derived read model — the materialized views — is not pipeline-maintained: the EventStore's `ViewManager` materializes views synchronously inside `appendEvent()` for a read-your-writes guarantee. The Archivist rebuilds them at startup; unlike the graph, they need no explicit command.)
 
 All seven actors subscribe to the EventBus via RxJS pipelines and expose no public business methods — only `initialize()` and `stop()`, plus a startup recovery entry point on the pipelines (`rebuildAll()` / `reconcile()`). Callers communicate with the access 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 `@semiont/http-transport` exposes the same operations via verb-oriented namespaces (`semiont.browse`, `semiont.mark`, `semiont.gather`, etc.).
+The EventBus is a **complete interface** for all knowledge-domain operations. HTTP routes in the gateway are thin wrappers that delegate to EventBus actors. The `@semiont/http-transport` exposes the same operations via verb-oriented namespaces (`semiont.browse`, `semiont.mark`, `semiont.gather`, etc.).
 
 ## Quick Start
 
@@ -45,7 +58,9 @@ import type { Logger } from '@semiont/core';
 
 // EventBus is created outside make-meaning — it is not encapsulated by this package
 const eventBus = new EventBus();
-const project = new SemiontProject('/path/to/project');
+const project = new SemiontProject('/path/to/project', {
+  anchoredTextDir: process.env.SEMIONT_ANCHORED_TEXT_DIR!,
+});
 
 // Start all infrastructure
 const makeMeaning = await startMakeMeaning(project, config, eventBus, logger);
@@ -103,7 +118,7 @@ All meaningful actions flow through the EventBus. The KB actors are reactive —
 
 ```mermaid
 graph TB
-    Routes["Backend Routes"] -->|commands| BUS["Event Bus"]
+    Routes["Gateway Routes"] -->|commands| BUS["Event Bus"]
     Workers["Job Workers"] -->|commands| BUS
     EBC["SemiontClient"] -->|commands| BUS
 
@@ -183,7 +198,7 @@ const kb = await createKnowledgeBase(eventStore, project, graphDb, eventBus, log
 
 ### EventBus Ownership
 
-The EventBus is created by the backend (or script) and passed into `startMakeMeaning()` as a dependency. Make-meaning does not own or encapsulate the EventBus — it is shared across the entire system.
+The EventBus is created by the gateway (or script) and passed into `startMakeMeaning()` as a dependency. Make-meaning does not own or encapsulate the EventBus — it is shared across the entire system.
 
 ### Pure projection validators
 
@@ -204,7 +219,7 @@ This pattern (functional core, imperative shell) is shared with `@semiont/event-
 - **[API Reference](./docs/api-reference.md)** — Context modules and operations
 - **[Examples](./docs/examples.md)** — Common use cases and patterns
 - **[Job Workers](./docs/job-workers.md)** — Async annotation workers (in @semiont/jobs)
-- **[Scripting](./docs/SCRIPTING.md)** — Direct scripting without HTTP backend
+- **[Scripting](./docs/SCRIPTING.md)** — Direct scripting without HTTP gateway
 
 ## Exports
 

package/dist/archivist-main.d.ts

@@ -0,0 +1,2 @@
+
+export { };