@semiont/make-meaning 0.5.5 → 0.5.7

package/README.md

@@ -8,18 +8,26 @@
 
 **Making meaning from resources through actors, context assembly, and relationship reasoning.**
 
-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:
+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:
 
 - **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)
+- **Browser** (read) — handles all KB read queries: resources, annotations, events, annotation history, referenced-by lookups, entity type and tag-schema 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`, 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.
+Two **projection pipelines** follow the event log to keep the eventually-consistent read models in sync — addressed by no one, replying to nothing:
+
+- **Graph Consumer** (project) — subscribes to graph-relevant domain events and projects them into the graph database; carried on the KB record (`kb.graphConsumer`) 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 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.)
+
+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/api-client` 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 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.).
 
 ## Quick Start
 
@@ -44,7 +52,7 @@ const makeMeaning = await startMakeMeaning(project, config, eventBus, logger);
 
 // Access components
 const { knowledgeSystem, jobQueue } = makeMeaning;
-const { kb, stower, browser, gatherer, matcher, smelter, cloneTokenManager } = knowledgeSystem;
+const { kb, stower, browser, gatherer, matcher, cloneTokenManager } = knowledgeSystem;
 
 // Graceful shutdown
 await makeMeaning.stop();
@@ -52,33 +60,37 @@ await makeMeaning.stop();
 
 This single call initializes:
 - **KnowledgeSystem** — groups the Knowledge Base and its actors
-  - **KnowledgeBase** — groups EventStore, ViewStorage, WorkingTreeStore, GraphDatabase, GraphDBConsumer, and optionally VectorStore and Smelter
+  - **KnowledgeBase** — groups EventStore, ViewStorage, WorkingTreeStore, GraphDatabase, GraphDBConsumer, and optionally VectorStore
   - **Stower** — subscribes to write commands on EventBus
   - **Browser** — subscribes to all KB read queries and directory browse requests on EventBus
   - **Gatherer** — subscribes to annotation and resource gather requests on EventBus; searches vectors for semantically similar passages
   - **Matcher** — subscribes to candidate search requests on EventBus
-  - **Smelter** — subscribes to resource/annotation events, chunks text, embeds, indexes into Qdrant
   - **CloneTokenManager** — subscribes to clone token operations on EventBus
 - **JobQueue** — background job processing queue + job status subscription
-- **6 annotation workers** — poll job queue for async AI tasks
+- **Bus command handlers** — request-channel translators registered via `registerBusHandlers`
+
+It does **not** start the Smelter (a standalone process — `@semiont/make-meaning/smelter-main`) or the job workers (the worker process in [@semiont/jobs](../jobs/) — see [Job Workers](./docs/job-workers.md)).
 
 ### Gather Context (via EventBus)
 
 ```typescript
 import { firstValueFrom, race, filter, timeout } from 'rxjs';
 
+const correlationId = crypto.randomUUID();
+
 // Emit gather request for an annotation
 eventBus.get('gather:requested').next({
-  annotationUri,
+  correlationId,
+  annotationId,
   resourceId,
-  options: { contextLines: 5 },
+  options: { contextWindow: 1000 },
 });
 
 // Await result
 const result = await firstValueFrom(
   race(
-    eventBus.get('gather:complete').pipe(filter(e => e.annotationUri === annotationUri)),
-    eventBus.get('gather:failed').pipe(filter(e => e.annotationUri === annotationUri)),
+    eventBus.get('gather:complete').pipe(filter(e => e.correlationId === correlationId)),
+    eventBus.get('gather:failed').pipe(filter(e => e.correlationId === correlationId)),
   ).pipe(timeout(30_000)),
 );
 ```
@@ -93,14 +105,15 @@ 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["SemiontApiClient"] -->|commands| BUS
+    EBC["SemiontClient"] -->|commands| BUS
 
     subgraph ks ["Knowledge System"]
         STOWER["Stower<br/>(write)"]
         BROWSER["Browser<br/>(read)"]
         GATHERER["Gatherer<br/>(context assembly)"]
         MATCHER["Matcher<br/>(search/link)"]
