@semiont/make-meaning 0.4.3 → 0.4.5

package/README.md

@@ -10,9 +10,10 @@
 
 This package implements the actor model from [ARCHITECTURE.md](../../docs/ARCHITECTURE.md). It owns the **Knowledge Base** and the actors that interface with it:
 
-- **Stower** (write) — the single write gateway to the Knowledge Base
-- **Gatherer** (read) — handles all browse reads, context assembly (passage + graph neighborhood + optional inference summary), and entity type listing
-- **Matcher** (search/link) — context-driven search with multi-source retrieval, composite structural scoring, optional LLM semantic scoring, and graph queries
+- **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)
+- **Gatherer** (context assembly) — assembles gathered context for annotations (`gather:requested`) and resources (`gather:resource-requested`)
+- **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
 
 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,59 +30,42 @@ npm install @semiont/make-meaning
 
 ```typescript
 import { startMakeMeaning } from '@semiont/make-meaning';
+import { SemiontProject } from '@semiont/core/node';
 import { EventBus } from '@semiont/core';
-import type { EnvironmentConfig, Logger } from '@semiont/core';
+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');
 
 // Start all infrastructure
-const makeMeaning = await startMakeMeaning(config, eventBus, logger);
+const makeMeaning = await startMakeMeaning(project, config, eventBus, logger);
 
 // Access components
-const { kb, jobQueue, stower, gatherer, matcher, cloneTokenManager } = makeMeaning;
+const { knowledgeSystem, jobQueue } = makeMeaning;
+const { kb, stower, browser, gatherer, matcher, cloneTokenManager } = knowledgeSystem;
 
 // Graceful shutdown
 await makeMeaning.stop();
 ```
 
 This single call initializes:
-- **KnowledgeBase** — groups EventStore, ViewStorage, RepresentationStore, GraphDatabase
-- **Stower** — subscribes to write commands on EventBus
-- **Gatherer** — subscribes to browse reads, gather context, and entity type listing on EventBus
-- **Matcher** — subscribes to search and referenced-by queries on EventBus
-- **CloneTokenManager** — subscribes to clone token operations on EventBus
-- **GraphDBConsumer** — event-to-graph synchronization (RxJS burst-buffered pipeline)
+- **KnowledgeSystem** — groups the Knowledge Base and its actors
+  - **KnowledgeBase** — groups EventStore, ViewStorage, WorkingTreeStore, GraphDatabase, and GraphDBConsumer
+  - **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
+  - **Matcher** — subscribes to candidate search requests on EventBus
+  - **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
 
-### Create a Resource (via EventBus)
-
-```typescript
-import { ResourceOperations } from '@semiont/make-meaning';
-import { userId } from '@semiont/core';
-
-const result = await ResourceOperations.createResource(
-  {
-    name: 'My Document',
-    content: Buffer.from('Document content here'),
-    format: 'text/plain',
-    language: 'en',
-  },
-  userId('user-123'),
-  eventBus,
-  config.services.backend.publicURL,
-);
-```
-
-`ResourceOperations.createResource` emits `yield:create` on the EventBus. The Stower subscribes to this event, persists the resource to the EventStore and ContentStore, and emits `yield:created` back on the bus.
-
 ### Gather Context (via EventBus)
 
 ```typescript
 import { firstValueFrom, race, filter, timeout } from 'rxjs';
 
-// Emit gather request
+// Emit gather request for an annotation
 eventBus.get('gather:requested').next({
   annotationUri,
   resourceId,
@@ -101,7 +85,7 @@ const result = await firstValueFrom(
 
 ### Actor Model
 
-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.
+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.
 
 ```mermaid
 graph TB
@@ -109,20 +93,31 @@ graph TB
     Workers["Job Workers"] -->|commands| BUS
     EBC["EventBusClient"] -->|commands| BUS
 
