@semiont/make-meaning 0.2.46 → 0.3.1

package/README.md

@@ -11,8 +11,8 @@
 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, and entity type listing
-- **Binder** (search/link) — searches KB stores for entity resolution and graph queries
+- **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
 - **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 (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

@@ -1,10 +1,23 @@
 import { JobQueue, ReferenceAnnotationWorker, GenerationWorker, HighlightAnnotationWorker, AssessmentAnnotationWorker, CommentAnnotationWorker, TagAnnotationWorker } from '@semiont/jobs';
 import { EventStore, ViewStorage } from '@semiont/event-sourcing';
-import { EnvironmentConfig, Logger, StoredEvent, ResourceId, EventBus, components, CreationMethod, UserId, AnnotationUri, ResourceAnnotations, AnnotationId, AnnotationCategory, GraphPath, GraphConnection } from '@semiont/core';
+import { FilesystemServiceConfig, GraphServiceConfig, InferenceServiceConfig, Logger, StoredEvent, ResourceId, EventBus, components, UserId, CreationMethod, AnnotationId, 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 { RepresentationStore } from '@semiont/content';
+import { Writable, Readable } from 'node:stream';
+
+/** Narrow config type — only the fields make-meaning actually reads */
+interface MakeMeaningConfig {
+    services: {
+        filesystem?: FilesystemServiceConfig;
+        graph?: GraphServiceConfig;
+        inference?: InferenceServiceConfig;
+    };
+    _metadata?: {
+        projectRoot: string;
+    };
+}
 
 /**
  * GraphDB Consumer
@@ -27,7 +40,6 @@ import { RepresentationStore } from '@semiont/content';
  */
 
 declare class GraphDBConsumer {
-    private config;
     private eventStore;
     private graphDb;
     private static readonly GRAPH_RELEVANT_EVENTS;
@@ -39,7 +51,7 @@ declare class GraphDBConsumer {
     private pipelineSubscription;
     private lastProcessed;
     private readonly logger;
-    constructor(config: EnvironmentConfig, eventStore: EventStore, graphDb: GraphDatabase, logger: Logger);
+    constructor(eventStore: EventStore, graphDb: GraphDatabase, logger: Logger);
     initialize(): Promise<void>;
     /**
      * Subscribe globally to ALL events, pre-filter to graph-relevant types,
@@ -110,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 {
@@ -148,14 +160,13 @@ declare function createKnowledgeBase(eventStore: EventStore, basePath: string, p
  */
 
 declare class Gatherer {
-    private publicURL;
     private kb;
     private eventBus;
     private inferenceClient;
     private config?;
     private subscriptions;
     private readonly logger;
-    constructor(publicURL: string, kb: KnowledgeBase, eventBus: EventBus, inferenceClient: InferenceClient, logger: Logger, config?: EnvironmentConfig | undefined);
+    constructor(kb: KnowledgeBase, eventBus: EventBus, inferenceClient: InferenceClient, logger: Logger, config?: MakeMeaningConfig | undefined);
     initialize(): Promise<void>;
     private handleAnnotationGather;
     private handleResourceGather;
@@ -170,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."
  *
@@ -185,21 +196,46 @@ 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 publicURL?;
+    private inferenceClient?;
     private subscriptions;
     private readonly logger;
-    constructor(kb: KnowledgeBase, eventBus: EventBus, logger: Logger, publicURL?: string | undefined);
+    constructor(kb: KnowledgeBase, eventBus: EventBus, logger: Logger, inferenceClient?: InferenceClient | undefined);
     initialize(): Promise<void>;
     private handleSearch;
+    /**
+     * Context-driven search: multi-source retrieval + composite scoring
+     *
+     * Retrieval sources:
+     * 1. Name match — graph.searchResources(searchTerm)
+     * 2. Entity type match — graph.listResources({ entityTypes })
+     * 3. Graph neighborhood — connections from GatheredContext
+     *
+     * Ranking signals:
+     * - Entity type overlap (Jaccard similarity)
+     * - Bidirectionality (already connected both ways)
+     * - Citation weight (well-connected = important)
+     * - Name match quality (exact > prefix > contains)
+     * - Recency (newer resources scored higher)
+     */
+    private contextDrivenSearch;
+    /**
+     * LLM-based semantic relevance scoring (GraphRAG-style)
+     *
+     * Batches candidates into a single prompt asking the LLM to score
+     * each candidate's semantic relevance given the passage and graph context.
+     *
+     * @returns Map of resourceId → score (0-1)
+     */
+    private inferenceSemanticScore;
     private handleReferencedBy;
     stop(): Promise<void>;
 }
@@ -215,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().
  *
@@ -234,18 +270,17 @@ declare class Binder {
  * - job:fail           → job.failed
  */
 
-type ResourceDescriptor$2 = components['schemas']['ResourceDescriptor'];
+type ResourceDescriptor$3 = components['schemas']['ResourceDescriptor'];
 interface CreateResourceResult {
     resourceId: ResourceId;
-    resource: ResourceDescriptor$2;
+    resource: ResourceDescriptor$3;
 }
 declare class Stower {
     private kb;
-    private publicURL;
     private eventBus;
     private subscription;
     private readonly logger;
-    constructor(kb: KnowledgeBase, publicURL: string, eventBus: EventBus, logger: Logger);
+    constructor(kb: KnowledgeBase, eventBus: EventBus, logger: Logger);
     initialize(): Promise<void>;
     private handleYieldCreate;
     private handleMarkCreate;
@@ -320,11 +355,11 @@ interface MakeMeaningService {
     graphConsumer: GraphDBConsumer;
     stower: Stower;
     gatherer: Gatherer;
-    binder: Binder;
+    matcher: Matcher;
     cloneTokenManager: CloneTokenManager;
     stop: () => Promise<void>;
 }
-declare function startMakeMeaning(config: EnvironmentConfig, eventBus: EventBus, logger: Logger): Promise<MakeMeaningService>;
+declare function startMakeMeaning(config: MakeMeaningConfig, eventBus: EventBus, logger: Logger): Promise<MakeMeaningService>;
 
 /**
  * Entity Types Bootstrap Service
@@ -338,7 +373,7 @@ declare function startMakeMeaning(config: EnvironmentConfig, eventBus: EventBus,
  * Bootstrap entity types projection if it doesn't exist.
  * Uses a system user ID (00000000-0000-0000-0000-000000000000) for bootstrap events.
  */
-declare function bootstrapEntityTypes(eventBus: EventBus, config: EnvironmentConfig, logger?: Logger): Promise<void>;
+declare function bootstrapEntityTypes(eventBus: EventBus, config: MakeMeaningConfig, logger?: Logger): Promise<void>;
 /**
  * Reset the bootstrap flag (used for testing)
  */
@@ -354,7 +389,230 @@ declare function resetBootstrap(): void;
 /**
  * Read entity types from view storage projection
  */
-declare function readEntityTypesProjection(config: EnvironmentConfig): Promise<string[]>;
+declare function readEntityTypesProjection(config: MakeMeaningConfig): Promise<string[]>;
+
+/**
+ * Exchange Format Manifest Types
+ *
+ * Defines the metadata structures for backup archives.
+ * The manifest is the first entry in an archive and describes its contents.
+ */
+declare const BACKUP_FORMAT: "semiont-backup";
+declare const FORMAT_VERSION = 1;
+interface BackupManifestHeader {
+    format: typeof BACKUP_FORMAT;
+    version: number;
+    exportedAt: string;
+    sourceUrl: string;
+    stats: {
+        streams: number;
+        events: number;
+        blobs: number;
+        contentBytes: number;
+    };
+}
+interface BackupStreamSummary {
+    stream: string;
+    eventCount: number;
+    firstChecksum: string;
+    lastChecksum: string;
+}
+declare const LINKED_DATA_FORMAT: "semiont-linked-data";
+interface LinkedDataManifest {
+    '@context': Record<string, string>;
+    '@type': string;
+    'semiont:format': typeof LINKED_DATA_FORMAT;
+    'semiont:version': number;
+    'dct:created': string;
+    'prov:wasGeneratedBy': {
+        '@type': string;
+        'prov:used': string;
+    };
+    'semiont:entityTypes': string[];
+    'void:entities': number;
+}
+declare function isBackupManifest(obj: unknown): obj is BackupManifestHeader;
+declare function validateManifestVersion(version: number): void;
+
+/**
+ * Backup Exporter
+ *
+ * Produces a lossless tar.gz archive of the system of record:
+ * - Event log (all streams, JSONL format)
+ * - Content store (content-addressed blobs)
+ *
+ * Reads events via EventStore and content via RepresentationStore.
+ * The archive can restore a complete knowledge base.
+ */
+
+/** Subset of EventStore used by the backup exporter. */
+interface BackupEventStoreReader {
+    log: {
+        storage: {
+            getAllResourceIds(): Promise<ResourceId[]>;
+        };
+        getEvents(resourceId: ResourceId): Promise<StoredEvent[]>;
+    };
+}
+/** Subset of RepresentationStore used by the backup exporter. */
+interface BackupContentReader {
+    retrieve(checksum: string, mediaType: string): Promise<Buffer>;
+}
+interface BackupExporterOptions {
+    eventStore: BackupEventStoreReader;
+    content: BackupContentReader;
+    sourceUrl: string;
+    logger?: Logger;
+}
+/**
+ * Export a full backup of the knowledge base to a tar.gz stream.
+ *
+ * Archive structure:
+ *   .semiont/manifest.jsonl              - Format metadata + per-stream checksums
+ *   .semiont/events/__system__.jsonl     - System events
+ *   .semiont/events/{resourceId}.jsonl   - Per-resource events
+ *   {checksum}.{ext}                     - Content blobs (root level)
+ */
+declare function exportBackup(options: BackupExporterOptions, output: Writable): Promise<BackupManifestHeader>;
+
+/**
+ * Event Replay
+ *
+ * Replays parsed JSONL event streams through the EventBus.
+ * Each domain event is translated to the corresponding command event
+ * (e.g. resource.created → yield:create), emitted, and the result
+ * event is awaited before proceeding (backpressure).
+ *
+ * Content blobs are resolved lazily via a lookup function so that
+ * the caller controls memory strategy (streaming, on-disk, etc.).
+ */
+
+/**
+ * Resolves a content blob by its checksum.
+ * Returned by the caller so replay doesn't dictate memory strategy.
+ */
+type ContentBlobResolver = (checksum: string) => Buffer | undefined;
+interface ReplayStats {
+    eventsReplayed: number;
+    resourcesCreated: number;
+    annotationsCreated: number;
+    entityTypesAdded: number;
+}
+
+/**
+ * Backup Importer
+ *
+ * Restores a knowledge base from a backup tar.gz archive.
+ * Replays events through the EventBus → Stower pipeline so all
+ * derived state (materialized views, graph) rebuilds naturally.
+ *
+ * Accepts a Readable stream so callers can pipe directly from disk
+ * or network without buffering the entire archive first.
+ * Content blobs are resolved lazily via a closure over the parsed
+ * tar entries, avoiding a separate copy of all blob data in memory.
+ */
+
+interface BackupImporterOptions {
+    eventBus: EventBus;
+    logger?: Logger;
+}
+interface BackupImportResult {
+    manifest: BackupManifestHeader;
+    stats: ReplayStats;
+    hashChainValid: boolean;
+}
+/**
+ * Import a backup archive by replaying events through the EventBus.
+ *
+ * Flow:
+ *   1. Stream and decompress tar.gz entries
+ *   2. Parse .semiont/manifest.jsonl → validate format
+ *   3. Build blob resolver over root-level content entries
+ *   4. Replay .semiont/events/__system__.jsonl (entity types)
+ *   5. Replay each .semiont/events/{resourceId}.jsonl (resources, annotations)
+ *
+ * Events flow: importer → EventBus → Stower → EventStore + Views
+ */
+declare function importBackup(archive: Readable, options: BackupImporterOptions): Promise<BackupImportResult>;
+
+/**
+ * Linked Data Exporter
+ *
+ * Produces a JSON-LD tar.gz archive from the current state of the knowledge base.
+ * Reads materialized views (not the event log) for a fast, current-state export.
+ *
+ * Archive structure:
+ *   .semiont/manifest.jsonld                - JSON-LD manifest with format metadata
+ *   .semiont/resources/{resourceId}.jsonld   - One JSON-LD document per resource
+ *   {checksum}.{ext}                        - Content blobs (root level)
+ */
+
+type ResourceDescriptor$2 = components['schemas']['ResourceDescriptor'];
+type Annotation$3 = components['schemas']['Annotation'];
+/** Subset of ViewStorage used by the linked-data exporter. */
+interface LinkedDataViewReader {
+    getAll(): Promise<Array<{
+        resource: ResourceDescriptor$2;
+        annotations: {
+            annotations: Annotation$3[];
+        };
+    }>>;
+}
+/** Subset of RepresentationStore used by the linked-data exporter. */
+interface LinkedDataContentReader {
+    retrieve(checksum: string, mediaType: string): Promise<Buffer>;
+}
+interface LinkedDataExporterOptions {
+    views: LinkedDataViewReader;
+    content: LinkedDataContentReader;
+    sourceUrl: string;
+    entityTypes: string[];
+    includeArchived?: boolean;
+    logger?: Logger;
+}
+/**
+ * Export the knowledge base as a JSON-LD tar.gz archive.
+ */
+declare function exportLinkedData(options: LinkedDataExporterOptions, output: Writable): Promise<LinkedDataManifest>;
+
+/**
+ * Linked Data Importer
+ *
+ * Creates resources from a JSON-LD tar.gz archive exported by the linked-data exporter.
+ * Unlike the backup importer, this is lossy — new resources are created (new IDs),
+ * no event history is preserved. Entity types are restored from the manifest.
+ *
+ * Parses .semiont/manifest.jsonld for format validation and entity types,
+ * then processes each .semiont/resources/{resourceId}.jsonld to create
+ * resources and annotations via the EventBus → Stower pipeline.
+ */
+
+interface LinkedDataImporterOptions {
+    eventBus: EventBus;
+    userId: UserId;
+    logger?: Logger;
+}
+interface LinkedDataImportResult {
+    manifest: LinkedDataManifest;
+    resourcesCreated: number;
+    annotationsCreated: number;
+    entityTypesAdded: number;
+}
+/**
+ * Import a JSON-LD archive by creating resources through the EventBus.
+ *
+ * Flow:
+ *   1. Stream and decompress tar.gz entries
+ *   2. Parse .semiont/manifest.jsonld → validate format
+ *   3. Build blob resolver over root-level content entries
+ *   4. Add entity types from manifest via mark:add-entity-type
+ *   5. For each .semiont/resources/{id}.jsonld:
+ *      a. Parse JSON-LD document
+ *      b. Resolve content blob by checksum from representations
+ *      c. Emit yield:create → await yield:created
+ *      d. For each annotation: emit mark:create → await mark:created
+ */
+declare function importLinkedData(archive: Readable, options: LinkedDataImporterOptions): Promise<LinkedDataImportResult>;
 
 /**
  * Resource Operations
@@ -420,7 +678,7 @@ declare class AnnotationOperations {
     /**
      * Create a new annotation via EventBus → Stower
      */
-    static createAnnotation(request: CreateAnnotationRequest, userId: UserId, creator: Agent, eventBus: EventBus, publicURL: string): Promise<CreateAnnotationResult>;
+    static createAnnotation(request: CreateAnnotationRequest, userId: UserId, creator: Agent, eventBus: EventBus): Promise<CreateAnnotationResult>;
     /**
      * Update annotation body via EventBus → Stower
      */
@@ -428,7 +686,7 @@ declare class AnnotationOperations {
     /**
      * Delete an annotation via EventBus → Stower
      */
-    static deleteAnnotation(id: string, resourceIdUri: string, userId: UserId, eventBus: EventBus, kb: KnowledgeBase, logger?: Logger): Promise<void>;
+    static deleteAnnotation(id: string, resourceIdStr: string, userId: UserId, eventBus: EventBus, kb: KnowledgeBase, logger?: Logger): Promise<void>;
 }
 
 /**
@@ -490,7 +748,7 @@ declare class AnnotationContext {
     /**
      * Build LLM context for an annotation
      *
-     * @param annotationUri - Full annotation URI (e.g., http://localhost:4000/annotations/abc123)
+     * @param annotationId - Bare annotation ID
      * @param resourceId - Source resource ID
      * @param kb - Knowledge base stores
      * @param options - Context building options
@@ -498,7 +756,7 @@ declare class AnnotationContext {
      * @returns Rich context for LLM processing
      * @throws Error if annotation or resource not found
      */
-    static buildLLMContext(annotationUri: AnnotationUri, resourceId: ResourceId, kb: KnowledgeBase, options?: BuildContextOptions, inferenceClient?: InferenceClient, logger?: Logger): Promise<AnnotationLLMContextResponse>;
+    static buildLLMContext(annotationId: AnnotationId, resourceId: ResourceId, kb: KnowledgeBase, options?: BuildContextOptions, inferenceClient?: InferenceClient, logger?: Logger): Promise<AnnotationLLMContextResponse>;
     /**
      * Get resource annotations from view storage (fast path)
      * Throws if view missing
@@ -597,7 +855,7 @@ declare class GraphContext {
      * Get all resources referencing this resource (backlinks)
      * Requires graph traversal - must use graph database
      */
-    static getBacklinks(resourceId: ResourceId, kb: KnowledgeBase, publicURL: string): Promise<Annotation[]>;
+    static getBacklinks(resourceId: ResourceId, kb: KnowledgeBase): Promise<Annotation[]>;
     /**
      * Find shortest path between two resources
      * Requires graph traversal - must use graph database
@@ -617,7 +875,7 @@ declare class GraphContext {
      * Build graph representation with nodes and edges for a resource and its connections
      * Retrieves connections from graph and builds visualization-ready structure
      */
-    static buildGraphRepresentation(resourceId: ResourceId, maxRelated: number, kb: KnowledgeBase, publicURL: string): Promise<GraphRepresentation>;
+    static buildGraphRepresentation(resourceId: ResourceId, maxRelated: number, kb: KnowledgeBase): Promise<GraphRepresentation>;
 }
 
 /**
@@ -639,18 +897,18 @@ 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, publicURL: string, inferenceClient: InferenceClient): Promise<ResourceLLMContextResponse>;
+    static getResourceContext(resourceId: ResourceId, options: LLMContextOptions, kb: KnowledgeBase, inferenceClient: InferenceClient): Promise<ResourceLLMContextResponse>;
 }
 
 /**
  * Resource Generation Functions
  *
- * Application-specific resource generation logic including:
- * - Markdown resource generation from topics
+ * Application-specific resource generation logic:
  * - Resource summary generation
  * - Reference suggestion generation
- * - Language handling and template processing
  *
+ * NOTE: generateResourceFromTopic lives in @semiont/jobs (canonical location)
+ * because make-meaning depends on jobs, not vice versa.
  */
 
 /**
@@ -665,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, Binder, type BuildContextOptions, CloneTokenManager, type CreateAnnotationResult, type CreateResourceInput, type CreateResourceResult, Gatherer, GraphContext, GraphDBConsumer, type GraphEdge, type GraphNode, type GraphRepresentation, type KnowledgeBase, LLMContext, type LLMContextOptions, type ListResourcesFilters, type MakeMeaningService, PACKAGE_NAME, ResourceContext, ResourceOperations, Stower, type UpdateAnnotationBodyResult, type UpdateResourceInput, VERSION, bootstrapEntityTypes, createKnowledgeBase, generateReferenceSuggestions, generateResourceSummary, readEntityTypesProjection, resetBootstrap, startMakeMeaning };
+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 };