@semiont/make-meaning

Making meaning from resources through actors, context assembly, and relationship reasoning.

This package implements the actor model from 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
• Browser (filesystem reads) — merges live filesystem directory listings with KB metadata for tracked resources
• 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.

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 system can operate entirely without HTTP — see EventBusClient in @semiont/api-client.

Quick Start

npm install @semiont/make-meaning

Start Make-Meaning Service

import { startMakeMeaning } from '@semiont/make-meaning';
import { SemiontProject } from '@semiont/core/node';
import { EventBus } 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(project, config, eventBus, logger);

// Access components
const { knowledgeSystem, jobQueue } = makeMeaning;
const { kb, stower, gatherer, matcher, browser, cloneTokenManager } = knowledgeSystem;

// Graceful shutdown
await makeMeaning.stop();

This single call initializes:

• KnowledgeSystem — groups the Knowledge Base and its actors
  • KnowledgeBase — groups EventStore, ViewStorage, ContentStore, GraphDatabase, and GraphDBConsumer
  • 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
  • Browser — subscribes to directory browse requests, merging filesystem + KB metadata
  • 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)

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)

import { firstValueFrom, race, filter, timeout } from 'rxjs';

// Emit gather request
eventBus.get('gather:requested').next({
  annotationUri,
  resourceId,
  options: { contextLines: 5 },
});

// 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)),
  ).pipe(timeout(30_000)),
);

Architecture

Actor Model

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.

graph TB
    Routes["Backend Routes"] -->|commands| BUS["Event Bus"]
    Workers["Job Workers"] -->|commands| BUS
    EBC["EventBusClient"] -->|commands| BUS

    subgraph ks ["Knowledge System"]
        STOWER["Stower<br/>(write)"]
        GATHERER["Gatherer<br/>(read)"]
        MATCHER["Matcher<br/>(search/link)"]
        BROWSER["Browser<br/>(filesystem)"]
        CTM["CloneTokenManager<br/>(clone)"]
        KB["Knowledge Base"]
        STOWER -->|persist| KB
        GATHERER -->|query| KB
        MATCHER -->|query| KB
        BROWSER -->|query| KB
        CTM -->|query| KB
    end

    BUS -->|"yield:create, mark:create,<br/>mark:delete, job:*"| STOWER
    BUS -->|"browse:*, gather:*,<br/>mark:entity-types-*"| GATHERER
    BUS -->|"bind:search-*,<br/>bind:referenced-by-*"| MATCHER
    BUS -->|"browse:directory-*"| BROWSER
    BUS -->|"yield:clone-*"| CTM

    STOWER -->|"yield:created, mark:created"| BUS
    GATHERER -->|"browse:*-result,<br/>gather:complete"| BUS
    MATCHER -->|"bind:search-results,<br/>bind:referenced-by-result"| BUS
    BROWSER -->|"browse:directory-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
    classDef actor fill:#5a9a6a,stroke:#3d6644,stroke-width:2px,color:#fff
    classDef kb fill:#8b6b9d,stroke:#6b4a7a,stroke-width:2px,color:#fff
    classDef caller fill:#4a90a4,stroke:#2c5f7a,stroke-width:2px,color:#fff

    class BUS bus
    class STOWER,GATHERER,MATCHER,BROWSER,CTM actor
    class KB kb
    class Routes,Workers,EBC caller

Knowledge System and Knowledge Base

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:

import { createKnowledgeBase } from '@semiont/make-meaning';

const kb = await createKnowledgeBase(eventStore, project, graphDb, logger);
// kb.eventStore, kb.views, kb.content, kb.graph, kb.graphConsumer

EventBus Ownership

The EventBus is created by the backend (or script) and passed into startMakeMeaning() as a dependency. Make-meaning does not own or encapsulate the EventBus — it is shared across the entire system.

Documentation

• Architecture — Actor model, data flow, storage architecture
• API Reference — Context modules and operations
• Examples — Common use cases and patterns
• Job Workers — Async annotation workers (in @semiont/jobs)
• Scripting — Direct scripting without HTTP backend

Exports

Service (Primary)

• 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(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 — Filesystem read actor (directory listings merged with KB metadata)
• CloneTokenManager — Clone token lifecycle actor (yield domain)

Operations

• ResourceOperations — Resource CRUD (emits commands to EventBus)
• AnnotationOperations — Annotation CRUD (emits commands to EventBus)

Context Assembly

• ResourceContext — Resource metadata queries from ViewStorage
• AnnotationContext — Annotation queries and LLM context building
• GraphContext — Graph traversal and search
• LLMContext — Resource-level LLM context assembly

Generation

• generateResourceSummary — Resource summarization
• generateReferenceSuggestions — Smart suggestion generation

Dependencies

• @semiont/core — Core types, EventBus, utilities
• @semiont/api-client — OpenAPI-generated types
• @semiont/event-sourcing — Event store and view storage
• @semiont/content — Content-addressed storage
• @semiont/graph — Graph database abstraction
• @semiont/ontology — Schema definitions for tags
• @semiont/inference — AI primitives (generateText)
• @semiont/jobs — Job queue and annotation workers

Testing

npm test                # Run tests
npm run test:watch      # Watch mode
npm run test:coverage   # Coverage report

License

Apache-2.0