@semiont/make-meaning 0.3.0 → 0.3.2

package/README.md

@@ -12,7 +12,7 @@ This package implements the actor model from [ARCHITECTURE.md](../../docs/ARCHIT
 
 - **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
-- **Binder** (search/link) — context-driven search with multi-source retrieval, composite structural scoring, optional LLM semantic scoring, and graph queries
+- **Matcher** (search/link) — context-driven search with multi-source retrieval, composite structural scoring, optional LLM semantic scoring, and graph queries
 - **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.
@@ -39,7 +39,7 @@ const eventBus = new EventBus();
 const makeMeaning = await startMakeMeaning(config, eventBus, logger);
 
 // Access components
-const { kb, jobQueue, stower, gatherer, binder, cloneTokenManager } = makeMeaning;
+const { kb, jobQueue, stower, gatherer, matcher, cloneTokenManager } = makeMeaning;
 
 // Graceful shutdown
 await makeMeaning.stop();
@@ -49,7 +49,7 @@ 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
-- **Binder** — subscribes to search and referenced-by queries 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)
 - **JobQueue** — background job processing queue + job status subscription
@@ -111,17 +111,17 @@ graph TB
 
     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-*"| BINDER["Binder<br/>(search/link)"]
+    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
-    BINDER -->|query| KB
+    MATCHER -->|query| KB
     CTM -->|query| KB
 
     STOWER -->|"yield:created, mark:created"| BUS
     GATHERER -->|"browse:*-result,<br/>gather:complete"| BUS
-    BINDER -->|"bind:search-results,<br/>bind:referenced-by-result"| BUS
+    MATCHER -->|"bind:search-results,<br/>bind:referenced-by-result"| BUS
     CTM -->|"yield:clone-token-generated,<br/>yield:clone-resource-result"| BUS
 
     classDef bus fill:#e8a838,stroke:#b07818,stroke-width:3px,color:#000,font-weight:bold
@@ -130,7 +130,7 @@ graph TB
     classDef caller fill:#4a90a4,stroke:#2c5f7a,stroke-width:2px,color:#fff
 
     class BUS bus
-    class STOWER,GATHERER,BINDER,CTM actor
+    class STOWER,GATHERER,MATCHER,CTM actor
     class KB kb
     class Routes,Workers,EBC caller
 ```
@@ -181,7 +181,7 @@ The EventBus is created by the backend (or script) and passed into `startMakeMea
 
 - `Stower` — Write gateway actor
 - `Gatherer` — Read actor (browse reads, context assembly, entity type listing)
-- `Binder` — Search/link actor (context-driven search, entity resolution, referenced-by queries)
+- `Matcher` — Search/link actor (context-driven search, entity resolution, referenced-by queries)
 - `CloneTokenManager` — Clone token lifecycle actor (yield domain)
 
 ### Operations

package/dist/index.d.ts

