@semiont/make-meaning 0.4.2 → 0.4.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -13,6 +13,7 @@ This package implements the actor model from [ARCHITECTURE.md](../../docs/ARCHIT
13
13
  - **Stower** (write) — the single write gateway to the Knowledge Base
14
14
  - **Gatherer** (read) — handles all browse reads, context assembly (passage + graph neighborhood + optional inference summary), and entity type listing
15
15
  - **Matcher** (search/link) — context-driven search with multi-source retrieval, composite structural scoring, optional LLM semantic scoring, and graph queries
16
+ - **Browser** (filesystem reads) — merges live filesystem directory listings with KB metadata for tracked resources
16
17
  - **CloneTokenManager** (yield) — manages clone token lifecycle for resource cloning
17
18
 
18
19
  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.
@@ -29,29 +30,33 @@ npm install @semiont/make-meaning
29
30
 
30
31
  ```typescript
31
32
  import { startMakeMeaning } from '@semiont/make-meaning';
33
+ import { SemiontProject } from '@semiont/core/node';
32
34
  import { EventBus } from '@semiont/core';
33
- import type { EnvironmentConfig, Logger } from '@semiont/core';
35
+ import type { Logger } from '@semiont/core';
34
36
 
35
37
  // EventBus is created outside make-meaning — it is not encapsulated by this package
36
38
  const eventBus = new EventBus();
39
+ const project = new SemiontProject('/path/to/project');
37
40
 
38
41
  // Start all infrastructure
39
- const makeMeaning = await startMakeMeaning(config, eventBus, logger);
42
+ const makeMeaning = await startMakeMeaning(project, config, eventBus, logger);
40
43
 
41
44
  // Access components
42
- const { kb, jobQueue, stower, gatherer, matcher, cloneTokenManager } = makeMeaning;
45
+ const { knowledgeSystem, jobQueue } = makeMeaning;
46
+ const { kb, stower, gatherer, matcher, browser, cloneTokenManager } = knowledgeSystem;
43
47
 
44
48
  // Graceful shutdown
45
49
  await makeMeaning.stop();
46
50
  ```
47
51
 
48
52
  This single call initializes:
49
- - **KnowledgeBase** — groups EventStore, ViewStorage, RepresentationStore, GraphDatabase
50
- - **Stower** — subscribes to write commands on EventBus
51
- - **Gatherer** — subscribes to browse reads, gather context, and entity type listing on EventBus
52
- - **Matcher** — subscribes to search and referenced-by queries on EventBus
53
- - **CloneTokenManager** — subscribes to clone token operations on EventBus
54
- - **GraphDBConsumer** — event-to-graph synchronization (RxJS burst-buffered pipeline)
53
+ - **KnowledgeSystem** — groups the Knowledge Base and its actors
54
+ - **KnowledgeBase** — groups EventStore, ViewStorage, ContentStore, GraphDatabase, and GraphDBConsumer
55
+ - **Stower** — subscribes to write commands on EventBus
56
+ - **Gatherer** — subscribes to browse reads, gather context, and entity type listing on EventBus
57
+ - **Matcher** — subscribes to search and referenced-by queries on EventBus
58
+ - **Browser** — subscribes to directory browse requests, merging filesystem + KB metadata
59
+ - **CloneTokenManager** — subscribes to clone token operations on EventBus
55
60
  - **JobQueue** — background job processing queue + job status subscription
56
61
  - **6 annotation workers** — poll job queue for async AI tasks
57
62
 
@@ -101,7 +106,7 @@ const result = await firstValueFrom(
101
106
 
102
107
  ### Actor Model
103
108
 
104
- All meaningful actions flow through the EventBus. The three KB actors are reactive — they subscribe via RxJS pipelines in `initialize()` and communicate results by emitting on the bus.
109
+ All meaningful actions flow through the EventBus. The KB actors are reactive — they subscribe via RxJS pipelines in `initialize()` and communicate results by emitting on the bus.
105
110
 
106
111
  ```mermaid
107
112
  graph TB
@@ -109,19 +114,30 @@ graph TB
109
114
  Workers["Job Workers"] -->|commands| BUS
110
115
  EBC["EventBusClient"] -->|commands| BUS
111
116
 
112
- BUS -->|"yield:create, mark:create,<br/>mark:delete, job:*"| STOWER["Stower<br/>(write)"]
113
- BUS -->|"browse:*, gather:*,<br/>mark:entity-types-*"| GATHERER["Gatherer<br/>(read)"]
114
- BUS -->|"bind:search-*,<br/>bind:referenced-by-*"| MATCHER["Matcher<br/>(search/link)"]
115
- BUS -->|"yield:clone-*"| CTM["CloneTokenManager<br/>(clone)"]
116
-
117
- STOWER -->|persist| KB["Knowledge Base"]
118
- GATHERER -->|query| KB
119
- MATCHER -->|query| KB
120
- CTM -->|query| KB
117
+ subgraph ks ["Knowledge System"]
118
+ STOWER["Stower<br/>(write)"]
119
+ GATHERER["Gatherer<br/>(read)"]
120
+ MATCHER["Matcher<br/>(search/link)"]
121
+ BROWSER["Browser<br/>(filesystem)"]
122
+ CTM["CloneTokenManager<br/>(clone)"]
123
+ KB["Knowledge Base"]
124
+ STOWER -->|persist| KB
125
+ GATHERER -->|query| KB
126
+ MATCHER -->|query| KB
127
+ BROWSER -->|query| KB
128
+ CTM -->|query| KB
129
+ end
130
+
131
+ BUS -->|"yield:create, mark:create,<br/>mark:delete, job:*"| STOWER
132
+ BUS -->|"browse:*, gather:*,<br/>mark:entity-types-*"| GATHERER
133
+ BUS -->|"bind:search-*,<br/>bind:referenced-by-*"| MATCHER
134
+ BUS -->|"browse:directory-*"| BROWSER
135
+ BUS -->|"yield:clone-*"| CTM
121
136
 
122
137
  STOWER -->|"yield:created, mark:created"| BUS
123
138
  GATHERER -->|"browse:*-result,<br/>gather:complete"| BUS
124
139
  MATCHER -->|"bind:search-results,<br/>bind:referenced-by-result"| BUS
140
+ BROWSER -->|"browse:directory-result"| BUS
125
141
  CTM -->|"yield:clone-token-generated,<br/>yield:clone-resource-result"| BUS
126
142
 
127
143
  classDef bus fill:#e8a838,stroke:#b07818,stroke-width:3px,color:#000,font-weight:bold
@@ -130,27 +146,30 @@ graph TB
130
146
  classDef caller fill:#4a90a4,stroke:#2c5f7a,stroke-width:2px,color:#fff
131
147
 
132
148
  class BUS bus
133
- class STOWER,GATHERER,MATCHER,CTM actor
149
+ class STOWER,GATHERER,MATCHER,BROWSER,CTM actor
134
150
  class KB kb
135
151
  class Routes,Workers,EBC caller
136
152
  ```
137
153
 
138
- ### Knowledge Base
154
+ ### Knowledge System and Knowledge Base
139
155
 
140
- The Knowledge Base is an inert store it has no intelligence, no goals, no decisions. It groups four subsystems:
156
+ The **Knowledge System** binds the Knowledge Base to its actors. Nothing outside the Knowledge System reads or writes the Knowledge Base directly.
157
+
158
+ The **Knowledge Base** is an inert store — it has no intelligence, no goals, no decisions. It groups five subsystems:
141
159
 
142
160
  | Store | Implementation | Purpose |
143
161
  |-------|---------------|---------|
144
162
  | **Event Log** | `EventStore` | Immutable append-only log of all domain events |
145
163
  | **Materialized Views** | `ViewStorage` | Denormalized projections for fast reads |
146
- | **Content Store** | `RepresentationStore` | Content-addressed binary storage (SHA-256) |
164
+ | **Content Store** | `WorkingTreeStore` | Content-addressed binary storage (SHA-256) |
147
165
  | **Graph** | `GraphDatabase` | Eventually consistent relationship projection |
166
+ | **Graph Consumer** | `GraphDBConsumer` | Event-to-graph synchronization pipeline |
148
167
 
149
168
  ```typescript
150
169
  import { createKnowledgeBase } from '@semiont/make-meaning';
151
170
 
152
- const kb = createKnowledgeBase(eventStore, basePath, projectRoot, graphDb, logger);
153
- // kb.eventStore, kb.views, kb.content, kb.graph
171
+ const kb = await createKnowledgeBase(eventStore, project, graphDb, logger);
172
+ // kb.eventStore, kb.views, kb.content, kb.graph, kb.graphConsumer
154
173
  ```
155
174
 
156
175
  ### EventBus Ownership
@@ -169,19 +188,25 @@ The EventBus is created by the backend (or script) and passed into `startMakeMea
169
188
 
170
189
  ### Service (Primary)
171
190
 
172
- - `startMakeMeaning(config, eventBus, logger)` — Initialize all infrastructure
173
- - `MakeMeaningService` — Type for service return value
191
+ - `startMakeMeaning(project, config, eventBus, logger)` — Initialize all infrastructure
192
+ - `MakeMeaningService` — Type for service return value (`knowledgeSystem`, `jobQueue`, `workers`, `stop`)
193
+
194
+ ### Knowledge System
195
+
196
+ - `KnowledgeSystem` — Interface grouping the Knowledge Base and its actors
197
+ - `stopKnowledgeSystem(ks)` — Ordered teardown of the Knowledge System
174
198
 
175
199
  ### Knowledge Base
176
200
 
177
- - `createKnowledgeBase(...)` — Factory function
178
- - `KnowledgeBase` — Interface grouping the four KB stores
201
+ - `createKnowledgeBase(eventStore, project, graphDb, logger)` — Async factory function
202
+ - `KnowledgeBase` — Interface grouping the five KB stores (including `graphConsumer`)
179
203
 
180
204
  ### Actors
181
205
 
182
206
  - `Stower` — Write gateway actor
183
207
  - `Gatherer` — Read actor (browse reads, context assembly, entity type listing)
184
208
  - `Matcher` — Search/link actor (context-driven search, entity resolution, referenced-by queries)
209
+ - `Browser` — Filesystem read actor (directory listings merged with KB metadata)
185
210
  - `CloneTokenManager` — Clone token lifecycle actor (yield domain)
186
211
 
187
212
  ### Operations
@@ -201,10 +226,6 @@ The EventBus is created by the backend (or script) and passed into `startMakeMea
201
226
  - `generateResourceSummary` — Resource summarization
202
227
  - `generateReferenceSuggestions` — Smart suggestion generation
203
228
 
204
- ### Graph
205
-
206
- - `GraphDBConsumer` — Event-to-graph synchronization
207
-
208
229
  ## Dependencies
209
230
 
210
231
  - **[@semiont/core](../core/)** — Core types, EventBus, utilities
package/dist/index.d.ts CHANGED
@@ -1,11 +1,11 @@
1
1
  import { JobQueue, ReferenceAnnotationWorker, GenerationWorker, HighlightAnnotationWorker, AssessmentAnnotationWorker, CommentAnnotationWorker, TagAnnotationWorker } from '@semiont/jobs';
2
- import { EventStore, ViewStorage } from '@semiont/event-sourcing';
3
2
  import { SemiontProject } from '@semiont/core/node';
4
- import { GraphServiceConfig, Logger, StoredEvent, ResourceId, EventBus, components, UserId, CreationMethod, AnnotationId, ResourceAnnotations, AnnotationCategory, GraphPath, GraphConnection } from '@semiont/core';
3
+ import { GraphServiceConfig, Logger, StoredEvent, ResourceId, components, EventBus, AnnotationId, UserId, CreationMethod, ResourceAnnotations, AnnotationCategory, GraphPath, GraphConnection } from '@semiont/core';
5
4
  export { AssembledAnnotation, applyBodyOperations, assembleAnnotation } from '@semiont/core';
6
- import { InferenceClient } from '@semiont/inference';
7
- import { GraphDatabase } from '@semiont/graph';
5
+ import { EventStore, ViewStorage } from '@semiont/event-sourcing';
8
6
  import { WorkingTreeStore } from '@semiont/content';
7
+ import { GraphDatabase } from '@semiont/graph';
8
+ import { InferenceClient } from '@semiont/inference';
9
9
  import { Writable, Readable } from 'node:stream';
10
10
 
11
11
  /**
@@ -146,13 +146,14 @@ declare class GraphDBConsumer {
146
146
  /**
147
147
  * Knowledge Base
148
148
  *
149
- * The inert store that records what intelligent actors decide.
150
- * Groups the four KB subsystems from ARCHITECTURE.md:
149
+ * The durable store that records what intelligent actors decide.
150
+ * Groups the five KB subsystems from ARCHITECTURE.md:
151
151
  *
152
152
  * - Event Log (immutable append-only) — via EventStore
153
153
  * - Materialized Views (fast single-doc queries) — via ViewStorage
154
154
  * - Content Store (working-tree files, URI-addressed) — via WorkingTreeStore
155
155
  * - Graph (eventually consistent relationship projection) — via GraphDatabase
156
+ * - Graph Consumer (event-to-graph projection) — via GraphDBConsumer
156
157
  *
157
158
  * The Gatherer and Matcher are the only actors that read from these stores directly.
158
159
  */
@@ -162,14 +163,76 @@ interface KnowledgeBase {
162
163
  views: ViewStorage;
163
164
  content: WorkingTreeStore;
164
165
  graph: GraphDatabase;
166
+ graphConsumer: GraphDBConsumer;
165
167
  projectionsDir: string;
166
168
  }
167
- declare function createKnowledgeBase(eventStore: EventStore, project: SemiontProject, graphDb: GraphDatabase, logger: Logger): KnowledgeBase;
169
+ declare function createKnowledgeBase(eventStore: EventStore, project: SemiontProject, graphDb: GraphDatabase, logger: Logger): Promise<KnowledgeBase>;
170
+
171
+ /**
172
+ * Stower Actor
173
+ *
174
+ * The single write gateway to the Knowledge Base. Subscribes to command
175
+ * events on the EventBus and translates them into domain events on the
176
+ * EventStore + content writes to the RepresentationStore.
177
+ *
178
+ * From ARCHITECTURE.md:
179
+ * The Knowledge Base has exactly three actor interfaces:
180
+ * - Stower (write) — this actor
181
+ * - Gatherer (read context)
182
+ * - Matcher (read search)
183
+ *
184
+ * No other code should call eventStore.appendEvent() or repStore.store().
185
+ *
186
+ * Subscriptions:
187
+ * - yield:create → resource.created (+ content store) → yield:created / yield:create-failed
188
+ * - yield:update → resource.updated (+ content store) → yield:updated / yield:update-failed
189
+ * - yield:mv → resource.moved (+ working tree move) → yield:moved / yield:move-failed
190
+ * - mark:create → annotation.added → mark:created / mark:create-failed
191
+ * - mark:delete → annotation.removed → mark:deleted / mark:delete-failed
192
+ * - mark:update-body → annotation.body.updated → (no result event yet)
193
+ * - mark:archive → resource.archived (+ file removal) (resource-scoped, no result event)
194
+ * - mark:unarchive → resource.unarchived (resource-scoped, no result event)
195
+ * - mark:add-entity-type → entitytype.added → mark:entity-type-added / mark:entity-type-add-failed
196
+ * - mark:update-entity-types → entitytag.added / entitytag.removed
197
+ * - job:start → job.started
198
+ * - job:report-progress → job.progress
199
+ * - job:complete → job.completed
200
+ * - job:fail → job.failed
201
+ */
202
+
203
+ type ResourceDescriptor$3 = components['schemas']['ResourceDescriptor'];
204
+ interface CreateResourceResult {
205
+ resourceId: ResourceId;
206
+ resource: ResourceDescriptor$3;
207
+ }
208
+ declare class Stower {
209
+ private kb;
210
+ private eventBus;
211
+ private subscription;
212
+ private readonly logger;
213
+ constructor(kb: KnowledgeBase, eventBus: EventBus, logger: Logger);
214
+ initialize(): Promise<void>;
215
+ private handleYieldCreate;
216
+ private handleYieldUpdate;
217
+ private handleYieldMv;
218
+ private handleMarkCreate;
219
+ private handleMarkDelete;
220
+ private handleMarkUpdateBody;
221
+ private handleMarkArchive;
222
+ private handleMarkUnarchive;
223
+ private handleAddEntityType;
224
+ private handleUpdateEntityTypes;
225
+ private handleJobStart;
226
+ private handleJobReportProgress;
227
+ private handleJobComplete;
228
+ private handleJobFail;
229
+ stop(): Promise<void>;
230
+ }
168
231
 
169
232
  /**
170
233
  * Gatherer Actor
171
234
  *
172
- * The read actor for the knowledge base. Subscribes to gather and browse events,
235
+ * LLM context assembly for the Knowledge System. Subscribes to gather events,
173
236
  * queries KB stores via context modules, and emits results back to the bus.
174
237
  *
175
238
  * From ARCHITECTURE.md:
@@ -178,70 +241,46 @@ declare function createKnowledgeBase(eventStore: EventStore, project: SemiontPro
178
241
  * the context needed for downstream work."
179
242
  *
180
243
  * Handles:
181
- * - gather:requested / gather:resource-requested LLM context assembly
182
- * - browse:resource-requested — single resource metadata (materialized from events)
183
- * - browse:resources-requested — list resources
184
- * - browse:annotations-requested — all annotations for a resource
185
- * - browse:annotation-requested — single annotation with resolved resource
186
- * - browse:events-requested — resource event history
187
- * - browse:annotation-history-requested — annotation event history
188
- * - mark:entity-types-requested — list entity types
244
+ * - gather:requested annotation-level LLM context assembly
245
+ * - gather:resource-requested — resource-level LLM context assembly
189
246
  *
190
- * RxJS pipeline follows the GraphDBConsumer pattern:
191
- * - groupBy(resourceUri) for per-resource isolation (gather events)
192
- * - mergeMap for independent request-response (browse events)
247
+ * RxJS pipeline uses groupBy(resourceId) + concatMap for per-resource isolation.
193
248
  */
194
249
 
195
250
  declare class Gatherer {
196
251
  private kb;
197
252
  private eventBus;
198
253
  private inferenceClient;
199
- private project?;
200
254
  private subscriptions;
201
255
  private readonly logger;
202
- constructor(kb: KnowledgeBase, eventBus: EventBus, inferenceClient: InferenceClient, logger: Logger, project?: SemiontProject | undefined);
256
+ constructor(kb: KnowledgeBase, eventBus: EventBus, inferenceClient: InferenceClient, logger: Logger);
203
257
  initialize(): Promise<void>;
204
258
  private handleAnnotationGather;
205
259
  private handleResourceGather;
206
- private handleBrowseResource;
207
- private handleBrowseResources;
208
- private handleBrowseAnnotations;
209
- private handleBrowseAnnotation;
210
- private handleBrowseEvents;
211
- private handleBrowseAnnotationHistory;
212
- private handleEntityTypes;
260
+ generateAnnotationSummary(annotationId: AnnotationId, resourceId: ResourceId): Promise<components['schemas']['ContextualSummaryResponse']>;
213
261
  stop(): Promise<void>;
214
262
  }
215
263
 
216
264
  /**
217
265
  * Matcher Actor
218
266
  *
219
- * Bridge between the event bus and the knowledge base for entity resolution.
220
- * Subscribes to bind search events and referenced-by queries, queries KB stores
221
- * (graph, views), and emits results back to the bus.
222
- *
223
- * From ARCHITECTURE.md:
224
- * "When an Analyst or Linker Agent emits a bind event, the Matcher receives it
225
- * from the bus, searches the KB stores for matching resources, and resolves
226
- * references — linking a mention to its referent."
267
+ * Candidate search for the bind flow. Subscribes to match:search-requested,
268
+ * queries the KB graph for matching resources, scores them, and emits results.
227
269
  *
228
270
  * Handles:
229
- * - bind:search-requested — search for binding candidates
230
- * - bind:referenced-by-requested — find annotations that reference a resource
271
+ * - match:search-requested — multi-source retrieval + composite scoring
231
272
  *
232
- * The Matcher handles only the read side (searching for candidates).
233
- * The write side (annotation.body.updated) stays in the route where
234
- * userId is available from auth context. That domain event still flows
235
- * through the bus via EventStore auto-publish.
273
+ * The write side (annotation.body.updated) stays in the route where userId
274
+ * is available from auth context.
236
275
  */
237
276
 
238
277
  declare class Matcher {
239
278
  private kb;
240
279
  private eventBus;
241
- private inferenceClient?;
280
+ private inferenceClient;
242
281
  private subscriptions;
243
282
  private readonly logger;
244
- constructor(kb: KnowledgeBase, eventBus: EventBus, logger: Logger, inferenceClient?: InferenceClient | undefined);
283
+ constructor(kb: KnowledgeBase, eventBus: EventBus, logger: Logger, inferenceClient: InferenceClient);
245
284
  initialize(): Promise<void>;
246
285
  private handleSearch;
247
286
  /**
@@ -269,68 +308,45 @@ declare class Matcher {
269
308
  * @returns Map of resourceId → score (0-1)
270
309
  */
271
310
  private inferenceSemanticScore;
272
- private handleReferencedBy;
273
311
  stop(): Promise<void>;
274
312
  }
275
313
 
276
314
  /**
277
- * Stower Actor
278
- *
279
- * The single write gateway to the Knowledge Base. Subscribes to command
280
- * events on the EventBus and translates them into domain events on the
281
- * EventStore + content writes to the RepresentationStore.
315
+ * Browser Actor
282
316
  *
283
- * From ARCHITECTURE.md:
284
- * The Knowledge Base has exactly three actor interfaces:
285
- * - Stower (write) — this actor
286
- * - Gatherer (read context)
287
- * - Matcher (read search)
317
+ * Filesystem-shaped reads and KB graph reads for the Knowledge System.
318
+ * Merges live filesystem state with KB metadata for tracked resources.
288
319
  *
289
- * No other code should call eventStore.appendEvent() or repStore.store().
290
- *
291
- * Subscriptions:
292
- * - yield:create → resource.created (+ content store) → yield:created / yield:create-failed
293
- * - yield:update → resource.updated (+ content store) → yield:updated / yield:update-failed
294
- * - yield:mv → resource.moved (+ working tree move) → yield:moved / yield:move-failed
295
- * - mark:create → annotation.added → mark:created / mark:create-failed
296
- * - mark:delete → annotation.removed → mark:deleted / mark:delete-failed
297
- * - mark:update-body → annotation.body.updated → (no result event yet)
298
- * - mark:archive → resource.archived (+ file removal) (resource-scoped, no result event)
299
- * - mark:unarchive → resource.unarchived (resource-scoped, no result event)
300
- * - mark:add-entity-type → entitytype.added → mark:entity-type-added / mark:entity-type-add-failed
301
- * - mark:update-entity-types → entitytag.added / entitytag.removed
302
- * - job:start → job.started
303
- * - job:report-progress → job.progress
304
- * - job:complete → job.completed
305
- * - job:fail → job.failed
320
+ * Handles:
321
+ * - browse:resource-requested — single resource metadata (materialized from events)
322
+ * - browse:resources-requested — list resources
323
+ * - browse:annotations-requested all annotations for a resource
324
+ * - browse:annotation-requested single annotation with resolved resource
325
+ * - browse:events-requested resource event history
326
+ * - browse:annotation-history-requested annotation event history
327
+ * - browse:referenced-by-requested find annotations in the KB graph that reference a resource
328
+ * - browse:entity-types-requested list entity types from the project projection
329
+ * - browse:directory-requested list a project directory, merging fs + ViewStorage
306
330
  */
307
331
 
308
- type ResourceDescriptor$3 = components['schemas']['ResourceDescriptor'];
309
- interface CreateResourceResult {
310
- resourceId: ResourceId;
311
- resource: ResourceDescriptor$3;
312
- }
313
- declare class Stower {
332
+ declare class Browser {
333
+ private views;
314
334
  private kb;
315
335
  private eventBus;
316
- private subscription;
336
+ private project;
337
+ private subscriptions;
317
338
  private readonly logger;
318
- constructor(kb: KnowledgeBase, eventBus: EventBus, logger: Logger);
339
+ constructor(views: ViewStorage, kb: KnowledgeBase, eventBus: EventBus, project: SemiontProject, logger: Logger);
319
340
  initialize(): Promise<void>;
320
- private handleYieldCreate;
321
- private handleYieldUpdate;
322
- private handleYieldMv;
323
- private handleMarkCreate;
324
- private handleMarkDelete;
325
- private handleMarkUpdateBody;
326
- private handleMarkArchive;
327
- private handleMarkUnarchive;
328
- private handleAddEntityType;
329
- private handleUpdateEntityTypes;
330
- private handleJobStart;
331
- private handleJobReportProgress;
332
- private handleJobComplete;
333
- private handleJobFail;
341
+ private handleBrowseResource;
342
+ private handleBrowseResources;
343
+ private handleBrowseAnnotations;
344
+ private handleBrowseAnnotation;
345
+ private handleBrowseEvents;
346
+ private handleBrowseAnnotationHistory;
347
+ private handleReferencedBy;
348
+ private handleEntityTypes;
349
+ private handleBrowseDirectory;
334
350
  stop(): Promise<void>;
335
351
  }
336
352
 
@@ -364,39 +380,53 @@ declare class CloneTokenManager {
364
380
  }
365
381
 
366
382
  /**
367
- * Make-Meaning Service
383
+ * Knowledge System
384
+ *
385
+ * Binds the KnowledgeBase to the actors that provide disciplined access to it.
386
+ * Nothing outside the KnowledgeSystem reads or writes the KnowledgeBase directly.
368
387
  *
369
- * Consolidates all meaning-making infrastructure:
370
- * - Job queue initialization
371
- * - Worker instantiation and startup
372
- * - Graph consumer (event-to-graph synchronization)
388
+ * - kb: the durable store (event log, views, content, graph)
389
+ * - stower: write actor — weaves new knowledge in
390
+ * - gatherer: read actor traces threads to build context
391
+ * - matcher: search actor finds related threads
392
+ * - browser: filesystem actor — lists project directories
393
+ * - cloneTokenManager: token actor — manages resource clone tokens
373
394
  *
374
- * Provides a clean interface similar to createEventStore():
375
- * const makeMeaning = await startMakeMeaning(config);
395
+ * EventBus, JobQueue, and workers are peers to KnowledgeSystem, not members.
376
396
  */
377
397
 
378
- interface MakeMeaningService {
398
+ interface KnowledgeSystem {
379
399
  kb: KnowledgeBase;
380
- jobQueue: JobQueue;
381
- eventStore: EventStore;
382
- graphDb: GraphDatabase;
383
- /** Inference client for the Gatherer actor — use for context-assembly operations */
384
- gathererInferenceClient: InferenceClient;
385
- workers: {
386
- detection: ReferenceAnnotationWorker;
387
- generation: GenerationWorker;
388
- highlight: HighlightAnnotationWorker;
389
- assessment: AssessmentAnnotationWorker;
390
- comment: CommentAnnotationWorker;
391
- tag: TagAnnotationWorker;
392
- };
393
- graphConsumer: GraphDBConsumer;
394
400
  stower: Stower;
395
401
  gatherer: Gatherer;
396
402
  matcher: Matcher;
403
+ browser: Browser;
397
404
  cloneTokenManager: CloneTokenManager;
398
405
  stop: () => Promise<void>;
399
406
  }
407
+ declare function stopKnowledgeSystem(ks: KnowledgeSystem): Promise<void>;
408
+
409
+ /**
410
+ * Make-Meaning Service
411
+ *
412
+ * Provides a clean interface:
413
+ * const makeMeaning = await startMakeMeaning(project, config, eventBus, logger);
414
+ */
415
+
416
+ interface MakeMeaningService {
417
+ knowledgeSystem: KnowledgeSystem;
418
+ jobQueue: JobQueue;
419
+ workers: Workers;
420
+ stop: () => Promise<void>;
421
+ }
422
+ type Workers = {
423
+ detection: ReferenceAnnotationWorker;
424
+ generation: GenerationWorker;
425
+ highlight: HighlightAnnotationWorker;
426
+ assessment: AssessmentAnnotationWorker;
427
+ comment: CommentAnnotationWorker;
428
+ tag: TagAnnotationWorker;
429
+ };
400
430
  declare function startMakeMeaning(project: SemiontProject, config: MakeMeaningConfig, eventBus: EventBus, logger: Logger): Promise<MakeMeaningService>;
401
431
 
402
432
  /**
@@ -962,4 +992,4 @@ declare function generateReferenceSuggestions(referenceTitle: string, client: In
962
992
  declare const PACKAGE_NAME = "@semiont/make-meaning";
963
993
  declare const VERSION = "0.1.0";
964
994
 
965
- export { AnnotationContext, AnnotationOperations, BACKUP_FORMAT, type BackupContentReader, type BackupEventStoreReader, type BackupExporterOptions, type BackupImportResult, type BackupImporterOptions, type BackupManifestHeader, type BackupStreamSummary, type BuildContextOptions, CloneTokenManager, type ContentBlobResolver, type CreateAnnotationResult, type CreateResourceInput, type CreateResourceResult, FORMAT_VERSION, Gatherer, GraphContext, GraphDBConsumer, type GraphEdge, type GraphNode, type GraphRepresentation, type KnowledgeBase, 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, resetBootstrap, startMakeMeaning, validateManifestVersion };
995
+ 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, resetBootstrap, startMakeMeaning, stopKnowledgeSystem, validateManifestVersion };