@semiont/make-meaning 0.5.9 → 0.5.11

package/README.md

@@ -13,7 +13,7 @@ This package implements the actor model from [ACTOR-MODEL.md](../../docs/system/
 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 and tag-schema 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, the collaborator directory (the KB's declared software agents, derived from the workers/actors inference config), and directory browse (merging filesystem listings with KB metadata)
 - **Gatherer** (context assembly) — assembles gathered context for annotations (`gather:requested`) and resources (`gather:resource-requested`); searches vectors for semantically similar passages (adds `semanticContext` to `GatheredContext`)
 - **Matcher** (search/link) — context-driven candidate search with multi-source retrieval, composite structural scoring, and optional LLM semantic scoring
 - **CloneTokenManager** (yield) — manages clone token lifecycle for resource cloning
@@ -130,7 +130,7 @@ graph TB
     end
 
     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 -->|"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:agents-requested<br/>browse:directory-requested"| BROWSER
     BUS -->|"gather:requested<br/>gather:resource-requested"| GATHERER
     BUS -->|"match:search-requested"| MATCHER
     BUS -->|"domain events:<br/>yield:created, yield:updated<br/>yield:representation-added<br/>mark:added, mark:removed, mark:archived"| SMELTER
@@ -138,7 +138,7 @@ graph TB
     BUS -->|"yield:clone-token-requested<br/>yield:clone-resource-requested<br/>yield:clone-create"| CTM
 
     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
+    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:agents-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

package/dist/index.d.ts

@@ -1,13 +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, AccessToken, Annotation, UserId, ResourceAnnotations, AnnotationCategory, GraphPath, GraphConnection } from '@semiont/core';
+import { GraphServiceConfig, VectorsServiceConfig, EmbeddingServiceConfig, EventBus, Logger, StoredEvent, ResourceId, ResourceDescriptor, AnnotationId, components, ITransport, BaseUrl, ConnectionState, SemiontError, UserDID, EventMap, IContentTransport, PutBinaryRequest, PutBinaryOptions, AccessToken, StateUnit, BusRequestPrimitive, Annotation, UserId, GatheredContext, 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, ChunkingConfig } from '@semiont/vectors';
 import { InferenceClient } from '@semiont/inference';
 import { BehaviorSubject, Observable } from 'rxjs';
-import { StateUnit, WorkerBus, BusRequestPrimitive } from '@semiont/sdk';
+import { WorkerBus } from '@semiont/sdk';
 import { Writable, Readable } from 'node:stream';
 
 /**
@@ -49,6 +49,16 @@ interface MakeMeaningConfig {
         vectors?: VectorsServiceConfig;
         embedding?: EmbeddingServiceConfig;
     };
+    /**
+     * The KB's canonical identity domain — the SAME value `/api/tokens/agent`
+     * mints agent DIDs from (backend `site.domain`). The agent roster consumes
+     * it verbatim, so directory DIDs and work-stamped `generator` DIDs are
+     * equal by construction; it is never derived from service topology
+     * (.plans/bugs/agent-did-host-skew.md).
+     */
+    site?: {
+        domain: string;
+    };
     /** Per-actor inference config */
     actors?: ActorInferenceConfig;
     /** Per-worker-type inference config */
@@ -235,9 +245,10 @@ interface CreateResourceResult {
 declare class Stower {
     private kb;
     private eventBus;
+    private project;
     private subscription;
     private readonly logger;
-    constructor(kb: KnowledgeBase, eventBus: EventBus, logger: Logger);
+    constructor(kb: KnowledgeBase, eventBus: EventBus, project: SemiontProject, logger: Logger);
     initialize(): Promise<void>;
     private handleYieldCreate;
     private handleYieldUpdate;
@@ -374,6 +385,8 @@ declare class Matcher {
  * - 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:tag-schemas-requested — list tag schemas from the project projection
+ * - browse:agents-requested — the collaborator directory: the KB's declared software
+ *   agents, derived from the workers + actors inference config (COLLABORATOR-DIRECTORY)
  * - browse:directory-requested — list a project directory, merging fs + ViewStorage
  */
 
@@ -382,9 +395,10 @@ declare class Browser {
     private kb;
     private eventBus;
     private project;
+    private config;
     private subscriptions;
     private readonly logger;
-    constructor(views: ViewStorage, kb: KnowledgeBase, eventBus: EventBus, project: SemiontProject, logger: Logger);
+    constructor(views: ViewStorage, kb: KnowledgeBase, eventBus: EventBus, project: SemiontProject, config: MakeMeaningConfig, logger: Logger);
     initialize(): Promise<void>;
     private handleBrowseResource;
     private handleBrowseResources;
@@ -395,6 +409,7 @@ declare class Browser {
     private handleReferencedBy;
     private handleEntityTypes;
     private handleTagSchemas;
+    private handleBrowseAgents;
     private handleBrowseDirectory;
     stop(): Promise<void>;
 }
@@ -847,6 +862,16 @@ declare class Smelter {
      * or is empty — callers skip it.
      */
     private fetchEmbeddableText;
+    /**
+     * Read a resource's current entity types from the materialized view — the
+     * authoritative source, updated before the EventBus fires to consumers — so
+     * its vectors carry the discriminator `searchResources` filters on (e.g.
+     * exclude `['Question']`). One read on every embed path, mirroring how the
+     * smelter already reads current content and annotations; a failed read
+     * propagates to the pipeline's per-resource error handler (reconcile heals),
+     * rather than silently stamping `[]` and letting the resource leak into recall.
+     */
+    private resolveEntityTypes;
     private embedResource;
     private handleResourceArchived;
     private handleAnnotationAdded;
@@ -1013,6 +1038,8 @@ interface ReplayStats {
 
 interface BackupImporterOptions {
     eventBus: EventBus;
+    /** Replay appends historical events directly (facts, not commands). */
+    eventStore: EventStore;
     contentStore: WorkingTreeStore;
     logger?: Logger;
 }
@@ -1237,8 +1264,6 @@ declare class ResourceContext {
  * - Generating AI summaries
  */
 
-type AnnotationLLMContextResponse = components['schemas']['AnnotationLLMContextResponse'];
-
 type AnnotationContextResponse = components['schemas']['AnnotationContextResponse'];
 type ContextualSummaryResponse = components['schemas']['ContextualSummaryResponse'];
 interface BuildContextOptions {
@@ -1258,7 +1283,7 @@ declare class AnnotationContext {
      * @returns Rich context for LLM processing
      * @throws Error if annotation or resource not found
      */
-    static buildLLMContext(annotationId: AnnotationId, resourceId: ResourceId, kb: KnowledgeBase, options?: BuildContextOptions, inferenceClient?: InferenceClient, logger?: Logger, embeddingProvider?: EmbeddingProvider): Promise<AnnotationLLMContextResponse>;
+    static buildLLMContext(annotationId: AnnotationId, resourceId: ResourceId, kb: KnowledgeBase, options?: BuildContextOptions, inferenceClient?: InferenceClient, logger?: Logger, embeddingProvider?: EmbeddingProvider): Promise<GatheredContext>;
     /**
      * Get resource annotations from view storage (fast path)
      * Throws if view missing
@@ -1332,24 +1357,7 @@ declare class AnnotationContext {
  * All methods require graph traversal - must use graph database.
  */
 
-interface GraphNode {
-    id: string;
-    type: string;
-    label: string;
-    metadata: {
-        entityTypes: string[];
-    };
-}
-interface GraphEdge {
-    source: string;
-    target: string;
-    type: string;
-    metadata: Record<string, unknown>;
-}
-interface GraphRepresentation {
-    nodes: GraphNode[];
-    edges: GraphEdge[];
-}
+type KnowledgeGraph = components['schemas']['KnowledgeGraph'];
 declare class GraphContext {
     /**
      * Get all resources referencing this resource (backlinks)
@@ -1372,10 +1380,20 @@ declare class GraphContext {
      */
     static searchResources(query: string, kb: KnowledgeBase, limit?: number): Promise<ResourceDescriptor[]>;
     /**
-     * Build graph representation with nodes and edges for a resource and its connections
-     * Retrieves connections from graph and builds visualization-ready structure
+     * Build the unified knowledge graph for a resource's neighborhood:
+     * resources AND annotations as typed nodes, typed/directional edges.
+     *
+     * This is the single graph builder (CONTEXT-UNIFICATION D3) — both the
+     * matcher (ranking) and the resource/viz path consume it. The flattened
+     * signals the matcher reads today (`connections`, `citedBy`/count,
+     * `siblingEntityTypes`, `bidirectional`) are all derivable from this:
+     *  - peer connections → resource nodes + main→peer edges carrying `bidirectional`
+     *  - inbound citations → citing-resource nodes + `citation` edges (citing→main),
+     *    so citedByCount = inbound citation-edge count
+     *  - annotations on the resource → `annotation` nodes + `annotation-of` edges,
+     *    so siblingEntityTypes = union of those nodes' entityTypes
      */
-    static buildGraphRepresentation(resourceId: ResourceId, maxRelated: number, kb: KnowledgeBase): Promise<GraphRepresentation>;
+    static buildKnowledgeGraph(resourceId: ResourceId, kb: KnowledgeBase): Promise<KnowledgeGraph>;
 }
 
 /**
@@ -1385,19 +1403,23 @@ declare class GraphContext {
  * Orchestrates: ResourceContext, GraphContext, AnnotationContext, and generation functions
  */
 
-type ResourceLLMContextResponse = components['schemas']['ResourceLLMContextResponse'];
 interface LLMContextOptions {
     depth: number;
     maxResources: number;
     includeContent: boolean;
     includeSummary: boolean;
+    /**
+     * Entity types to exclude from the resource-gather semantic recall
+     * (caller-supplied; e.g. ['Question']). Optional; default none.
+     */
+    excludeEntityTypes?: string[];
 }
 declare class LLMContext {
     /**
      * Get comprehensive LLM context for a resource
      * Includes: main resource, related resources, annotations, graph, content, summary, references
      */
-    static getResourceContext(resourceId: ResourceId, options: LLMContextOptions, kb: KnowledgeBase, inferenceClient: InferenceClient): Promise<ResourceLLMContextResponse>;
+    static getResourceContext(resourceId: ResourceId, options: LLMContextOptions, kb: KnowledgeBase, inferenceClient: InferenceClient): Promise<GatheredContext>;
 }
 
 /**
@@ -1421,4 +1443,4 @@ declare function generateResourceSummary(resourceName: string, content: string,
 declare function generateReferenceSuggestions(referenceTitle: string, client: InferenceClient, entityType?: string, currentContent?: string): Promise<string[] | null>;
 
 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 };
+export type { BackupContentReader, BackupEventStoreReader, BackupExporterOptions, BackupImportResult, BackupImporterOptions, BackupManifestHeader, BackupStreamSummary, BuildContextOptions, ContentBlobResolver, CreateAnnotationResult, CreateResourceInput, CreateResourceResult, KnowledgeBase, KnowledgeSystem, LLMContextOptions, LinkedDataContentReader, LinkedDataExporterOptions, LinkedDataImportResult, LinkedDataImporterOptions, LinkedDataViewReader, ListResourcesFilters, LocalTransportConfig, MakeMeaningConfig, MakeMeaningService, ReconcileState, ReconcileSummary, ReplayStats, SmelterActorStateUnit, SmelterActorStateUnitOptions, SmelterEvent, SmelterInput, SmelterTiming, SmelterWorkItem, UpdateAnnotationBodyResult };