-    BUS -->|"yield:create, mark:create,<br/>mark:delete, job:*"| STOWER["Stower<br/>(write)"]
-    BUS -->|"browse:*, gather:*,<br/>mark:entity-types-*"| GATHERER["Gatherer<br/>(read)"]
-    BUS -->|"bind:search-*,<br/>bind:referenced-by-*"| MATCHER["Matcher<br/>(search/link)"]
-    BUS -->|"yield:clone-*"| CTM["CloneTokenManager<br/>(clone)"]
-
-    STOWER -->|persist| KB["Knowledge Base"]
-    GATHERER -->|query| KB
-    MATCHER -->|query| KB
-    CTM -->|query| KB
-
-    STOWER -->|"yield:created, mark:created"| BUS
-    GATHERER -->|"browse:*-result,<br/>gather:complete"| BUS
-    MATCHER -->|"bind:search-results,<br/>bind:referenced-by-result"| BUS
-    CTM -->|"yield:clone-token-generated,<br/>yield:clone-resource-result"| BUS
+    subgraph ks ["Knowledge System"]
+        STOWER["Stower<br/>(write)"]
+        BROWSER["Browser<br/>(read)"]
+        GATHERER["Gatherer<br/>(context assembly)"]
+        MATCHER["Matcher<br/>(search/link)"]
+        CTM["CloneTokenManager<br/>(clone)"]
+        KB["Knowledge Base"]
+        STOWER -->|persist| KB
+        BROWSER -->|query| KB
+        GATHERER -->|query| KB
+        MATCHER -->|query| KB
+        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 -->|"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: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
+    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
+    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
     classDef actor fill:#5a9a6a,stroke:#3d6644,stroke-width:2px,color:#fff
@@ -130,27 +125,30 @@ graph TB
     classDef caller fill:#4a90a4,stroke:#2c5f7a,stroke-width:2px,color:#fff
 
     class BUS bus
-    class STOWER,GATHERER,MATCHER,CTM actor
+    class STOWER,BROWSER,GATHERER,MATCHER,CTM actor
     class KB kb
     class Routes,Workers,EBC caller
 ```
 
-### Knowledge Base
+### Knowledge System and Knowledge Base
 
-The Knowledge Base is an inert store — it has no intelligence, no goals, no decisions. It groups four subsystems:
+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 subsystems:
 
 | Store | Implementation | Purpose |
 |-------|---------------|---------|
 | **Event Log** | `EventStore` | Immutable append-only log of all domain events |
 | **Materialized Views** | `ViewStorage` | Denormalized projections for fast reads |
-| **Content Store** | `RepresentationStore` | Content-addressed binary storage (SHA-256) |
+| **Content Store** | `WorkingTreeStore` | Working-tree files addressed by URI |
 | **Graph** | `GraphDatabase` | Eventually consistent relationship projection |
+| **Graph Consumer** | `GraphDBConsumer` | Event-to-graph synchronization pipeline |
 
 ```typescript
 import { createKnowledgeBase } from '@semiont/make-meaning';
 
-const kb = createKnowledgeBase(eventStore, basePath, projectRoot, graphDb, logger);
-// kb.eventStore, kb.views, kb.content, kb.graph
+const kb = await createKnowledgeBase(eventStore, project, graphDb, logger);
+// kb.eventStore, kb.views, kb.content, kb.graph, kb.graphConsumer
 ```
 
 ### EventBus Ownership
@@ -169,19 +167,25 @@ The EventBus is created by the backend (or script) and passed into `startMakeMea
 
 ### Service (Primary)
 
-- `startMakeMeaning(config, eventBus, logger)` — Initialize all infrastructure
-- `MakeMeaningService` — Type for service return value
+- `startMakeMeaning(project, config, eventBus, logger)` — Initialize all infrastructure
+- `MakeMeaningService` — Type for service return value (`knowledgeSystem`, `jobQueue`, `workers`, `stop`)
+
+### Knowledge System
+
+- `KnowledgeSystem` — Interface grouping the Knowledge Base and its actors
+- `stopKnowledgeSystem(ks)` — Ordered teardown of the Knowledge System
 
 ### Knowledge Base
 