-        SMELTER["Smelter<br/>(embed)"]
+        SMELTER["Smelter<br/>(embed pipeline, standalone process)"]
+        GC["Graph Consumer<br/>(graph pipeline)"]
         CTM["CloneTokenManager<br/>(clone)"]
         KB["Knowledge Base"]
         VECTORS["Vector Store<br/>(Qdrant)"]
@@ -112,21 +125,22 @@ graph TB
         MATCHER -->|search| VECTORS
         SMELTER -->|embed & index| VECTORS
         SMELTER -->|read| KB
+        GC -->|project| KB
         CTM -->|query| KB
     end
 
-    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 -->|"yield:create, yield:update, yield:mv<br/>mark:create, mark:delete, mark:update-body<br/>frame:add-entity-type, frame:add-tag-schema<br/>mark:archive, mark:unarchive, mark:update-entity-types<br/>job:start, job:complete, job:fail"| 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:tag-schemas-requested, 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 -->|"domain events:<br/>yield:created, yield:updated<br/>yield:representation-added<br/>mark:added, mark:removed, mark:archived"| SMELTER
+    BUS -->|"graph-relevant<br/>domain events"| GC
     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/>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
+    STOWER -->|"yield:create-ok, yield:update-ok, yield:move-ok<br/>mark:delete-ok, *-failed replies<br/>(domain events are republished onto the bus<br/>by the EventStore: yield:created, mark: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:tag-schemas-result, 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: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
@@ -136,7 +150,7 @@ graph TB
 
     class BUS bus
     classDef vectorstore fill:#6b8e9d,stroke:#4a6a7a,stroke-width:2px,color:#fff
-    class STOWER,BROWSER,GATHERER,MATCHER,SMELTER,CTM actor
+    class STOWER,BROWSER,GATHERER,MATCHER,SMELTER,GC,CTM actor
     class KB kb
     class VECTORS vectorstore
     class Routes,Workers,EBC caller
@@ -146,24 +160,25 @@ graph TB
 
 The **Knowledge System** binds the Knowledge Base to its actors. Nothing outside the Knowledge System reads or writes the Knowledge Base directly.
 
-The **Knowledge Base** is an inert store — it has no intelligence, no goals, no decisions. It groups five core subsystems and two optional ones:
+The **Knowledge Base** is an inert store — it has no intelligence, no goals, no decisions. It groups five core subsystems and one optional one:
 
 | Store | Implementation | Purpose |
 |-------|---------------|---------|
 | **Event Log** | `EventStore` | Immutable append-only log of all domain events |
-| **Materialized Views** | `ViewStorage` | Denormalized projections for fast reads |
+| **Materialized Views** | `ViewStorage` | Denormalized projections for fast reads (materialized synchronously on append) |
 | **Content Store** | `WorkingTreeStore` | Working-tree files addressed by URI |
 | **Graph** | `GraphDatabase` | Eventually consistent relationship projection |
-| **Graph Consumer** | `GraphDBConsumer` | Event-to-graph synchronization pipeline |
+| **Graph Consumer** | `GraphDBConsumer` | Event-to-graph projection pipeline (one of the two pipeline actors; carried on the KB record because `createKnowledgeBase()` constructs and starts it) |
 | **Vectors** *(optional)* | `VectorStore` | Semantic vector index (Qdrant + memory) via `@semiont/vectors` |
-| **Smelter** *(optional)* | `Smelter` | Embedding pipeline actor (chunk, embed, index) |
+
+Its sibling pipeline, the Smelter (event-to-vector projection), is **not** a KB member — it runs as a standalone process via `@semiont/make-meaning/smelter-main`.
 
 ```typescript
 import { createKnowledgeBase } from '@semiont/make-meaning';
 
-const kb = await createKnowledgeBase(eventStore, project, graphDb, logger);
+const kb = await createKnowledgeBase(eventStore, project, graphDb, eventBus, logger, options);
 // kb.eventStore, kb.views, kb.content, kb.graph, kb.graphConsumer
-// kb.vectors (optional), kb.smelter (optional)
+// kb.vectors (optional), kb.projectionsDir
 ```
 
 ### EventBus Ownership
