@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
• Binder (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.

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 { EventBus } from '@semiont/core';
import type { EnvironmentConfig, Logger } from '@semiont/core';

// EventBus is created outside make-meaning — it is not encapsulated by this package
const eventBus = new EventBus();

// Start all infrastructure
const makeMeaning = await startMakeMeaning(config, eventBus, logger);

// Access components
const { kb, jobQueue, stower, gatherer, binder, cloneTokenManager } = makeMeaning;

// 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
• Binder — 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
• 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 three 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

    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 -->|"yield:clone-*"| CTM["CloneTokenManager<br/>(clone)"]

    STOWER -->|persist| KB["Knowledge Base"]
    GATHERER -->|query| KB
    BINDER -->|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
    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,BINDER,CTM actor
    class KB kb
    class Routes,Workers,EBC caller

Knowledge Base

The Knowledge Base is an inert store — it has no intelligence, no goals, no decisions. It groups four 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) | | Graph | GraphDatabase | Eventually consistent relationship projection |

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

const kb = createKnowledgeBase(eventStore, basePath, projectRoot, graphDb, logger);
// kb.eventStore, kb.views, kb.content, kb.graph

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(config, eventBus, logger) — Initialize all infrastructure
• MakeMeaningService — Type for service return value

Knowledge Base

• createKnowledgeBase(...) — Factory function
• KnowledgeBase — Interface grouping the four KB stores

Actors

• 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)
• 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

Graph

• GraphDBConsumer — Event-to-graph synchronization

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