-- `createKnowledgeBase(...)` — Factory function
-- `KnowledgeBase` — Interface grouping the four KB stores
+- `createKnowledgeBase(eventStore, project, graphDb, logger)` — Async factory function
+- `KnowledgeBase` — Interface grouping the five KB stores (including `graphConsumer`)
 
 ### Actors
 
 - `Stower` — Write gateway actor
-- `Gatherer` — Read actor (browse reads, context assembly, entity type listing)
-- `Matcher` — Search/link actor (context-driven search, entity resolution, referenced-by queries)
+- `Browser` — Read actor (all KB queries, directory listings merged with KB metadata)
+- `Gatherer` — Context assembly actor (annotation and resource gather flows)
+- `Matcher` — Search/link actor (context-driven candidate search with structural + semantic scoring)
 - `CloneTokenManager` — Clone token lifecycle actor (yield domain)
 
 ### Operations
@@ -201,10 +205,6 @@ The EventBus is created by the backend (or script) and passed into `startMakeMea
 - `generateResourceSummary` — Resource summarization
 - `generateReferenceSuggestions` — Smart suggestion generation
 
-### Graph
-
-- `GraphDBConsumer` — Event-to-graph synchronization
-
 ## Dependencies
 
 - **[@semiont/core](../core/)** — Core types, EventBus, utilities

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 import { JobQueue, ReferenceAnnotationWorker, GenerationWorker, HighlightAnnotationWorker, AssessmentAnnotationWorker, CommentAnnotationWorker, TagAnnotationWorker } from '@semiont/jobs';
-import { EventStore, ViewStorage } from '@semiont/event-sourcing';
 import { SemiontProject } from '@semiont/core/node';
-import { GraphServiceConfig, Logger, StoredEvent, ResourceId, EventBus, components, UserId, CreationMethod, AnnotationId, ResourceAnnotations, AnnotationCategory, GraphPath, GraphConnection } from '@semiont/core';
+import { GraphServiceConfig, Logger, StoredEvent, ResourceId, components, EventBus, AnnotationId, UserId, CreationMethod, ResourceAnnotations, AnnotationCategory, GraphPath, GraphConnection } from '@semiont/core';
 export { AssembledAnnotation, applyBodyOperations, assembleAnnotation } from '@semiont/core';
-import { InferenceClient } from '@semiont/inference';
-import { GraphDatabase } from '@semiont/graph';
+import { EventStore, ViewStorage } from '@semiont/event-sourcing';
 import { WorkingTreeStore } from '@semiont/content';
+import { GraphDatabase } from '@semiont/graph';
+import { InferenceClient } from '@semiont/inference';
 import { Writable, Readable } from 'node:stream';
 
 /**
@@ -146,13 +146,14 @@ declare class GraphDBConsumer {
 /**
  * Knowledge Base
  *
- * The inert store that records what intelligent actors decide.
- * Groups the four KB subsystems from ARCHITECTURE.md:
+ * The durable store that records what intelligent actors decide.
+ * Groups the five KB subsystems from ARCHITECTURE.md:
  *
  * - Event Log (immutable append-only) — via EventStore
  * - Materialized Views (fast single-doc queries) — via ViewStorage
  * - Content Store (working-tree files, URI-addressed) — via WorkingTreeStore
  * - Graph (eventually consistent relationship projection) — via GraphDatabase
+ * - Graph Consumer (event-to-graph projection) — via GraphDBConsumer
  *
  * The Gatherer and Matcher are the only actors that read from these stores directly.
  */
@@ -162,14 +163,76 @@ interface KnowledgeBase {
     views: ViewStorage;
     content: WorkingTreeStore;
     graph: GraphDatabase;
+    graphConsumer: GraphDBConsumer;
     projectionsDir: string;
 }
-declare function createKnowledgeBase(eventStore: EventStore, project: SemiontProject, graphDb: GraphDatabase, logger: Logger): KnowledgeBase;
+declare function createKnowledgeBase(eventStore: EventStore, project: SemiontProject, graphDb: GraphDatabase, logger: Logger): Promise<KnowledgeBase>;
+
+/**
+ * Stower Actor
+ *
+ * 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.
+ *
+ * From ARCHITECTURE.md:
+ * The Knowledge Base has exactly three actor interfaces:
+ * - Stower (write) — this actor
+ * - Gatherer (read context)
+ * - Matcher (read search)
+ *
+ * No other code should call eventStore.appendEvent() or repStore.store().
+ *
+ * Subscriptions:
+ * - yield:create       → resource.created (+ content store)   → yield:created / yield:create-failed
+ * - yield:update       → resource.updated (+ content store)   → yield:updated / yield:update-failed
+ * - yield:mv           → resource.moved (+ working tree move) → yield:moved / yield:move-failed
+ * - mark:create        → annotation.added                     → mark:created / mark:create-failed
+ * - mark:delete        → annotation.removed                   → mark:deleted / mark:delete-failed
+ * - 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
+ * - mark:update-entity-types → entitytag.added / entitytag.removed
+ * - job:start          → job.started
+ * - job:report-progress → job.progress
+ * - job:complete       → job.completed
+ * - job:fail           → job.failed
+ */
+
+type ResourceDescriptor$3 = components['schemas']['ResourceDescriptor'];
+interface CreateResourceResult {
+    resourceId: ResourceId;
+    resource: ResourceDescriptor$3;
+}
+declare class Stower {
+    private kb;
+    private eventBus;
+    private subscription;
+    private readonly logger;
+    constructor(kb: KnowledgeBase, eventBus: EventBus, logger: Logger);
+    initialize(): Promise<void>;
+    private handleYieldCreate;
+    private handleYieldUpdate;
+    private handleYieldMv;
+    private handleMarkCreate;
+    private handleMarkDelete;
+    private handleMarkUpdateBody;
+    private handleMarkArchive;
+    private handleMarkUnarchive;
+    private handleAddEntityType;
+    private handleUpdateEntityTypes;
+    private handleJobStart;
+    private handleJobReportProgress;
+    private handleJobComplete;
+    private handleJobFail;
+    stop(): Promise<void>;
+}
 
 /**
  * Gatherer Actor
  *
- * The read actor for the knowledge base. Subscribes to gather and browse events,
+ * LLM context assembly for the Knowledge System. Subscribes to gather events,
  * queries KB stores via context modules, and emits results back to the bus.
  *
  * From ARCHITECTURE.md:
@@ -178,70 +241,46 @@ declare function createKnowledgeBase(eventStore: EventStore, project: SemiontPro
  * the context needed for downstream work."
  *
  * Handles:
- * - gather:requested / gather:resource-requested — LLM context assembly
- * - browse:resource-requested — single resource metadata (materialized from events)
- * - browse:resources-requested — list resources
- * - browse:annotations-requested — all annotations for a resource
- * - browse:annotation-requested — single annotation with resolved resource
- * - browse:events-requested — resource event history
- * - browse:annotation-history-requested — annotation event history
- * - mark:entity-types-requested — list entity types
+ * - gather:requested — annotation-level LLM context assembly
+ * - gather:resource-requested — resource-level LLM context assembly
  *
- * RxJS pipeline follows the GraphDBConsumer pattern:
- * - groupBy(resourceUri) for per-resource isolation (gather events)
- * - mergeMap for independent request-response (browse events)
+ * RxJS pipeline uses groupBy(resourceId) + concatMap for per-resource isolation.
  */
 
 declare class Gatherer {
     private kb;
     private eventBus;
     private inferenceClient;
-    private project?;
     private subscriptions;
     private readonly logger;
-    constructor(kb: KnowledgeBase, eventBus: EventBus, inferenceClient: InferenceClient, logger: Logger, project?: SemiontProject | undefined);
+    constructor(kb: KnowledgeBase, eventBus: EventBus, inferenceClient: InferenceClient, logger: Logger);
     initialize(): Promise<void>;
     private handleAnnotationGather;
     private handleResourceGather;
-    private handleBrowseResource;
-    private handleBrowseResources;
-    private handleBrowseAnnotations;
-    private handleBrowseAnnotation;
-    private handleBrowseEvents;
-    private handleBrowseAnnotationHistory;
-    private handleEntityTypes;
+    generateAnnotationSummary(annotationId: AnnotationId, resourceId: ResourceId): Promise<components['schemas']['ContextualSummaryResponse']>;
     stop(): Promise<void>;
 }
 
 /**
  * Matcher Actor
  *
- * Bridge between the event bus and the knowledge base for entity resolution.
- * Subscribes to bind search events and referenced-by queries, queries KB stores
- * (graph, views), and emits results back to the bus.
- *
- * From ARCHITECTURE.md:
- * "When an Analyst or Linker Agent emits a bind event, the Matcher receives it
- * from the bus, searches the KB stores for matching resources, and resolves
- * references — linking a mention to its referent."
+ * Candidate search for the bind flow. Subscribes to match:search-requested,
+ * queries the KB graph for matching resources, scores them, and emits results.
  *
  * Handles:
- * - bind:search-requested — search for binding candidates
- * - bind:referenced-by-requested — find annotations that reference a resource
+ * - match:search-requested — multi-source retrieval + composite scoring
  *
- * The Matcher handles only the read side (searching for candidates).
- * The write side (annotation.body.updated) stays in the route where
- * userId is available from auth context. That domain event still flows
- * through the bus via EventStore auto-publish.
+ * The write side (annotation.body.updated) stays in the route where userId
+ * is available from auth context.
  */
 
 declare class Matcher {
     private kb;
     private eventBus;
-    private inferenceClient?;
+    private inferenceClient;
     private subscriptions;
     private readonly logger;
-    constructor(kb: KnowledgeBase, eventBus: EventBus, logger: Logger, inferenceClient?: InferenceClient | undefined);
+    constructor(kb: KnowledgeBase, eventBus: EventBus, logger: Logger, inferenceClient: InferenceClient);
     initialize(): Promise<void>;
     private handleSearch;
     /**
@@ -269,68 +308,45 @@ declare class Matcher {
      * @returns Map of resourceId → score (0-1)
      */
     private inferenceSemanticScore;
-    private handleReferencedBy;
     stop(): Promise<void>;
 }
 
 /**
- * Stower Actor
- *
- * 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.
+ * Browser Actor
  *
- * From ARCHITECTURE.md:
- * The Knowledge Base has exactly three actor interfaces:
- * - Stower (write) — this actor
- * - Gatherer (read context)
- * - Matcher (read search)
+ * Filesystem-shaped reads and KB graph reads for the Knowledge System.
+ * Merges live filesystem state with KB metadata for tracked resources.
  *
- * No other code should call eventStore.appendEvent() or repStore.store().
- *
- * Subscriptions:
- * - yield:create       → resource.created (+ content store)   → yield:created / yield:create-failed
- * - yield:update       → resource.updated (+ content store)   → yield:updated / yield:update-failed
- * - yield:mv           → resource.moved (+ working tree move) → yield:moved / yield:move-failed
- * - mark:create        → annotation.added                     → mark:created / mark:create-failed
- * - mark:delete        → annotation.removed                   → mark:deleted / mark:delete-failed
- * - 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
- * - mark:update-entity-types → entitytag.added / entitytag.removed
- * - job:start          → job.started
- * - job:report-progress → job.progress
- * - job:complete       → job.completed
- * - job:fail           → job.failed
+ * Handles:
+ * - browse:resource-requested — single resource metadata (materialized from events)
+ * - browse:resources-requested — list resources
+ * - browse:annotations-requested — all annotations for a resource
+ * - browse:annotation-requested — single annotation with resolved resource
+ * - browse:events-requested — resource event history
+ * - browse:annotation-history-requested — annotation event history
+ * - browse:referenced-by-requested — find annotations in the KB graph that reference a resource
+ * - browse:entity-types-requested — list entity types from the project projection
+ * - browse:directory-requested — list a project directory, merging fs + ViewStorage
  */
 
-type ResourceDescriptor$3 = components['schemas']['ResourceDescriptor'];
-interface CreateResourceResult {
-    resourceId: ResourceId;
-    resource: ResourceDescriptor$3;
-}
-declare class Stower {
+declare class Browser {
+    private views;
     private kb;
     private eventBus;
-    private subscription;
+    private project;
+    private subscriptions;
     private readonly logger;
-    constructor(kb: KnowledgeBase, eventBus: EventBus, logger: Logger);
+    constructor(views: ViewStorage, kb: KnowledgeBase, eventBus: EventBus, project: SemiontProject, logger: Logger);
     initialize(): Promise<void>;
-    private handleYieldCreate;
-    private handleYieldUpdate;
-    private handleYieldMv;
-    private handleMarkCreate;
-    private handleMarkDelete;
-    private handleMarkUpdateBody;
-    private handleMarkArchive;
-    private handleMarkUnarchive;
-    private handleAddEntityType;
-    private handleUpdateEntityTypes;
-    private handleJobStart;
-    private handleJobReportProgress;
-    private handleJobComplete;
-    private handleJobFail;
+    private handleBrowseResource;
+    private handleBrowseResources;
+    private handleBrowseAnnotations;
+    private handleBrowseAnnotation;
+    private handleBrowseEvents;
+    private handleBrowseAnnotationHistory;
+    private handleReferencedBy;
+    private handleEntityTypes;
+    private handleBrowseDirectory;
     stop(): Promise<void>;
 }
 
@@ -364,39 +380,53 @@ declare class CloneTokenManager {
 }
 
 /**
- * Make-Meaning Service
+ * Knowledge System
+ *
+ * Binds the KnowledgeBase to the actors that provide disciplined access to it.
+ * Nothing outside the KnowledgeSystem reads or writes the KnowledgeBase directly.
  *
- * Consolidates all meaning-making infrastructure:
- * - Job queue initialization
- * - Worker instantiation and startup
- * - Graph consumer (event-to-graph synchronization)
+ * - 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
+ * - cloneTokenManager: token actor — manages resource clone tokens
  *
- * Provides a clean interface similar to createEventStore():
- *   const makeMeaning = await startMakeMeaning(config);
+ * EventBus, JobQueue, and workers are peers to KnowledgeSystem, not members.
  */
 
-interface MakeMeaningService {
+interface KnowledgeSystem {
     kb: KnowledgeBase;
-    jobQueue: JobQueue;
-    eventStore: EventStore;
-    graphDb: GraphDatabase;
-    /** Inference client for the Gatherer actor — use for context-assembly operations */
-    gathererInferenceClient: InferenceClient;
-    workers: {
-        detection: ReferenceAnnotationWorker;
-        generation: GenerationWorker;
-        highlight: HighlightAnnotationWorker;
-        assessment: AssessmentAnnotationWorker;
-        comment: CommentAnnotationWorker;
-        tag: TagAnnotationWorker;
-    };
-    graphConsumer: GraphDBConsumer;
     stower: Stower;
     gatherer: Gatherer;
     matcher: Matcher;
+    browser: Browser;
     cloneTokenManager: CloneTokenManager;
     stop: () => Promise<void>;
 }
+declare function stopKnowledgeSystem(ks: KnowledgeSystem): Promise<void>;
+
+/**
+ * Make-Meaning Service
+ *
+ * Provides a clean interface:
+ *   const makeMeaning = await startMakeMeaning(project, config, eventBus, logger);
+ */
+
+interface MakeMeaningService {
+    knowledgeSystem: KnowledgeSystem;
+    jobQueue: JobQueue;
+    workers: Workers;
+    stop: () => Promise<void>;
+}
+type Workers = {
+    detection: ReferenceAnnotationWorker;
+    generation: GenerationWorker;
+    highlight: HighlightAnnotationWorker;
+    assessment: AssessmentAnnotationWorker;
+    comment: CommentAnnotationWorker;
+    tag: TagAnnotationWorker;
+};
 declare function startMakeMeaning(project: SemiontProject, config: MakeMeaningConfig, eventBus: EventBus, logger: Logger): Promise<MakeMeaningService>;
 
 /**
@@ -962,4 +992,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, 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 };
+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 };