@@ -122,7 +122,7 @@ declare class GraphDBConsumer {
  * - Content Store (SHA-256 addressed, deduplicated) — via RepresentationStore
  * - Graph (eventually consistent relationship projection) — via GraphDatabase
  *
- * The Gatherer and Binder are the only actors that read from these stores directly.
+ * The Gatherer and Matcher are the only actors that read from these stores directly.
  */
 
 interface KnowledgeBase {
@@ -181,14 +181,14 @@ declare class Gatherer {
 }
 
 /**
- * Binder Actor
+ * 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 Binder receives it
+ * "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."
  *
@@ -196,13 +196,13 @@ declare class Gatherer {
  * - bind:search-requested — search for binding candidates
  * - bind:referenced-by-requested — find annotations that reference a resource
  *
- * The Binder handles only the read side (searching for candidates).
+ * 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.
  */
 
-declare class Binder {
+declare class Matcher {
     private kb;
     private eventBus;
     private inferenceClient?;
@@ -251,7 +251,7 @@ declare class Binder {
  * The Knowledge Base has exactly three actor interfaces:
  * - Stower (write) — this actor
  * - Gatherer (read context)
- * - Binder (read search)
+ * - Matcher (read search)
  *
  * No other code should call eventStore.appendEvent() or repStore.store().
  *
@@ -355,7 +355,7 @@ interface MakeMeaningService {
     graphConsumer: GraphDBConsumer;
     stower: Stower;
     gatherer: Gatherer;
-    binder: Binder;
+    matcher: Matcher;
     cloneTokenManager: CloneTokenManager;
     stop: () => Promise<void>;
 }
@@ -923,4 +923,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, Binder, 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, 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, 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 };

package/dist/index.js

@@ -10753,21 +10753,23 @@ Summary:`;
       citedByCount: citedByMap.size,
       siblingEntityTypes: siblingEntityTypes.size
     });
-    const generationContext = sourceContext ? {
+    const generationContext = {
       annotation,
       sourceResource: sourceDoc,
-      sourceContext: {
-        before: sourceContext.before || "",
-        selected: sourceContext.selected,
-        after: sourceContext.after || ""
-      },
       metadata: {
         resourceType: "document",
         language: sourceDoc.language,
         entityTypes: annotationEntityTypes
       },
       graphContext
-    } : void 0;
+    };
+    if (sourceContext) {
+      generationContext.sourceContext = {
+        before: sourceContext.before || "",
+        selected: sourceContext.selected,
+        after: sourceContext.after || ""
+      };
+    }
     const response = {
       annotation,
       sourceResource: sourceDoc,
@@ -11541,12 +11543,12 @@ var Gatherer = class {
   }
 };
 
-// src/binder.ts
+// src/matcher.ts
 var import_rxjs4 = __toESM(require_cjs(), 1);
 var import_operators4 = __toESM(require_operators(), 1);
 import { resourceId as resourceId2 } from "@semiont/core";
 import { getExactText, getResourceId as getResourceId4, getResourceEntityTypes as getResourceEntityTypes5, getTargetSource as getTargetSource2, getTargetSelector as getTargetSelector2 } from "@semiont/api-client";
-var Binder = class {
+var Matcher = class {
   constructor(kb, eventBus, logger, inferenceClient) {
     this.kb = kb;
     this.eventBus = eventBus;
@@ -11556,8 +11558,8 @@ var Binder = class {
   subscriptions = [];
   logger;
   async initialize() {
-    this.logger.info("Binder actor initialized");
-    const errorHandler = (err) => this.logger.error("Binder pipeline error", { error: err });
+    this.logger.info("Matcher actor initialized");
+    const errorHandler = (err) => this.logger.error("Matcher pipeline error", { error: err });
     const search$ = this.eventBus.get("bind:search-requested").pipe(
       (0, import_operators4.concatMap)((event) => (0, import_rxjs4.from)(this.handleSearch(event)))
     );
@@ -11572,7 +11574,9 @@ var Binder = class {
   async handleSearch(event) {
     try {
       const context = event.context;
-      const searchTerm = context.sourceContext?.selected ?? "";
+      const selectedText = context.sourceContext?.selected ?? "";
+      const userHint = context.userHint ?? "";
+      const searchTerm = [selectedText, userHint].filter(Boolean).join(" ");
       this.logger.debug("Searching for binding candidates", {
         referenceId: event.referenceId,
         searchTerm,
@@ -11756,7 +11760,7 @@ var Binder = class {
    */
   async inferenceSemanticScore(searchTerm, context, candidates) {
     if (!this.inferenceClient) return /* @__PURE__ */ new Map();
-    const passage = context.sourceContext?.selected ?? searchTerm;
+    const passage = [context.sourceContext?.selected, context.userHint].filter(Boolean).join(" \u2014 ") || searchTerm;
     const entityTypes = context.metadata?.entityTypes ?? [];
     const graphConnections = context.graphContext?.connections;
     const connections = graphConnections ?? [];
@@ -11867,7 +11871,7 @@ No explanations.`;
       sub.unsubscribe();
     }
     this.subscriptions = [];
-    this.logger.info("Binder actor stopped");
+    this.logger.info("Matcher actor stopped");
   }
 };
 
@@ -12470,9 +12474,9 @@ async function startMakeMeaning(config, eventBus, logger) {
   const gathererLogger = logger.child({ component: "gatherer" });
   const gatherer = new Gatherer(kb, eventBus, inferenceClient, gathererLogger, config);
   await gatherer.initialize();
-  const binderLogger = logger.child({ component: "binder" });
-  const binder = new Binder(kb, eventBus, binderLogger, inferenceClient);
-  await binder.initialize();
+  const matcherLogger = logger.child({ component: "matcher" });
+  const matcher = new Matcher(kb, eventBus, matcherLogger, inferenceClient);
+  await matcher.initialize();
   const cloneTokenLogger = logger.child({ component: "clone-token-manager" });
   const cloneTokenManager = new CloneTokenManager(kb, eventBus, cloneTokenLogger);
   await cloneTokenManager.initialize();
@@ -12527,7 +12531,7 @@ async function startMakeMeaning(config, eventBus, logger) {
     graphConsumer,
     stower,
     gatherer,
-    binder,
+    matcher,
     cloneTokenManager,
     stop: async () => {
       logger.info("Stopping Make-Meaning service");
@@ -12540,7 +12544,7 @@ async function startMakeMeaning(config, eventBus, logger) {
         workers.tag.stop()
       ]);
       await gatherer.stop();
-      await binder.stop();
+      await matcher.stop();
       jobStatusSubscription.unsubscribe();
       await cloneTokenManager.stop();
       await stower.stop();
@@ -13479,13 +13483,13 @@ export {
   AnnotationContext,
   AnnotationOperations,
   BACKUP_FORMAT,
-  Binder,
   CloneTokenManager,
   FORMAT_VERSION,
   Gatherer,
   GraphContext,
   GraphDBConsumer,
   LLMContext,
+  Matcher,
   PACKAGE_NAME,
   ResourceContext,
   ResourceOperations,