@@ -196,7 +211,7 @@ This pattern (functional core, imperative shell) is shared with `@semiont/event-
 ### Service (Primary)
 
 - `startMakeMeaning(project, config, eventBus, logger)` — Initialize all infrastructure
-- `MakeMeaningService` — Type for service return value (`knowledgeSystem`, `jobQueue`, `workers`, `stop`)
+- `MakeMeaningService` — Type for service return value (`knowledgeSystem`, `jobQueue`, `stop`)
 
 ### Knowledge System
 
@@ -205,8 +220,8 @@ This pattern (functional core, imperative shell) is shared with `@semiont/event-
 
 ### Knowledge Base
 
-- `createKnowledgeBase(eventStore, project, graphDb, logger)` — Async factory function
-- `KnowledgeBase` — Interface grouping the five KB stores (including `graphConsumer`)
+- `createKnowledgeBase(eventStore, project, graphDb, eventBus, logger, options?)` — Async factory function
+- `KnowledgeBase` — Interface grouping the KB stores (`eventStore`, `views`, `content`, `graph`, optional `vectors`) plus the `graphConsumer` pipeline
 
 ### Actors
 
@@ -214,8 +229,10 @@ This pattern (functional core, imperative shell) is shared with `@semiont/event-
 - `Browser` — Read actor (all KB queries, directory listings merged with KB metadata)
 - `Gatherer` — Context assembly actor (annotation and resource gather flows; vector semantic search)
 - `Matcher` — Search/link actor (context-driven candidate search with structural + semantic scoring)
-- `Smelter` — Embedding pipeline actor (chunk, embed, persist, index into vector store)
 - `CloneTokenManager` — Clone token lifecycle actor (yield domain)
+- `Smelter` / `createSmelterActorStateUnit` / `WorkerContentTransport` — the embedding pipeline, its domain-event fan-in, and the worker-side content transport; wired together by the standalone `@semiont/make-meaning/smelter-main` entry point, and exported for callers that run the pipeline on their own `WorkerBus`
+
+The Graph Consumer (`GraphDBConsumer`) is not exported — `createKnowledgeBase()` constructs it internally and exposes it as `kb.graphConsumer`.
 
 ### Operations
 
@@ -237,7 +254,7 @@ This pattern (functional core, imperative shell) is shared with `@semiont/event-
 ## Dependencies
 
 - **[@semiont/core](../core/)** — Core types, EventBus, utilities
-- **[@semiont/api-client](../api-client/)** — OpenAPI-generated types
+- **[@semiont/http-transport](../http-transport/)** — OpenAPI-generated types
 - **[@semiont/event-sourcing](../event-sourcing/)** — Event store and view storage
 - **[@semiont/content](../content/)** — Content-addressed storage
 - **[@semiont/graph](../graph/)** — Graph database abstraction
@@ -245,6 +262,8 @@ This pattern (functional core, imperative shell) is shared with `@semiont/event-
 - **[@semiont/inference](../inference/)** — AI primitives (generateText)
 - **[@semiont/vectors](../vectors/)** — Vector store abstraction (Qdrant + memory) and embedding providers (Voyage, Ollama)
 - **[@semiont/jobs](../jobs/)** — Job queue and annotation workers
+- **[@semiont/observability](../observability/)** — Actor spans and metrics providers
+- **[@semiont/sdk](../sdk/)** — `StateUnit` / `WorkerBus` types (used by the Smelter actor state unit)
 
 ## Testing
 

package/dist/index.d.ts

@@ -1,14 +1,13 @@
 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, SemiontError, UserDID, EventMap, IContentTransport, PutBinaryRequest, PutBinaryOptions, ContentFormat as ContentFormat$1, AccessToken, Annotation, UserId, ResourceAnnotations, AnnotationCategory, GraphPath, GraphConnection } from '@semiont/core';
-export { AssembledAnnotation, applyBodyOperations, assembleAnnotation } from '@semiont/core';
+import { GraphServiceConfig, VectorsServiceConfig, EmbeddingServiceConfig, EventBus, Logger, StoredEvent, ResourceId, ResourceDescriptor, AnnotationId, components, ITransport, BaseUrl, ConnectionState, SemiontError, UserDID, EventMap, IContentTransport, PutBinaryRequest, PutBinaryOptions, AccessToken, Annotation, UserId, ResourceAnnotations, AnnotationCategory, GraphPath, GraphConnection } 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 { VectorStore, EmbeddingProvider, ChunkingConfig } from '@semiont/vectors';
 import { InferenceClient } from '@semiont/inference';
 import { BehaviorSubject, Observable } from 'rxjs';
-import { StateUnit, WorkerBus } from '@semiont/sdk';
+import { StateUnit, WorkerBus, BusRequestPrimitive } from '@semiont/sdk';
 import { Writable, Readable } from 'node:stream';
 
 /**
@@ -195,7 +194,7 @@ declare function createKnowledgeBase(eventStore: EventStore, project: SemiontPro
  *
  * The single write gateway to the Knowledge Base. Subscribes to command
  * events on the EventBus and translates them into domain events on the
- * EventStore + content writes to the RepresentationStore.
+ * EventStore + content operations on the WorkingTreeStore.
  *
  * From ARCHITECTURE.md:
  * The Knowledge Base has exactly three actor interfaces:
@@ -203,7 +202,8 @@ declare function createKnowledgeBase(eventStore: EventStore, project: SemiontPro
  * - Gatherer (read context)
  * - Matcher (read search)
  *
- * No other code should call eventStore.appendEvent() or repStore.store().
+ * No other code should call eventStore.appendEvent() or mutate the working tree
+ * through kb.content.
  *
  * Subscriptions:
  * - yield:create       → resource.created (+ content store)   → yield:created / yield:create-failed
@@ -348,6 +348,11 @@ declare class Matcher {
     /**
      * Search vectors for semantically similar resources.
      * Returns empty array if vectors or embedding provider are not configured.
+     *
+     * No entity-type filter: the annotation's entity types are a ranking signal
+     * (Jaccard + IDF in `contextDrivenSearch`), not an inclusion gate. Gating
+     * recall here would hide vector-similar but differently-tagged candidates
+     * from the scorer.
      */
     private searchVectors;
     stop(): Promise<void>;
@@ -430,12 +435,16 @@ declare class CloneTokenManager {
  * Nothing outside the KnowledgeSystem reads or writes the KnowledgeBase directly.
  *
  * - kb:                the durable store (event log, views, content, graph)
- * - stower:            write actor — weaves new knowledge in
- * - gatherer:          read actor — traces threads to build context
- * - matcher:           search actor — finds related threads
- * - browser:           filesystem actor — lists project directories
+ * - stower:            write actor — the single write gateway
+ * - browser:           read actor — all KB queries plus directory listings
+ * - gatherer:          context-assembly actor — builds GatheredContext from passage, graph, and vectors
+ * - matcher:           search actor — context-driven candidate search and scoring
  * - cloneTokenManager: token actor — manages resource clone tokens
  *
+ * These are the five access actors. Two projection-pipeline actors complete
+ * the seven: the Graph Consumer (kb.graphConsumer, started by
+ * createKnowledgeBase) and the Smelter (standalone process via smelter-main).
+ *
  * EventBus, JobQueue, and workers are peers to KnowledgeSystem, not members.
  */
 
@@ -556,27 +565,34 @@ declare class LocalTransport implements ITransport {
  * resource-creation pipeline the HTTP `/resources` handler uses.
  */
 
+type GetResourceResponse = components['schemas']['GetResourceResponse'];
 declare class LocalContentTransport implements IContentTransport {
     private readonly ks;
     constructor(ks: KnowledgeSystem);
     putBinary(_request: PutBinaryRequest, _options?: PutBinaryOptions): Promise<{
         resourceId: ResourceId;
     }>;
-    getBinary(resourceId: ResourceId, options?: {
-        accept?: ContentFormat$1 | string;
+    getBinary(resourceId: ResourceId, _options?: {
         auth?: AccessToken;
     }): Promise<{
         data: ArrayBuffer;
         contentType: string;
     }>;
-    getBinaryStream(resourceId: ResourceId, options?: {
-        accept?: ContentFormat$1 | string;
+    getBinaryStream(resourceId: ResourceId, _options?: {
         auth?: AccessToken;
     }): Promise<{
         stream: ReadableStream<Uint8Array>;
         contentType: string;
     }>;
     private loadBinary;
+    /**
+     * Assemble the resource's JSON-LD graph in-process from the KB — the local
+     * realization of `IContentTransport.getResourceGraph` (symmetric with
+     * getBinary; SIMPLER-JSON-LD.md decision 7). Local mode has no auth.
+     */
+    getResourceGraph(resourceId: ResourceId, _options?: {
+        auth?: AccessToken;
+    }): Promise<GetResourceResponse>;
     dispose(): void;
 }
 
@@ -704,11 +720,178 @@ interface SmelterActorStateUnitOptions {
 }
 interface SmelterActorStateUnit extends StateUnit {
     events$: Observable<SmelterEvent>;
-    emit(channel: string, payload: Record<string, unknown>): Promise<void>;
     start(): void;
 }
 declare function createSmelterActorStateUnit(options: SmelterActorStateUnitOptions): SmelterActorStateUnit;
 
+/**
+ * Smelter — event-to-vector pipeline for the standalone smelter worker.
+ *
+ * Consumes the smelter-relevant domain events surfaced by
+ * `SmelterActorStateUnit.events$`, reads resource content via the injected
+ * `IContentTransport` (HTTP verbatim mode in worker deployments — the
+ * stored bytes, untouched), chunks and embeds it via the configured
+ * EmbeddingProvider, and indexes vectors into the VectorStore (Qdrant).
+ * `smelter-main` is the container entry point that wires this up.
+ *
+ * ## 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.
+ *
+ * ## Batching
+ *
+ * `burstBuffer` collects event bursts per resource; consecutive same-type
+ * runs within a burst share a single `embedBatch()` call.
+ *
+ * ## Reconciliation
+ *
+ * Qdrant is an ephemeral projection of the event log. `reconcile()` brings
+ * it back in sync at startup — after a wiped volume, or after events missed
+ * while the worker was down. It is a planner: it diffs the store against the
+ * catalog (over the `browse:*` RPC channels) — both membership AND content
+ * freshness, via the checksum stamped onto every resource upsert — and
+ * enqueues `smelt:*` work items through the same mailbox as live events, so
+ * per-resource ordering holds across the two paths (axioms S1/S2/S11/S12 in
+ * `.plans/SMELTER-AXIOMS.md`).
+ */
+
+interface ReconcileSummary {
+    resourcesEmbedded: number;
+    resourceVectorsDeleted: number;
+    annotationsEmbedded: number;
+    annotationVectorsDeleted: number;
+}
+type ReconcileState = {
+    phase: 'pending';
+} | {
+    phase: 'running';
+} | {
+    phase: 'done';
+    summary: ReconcileSummary;
+} | {
+    phase: 'failed';
+    error: string;
+};
+/**
+ * Burst-buffer timings for the event pipeline. Required — `smelter-main`
+ * passes production values (50/100/200); test harnesses pass ~1ms values so
+ * property suites run at generator speed. See `.plans/SMELTER-AXIOMS.md` (D4).
+ */
+interface SmelterTiming {
+    burstWindowMs: number;
+    maxBatchSize: number;
+    idleTimeoutMs: number;
+}
+/**
+ * Reconcile-planner work items — enqueued through the same mailbox as wire
+ * events. Distinct `smelt:*` types make forged domain events unrepresentable
+ * (`.plans/SMELTER-AXIOMS.md`, D1); the shared shape lets the per-resource
+ * lanes and batch paths serve both kinds of input.
+ */
+interface SmelterWorkItem {
+    type: 'smelt:embed' | 'smelt:purge' | 'smelt:embed-annotation' | 'smelt:purge-annotation';
+    resourceId: string;
+    payload: Record<string, unknown>;
+}
+type SmelterInput = SmelterEvent | SmelterWorkItem;
+declare class Smelter {
+    private events$;
+    private vectorStore;
+    private embeddingProvider;
+    private content;
+    private bus;
+    private chunkingConfig;
+    private timing;
+    private logger;
+    private static readonly RECONCILE_PAGE_SIZE;
+    /** Bound on concurrently in-flight reconcile work — a cold rebuild must not fan out unbounded embedding calls. */
+    private static readonly RECONCILE_WAVE;
+    private eventSubject;
+    private sourceSubscription;
+    private pipelineSubscription;
+    private _eventsProcessed;
+    private _reconcileState;
+    private workDone;
+    private workWaiter;
+    constructor(events$: Observable<SmelterEvent>, vectorStore: VectorStore, embeddingProvider: EmbeddingProvider, content: IContentTransport, bus: BusRequestPrimitive, chunkingConfig: ChunkingConfig, timing: SmelterTiming, logger: Logger);
+    get eventsProcessed(): number;
+    get reconcileState(): ReconcileState;
+    initialize(): void;
+    stop(): void;
+    private noteWorkDone;
+    /**
+     * Returns the number of WIRE events processed without error (the S9b
+     * oracle) — `smelt:*` work-item runs tick the drain counter instead.
+     */
+    private processBatch;
+    /**
+     * Batch-optimized processing for consecutive events of the same type.
+     * Returns the number of events processed without error.
+     */
+    private applyBatchByType;
+    /** Returns true if the input was processed without error. */
+    private safeProcessEvent;
+    private processEvent;
+    private handleResourcePurge;
+    /**
+     * Resolve a resource's embeddable text: bytes via the content transport,
+     * gated to media types that decode as text, decoded charset-aware. The
+     * checksum is over the raw bytes actually read — stamped onto the vectors
+     * so reconciliation can compare against the catalog's claim (S12). Returns
+     * null (logged) when the resource doesn't decode as text, is unavailable,
+     * or is empty — callers skip it.
+     */
+    private fetchEmbeddableText;
+    private embedResource;
+    private handleResourceArchived;
+    private handleAnnotationAdded;
+    private handleAnnotationRemoved;
+    /**
+     * Batch-embed chunks from multiple yield:created events in a single
+     * embedBatch() call, then index per resource.
+     */
+    private batchResourceCreated;
+    /**
+     * Batch-embed exact texts from multiple mark:added events in a single
+     * embedBatch() call, then index per annotation.
+     */
+    private batchAnnotationAdded;
+    /**
+     * Reconcile the vector store against the KS catalog.
+     *
+     * Lists what IS indexed (via the store's id enumeration) and what SHOULD
+     * be (non-archived resources with embeddable media types, plus their
+     * exact-text annotations, via the `browse:*` RPC channels), then plans the
+     * diff as `smelt:*` work items — embeds for what's missing, purges for
+     * what shouldn't be there — and drains them through the pipeline mailbox.
+     * Work items share the per-resource lanes with live events, so a reconcile
+     * re-embed can never interleave with (or stale-overwrite) live processing
+     * of the same resource (axioms S1/S2). Waves of RECONCILE_WAVE bound how
+     * many embedding calls a cold rebuild has in flight.
+     *
+     * Call after the live subscription is attached so nothing falls in the
+     * gap. The index snapshot is taken BEFORE the catalog listing so a
+     * resource indexed by a live event mid-reconcile is never mistaken for an
+     * orphan; convergence holds because every upsert replaces a resource's
+     * full vector set from current content.
+     */
+    reconcile(): Promise<ReconcileSummary>;
+    /**
+     * Enqueue planner work through the mailbox in bounded waves and await
+     * completion. The pipeline ticks `noteWorkDone` for every consumed work
+     * item (success or failure — failures are logged like any live event), so
+     * each wave's waiter resolves exactly when its items have been processed.
+     */
+    private drain;
+    /** Page through `browse:resources-requested` until the catalog is exhausted. */
+    private listAllResources;
+}
+
 /**
  * Exchange Format Manifest Types
  *
@@ -755,9 +938,9 @@ declare function validateManifestVersion(version: number): void;
  *
  * Produces a lossless tar.gz archive of the system of record:
  * - Event log (all streams, JSONL format)
- * - Content store (content-addressed blobs)
+ * - Working-tree content (archived as checksum-named blobs)
  *
- * Reads events via EventStore and content via RepresentationStore.
+ * Reads events via EventStore and content via WorkingTreeStore.
  * The archive can restore a complete knowledge base.
  */
 
@@ -935,7 +1118,7 @@ declare function importLinkedData(archive: Readable, options: LinkedDataImporter
  * Business logic for resource operations. All writes go through the EventBus
  * — the Stower actor subscribes and handles persistence.
  *
- * For create: emits yield:create, awaits yield:created / yield:create-failed.
+ * For create: emits yield:create, awaits yield:create-ok / yield:create-failed.
  */
 
 type ContentFormat = components['schemas']['ContentFormat'];
@@ -1237,8 +1420,5 @@ declare function generateResourceSummary(resourceName: string, content: string,
  */
 declare function generateReferenceSuggestions(referenceTitle: string, client: InferenceClient, entityType?: string, currentContent?: string): Promise<string[] | null>;
 
-declare const PACKAGE_NAME = "@semiont/make-meaning";
-declare const VERSION = "0.1.0";
-
-export { AnnotationContext, AnnotationOperations, BACKUP_FORMAT, Browser, CloneTokenManager, FORMAT_VERSION, Gatherer$1 as Gatherer, GraphContext, LLMContext, LocalContentTransport, LocalTransport, Matcher, PACKAGE_NAME, ResourceContext, ResourceOperations, Stower, VERSION, bootstrapEntityTypes, createKnowledgeBase, createSmelterActorStateUnit, exportBackup, exportLinkedData, generateReferenceSuggestions, generateResourceSummary, importBackup, importLinkedData, isBackupManifest, readEntityTypesProjection, registerAnnotationAssemblyHandler, registerAnnotationLookupHandlers, registerBindUpdateBodyHandler, registerBusHandlers, registerJobCommandHandlers, startMakeMeaning, stopKnowledgeSystem, validateManifestVersion };
-export type { BackupContentReader, BackupEventStoreReader, BackupExporterOptions, BackupImportResult, BackupImporterOptions, BackupManifestHeader, BackupStreamSummary, BuildContextOptions, ContentBlobResolver, CreateAnnotationResult, CreateResourceInput, CreateResourceResult, GraphEdge, GraphNode, GraphRepresentation, KnowledgeBase, KnowledgeSystem, LLMContextOptions, LinkedDataContentReader, LinkedDataExporterOptions, LinkedDataImportResult, LinkedDataImporterOptions, LinkedDataViewReader, ListResourcesFilters, LocalTransportConfig, MakeMeaningConfig, MakeMeaningService, ReplayStats, SmelterActorStateUnit, SmelterActorStateUnitOptions, SmelterEvent, UpdateAnnotationBodyResult };
+export { AnnotationContext, AnnotationOperations, BACKUP_FORMAT, Browser, CloneTokenManager, FORMAT_VERSION, Gatherer$1 as Gatherer, GraphContext, LLMContext, LocalContentTransport, LocalTransport, Matcher, ResourceContext, ResourceOperations, Smelter, Stower, bootstrapEntityTypes, createKnowledgeBase, createSmelterActorStateUnit, exportBackup, exportLinkedData, generateReferenceSuggestions, generateResourceSummary, importBackup, importLinkedData, isBackupManifest, readEntityTypesProjection, registerAnnotationAssemblyHandler, registerAnnotationLookupHandlers, registerBindUpdateBodyHandler, registerBusHandlers, registerJobCommandHandlers, startMakeMeaning, stopKnowledgeSystem, validateManifestVersion };
+export type { BackupContentReader, BackupEventStoreReader, BackupExporterOptions, BackupImportResult, BackupImporterOptions, BackupManifestHeader, BackupStreamSummary, BuildContextOptions, ContentBlobResolver, CreateAnnotationResult, CreateResourceInput, CreateResourceResult, GraphEdge, GraphNode, GraphRepresentation, KnowledgeBase, KnowledgeSystem, LLMContextOptions, LinkedDataContentReader, LinkedDataExporterOptions, LinkedDataImportResult, LinkedDataImporterOptions, LinkedDataViewReader, ListResourcesFilters, LocalTransportConfig, MakeMeaningConfig, MakeMeaningService, ReconcileState, ReconcileSummary, ReplayStats, SmelterActorStateUnit, SmelterActorStateUnitOptions, SmelterEvent, SmelterInput, SmelterTiming, SmelterWorkItem, UpdateAnnotationBodyResult };