@semiont/make-meaning 0.2.43 → 0.2.46

package/dist/index.d.ts

@@ -1,218 +1,10 @@
-import { JobWorker, JobQueue, AnyJob, DetectionResult, RunningJob, DetectionParams, DetectionProgress, GenerationResult, GenerationParams, YieldProgress, HighlightDetectionResult, HighlightDetectionParams, HighlightDetectionProgress, AssessmentDetectionResult, AssessmentDetectionParams, AssessmentDetectionProgress, CommentDetectionResult, CommentDetectionParams, CommentDetectionProgress, TagDetectionResult, TagDetectionParams, TagDetectionProgress } from '@semiont/jobs';
-import { EventStore } from '@semiont/event-sourcing';
-import { RepresentationStore } from '@semiont/content';
-import { EnvironmentConfig, EventBus, Logger, components, StoredEvent, ResourceId, CreationMethod, UserId, AnnotationUri, ResourceAnnotations, AnnotationId, AnnotationCategory, GraphPath, GraphConnection, YieldContext } from '@semiont/core';
+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';
+export { AssembledAnnotation, applyBodyOperations, assembleAnnotation } from '@semiont/core';
 import { InferenceClient } from '@semiont/inference';
 import { GraphDatabase } from '@semiont/graph';
-
-/**
- * Reference Detection Worker
- *
- * Processes detection jobs: runs AI inference to find entities in resources
- * and emits reference.created events for each detected entity.
- *
- * This worker is INDEPENDENT of HTTP clients - it just processes jobs and emits events.
- */
-
-type ResourceDescriptor$2 = components['schemas']['ResourceDescriptor'];
-interface DetectedAnnotation {
-    annotation: {
-        selector: {
-            start: number;
-            end: number;
-            exact: string;
-            prefix?: string;
-            suffix?: string;
-        };
-        entityTypes: string[];
-    };
-}
-declare class ReferenceAnnotationWorker extends JobWorker {
-    private config;
-    private eventStore;
-    private inferenceClient;
-    private eventBus;
-    constructor(jobQueue: JobQueue, config: EnvironmentConfig, eventStore: EventStore, inferenceClient: InferenceClient, eventBus: EventBus, logger: Logger);
-    protected getWorkerName(): string;
-    protected canProcessJob(job: AnyJob): boolean;
-    protected executeJob(job: AnyJob): Promise<DetectionResult>;
-    /**
-     * Detect entity references in resource using AI
-     * Self-contained implementation for reference detection
-     *
-     * Public for testing charset handling - see entity-detection-charset.test.ts
-     */
-    detectReferences(resource: ResourceDescriptor$2, entityTypes: string[], includeDescriptiveReferences?: boolean): Promise<DetectedAnnotation[]>;
-    private processDetectionJob;
-    /**
-     * Emit completion event with result data
-     * Override base class to emit job.completed event (domain + progress)
-     */
-    protected emitCompletionEvent(job: RunningJob<DetectionParams, DetectionProgress>, result: DetectionResult): Promise<void>;
-    protected handleJobFailure(job: AnyJob, error: any): Promise<void>;
-    /**
-     * Update job progress and emit events to Event Store and EventBus
-     * Overrides base class to emit both domain events and progress events
-     */
-    protected updateJobProgress(job: AnyJob): Promise<void>;
-}
-
-/**
- * Generation Worker
- *
- * Processes generation jobs: runs AI inference to generate new resources
- * and emits resource.created and annotation.body.updated events.
- *
- * This worker is INDEPENDENT of HTTP clients - it just processes jobs and emits events.
- */
-
-declare class GenerationWorker extends JobWorker {
-    private config;
-    private eventStore;
-    private inferenceClient;
-    private eventBus;
-    constructor(jobQueue: JobQueue, config: EnvironmentConfig, eventStore: EventStore, inferenceClient: InferenceClient, eventBus: EventBus, logger: Logger);
-    protected getWorkerName(): string;
-    protected canProcessJob(job: AnyJob): boolean;
-    protected executeJob(job: AnyJob): Promise<GenerationResult>;
-    private processGenerationJob;
-    /**
-     * Emit completion event with result data
-     * Override base class to emit job.completed event with resultResourceId
-     */
-    protected emitCompletionEvent(job: RunningJob<GenerationParams, YieldProgress>, result: GenerationResult): Promise<void>;
-    protected handleJobFailure(job: AnyJob, error: any): Promise<void>;
-    /**
-     * Update job progress and emit events to Event Store
-     * Overrides base class to also emit job progress events
-     */
-    protected updateJobProgress(job: AnyJob): Promise<void>;
-}
-
-/**
- * Highlight Detection Worker
- *
- * Processes highlight-detection jobs: runs AI inference to find passages
- * that should be highlighted and creates highlight annotations.
- */
-
-declare class HighlightAnnotationWorker extends JobWorker {
-    private config;
-    private eventStore;
-    private inferenceClient;
-    private eventBus;
-    private isFirstProgress;
-    constructor(jobQueue: JobQueue, config: EnvironmentConfig, eventStore: EventStore, inferenceClient: InferenceClient, eventBus: EventBus, logger: Logger);
-    protected getWorkerName(): string;
-    protected canProcessJob(job: AnyJob): boolean;
-    protected executeJob(job: AnyJob): Promise<HighlightDetectionResult>;
-    /**
-     * Emit completion event with result data
-     * Override base class to emit job.completed event
-     */
-    protected emitCompletionEvent(job: RunningJob<HighlightDetectionParams, HighlightDetectionProgress>, result: HighlightDetectionResult): Promise<void>;
-    /**
-     * Override updateJobProgress to emit events to Event Store
-     */
-    protected updateJobProgress(job: AnyJob): Promise<void>;
-    protected handleJobFailure(job: AnyJob, error: any): Promise<void>;
-    private processHighlightDetectionJob;
-    private createHighlightAnnotation;
-}
-
-/**
- * Assessment Detection Worker
- *
- * Processes assessment-detection jobs: runs AI inference to assess/evaluate
- * passages in the text and creates assessment annotations.
- */
-
-declare class AssessmentAnnotationWorker extends JobWorker {
-    private config;
-    private eventStore;
-    private inferenceClient;
-    private eventBus;
-    private isFirstProgress;
-    constructor(jobQueue: JobQueue, config: EnvironmentConfig, eventStore: EventStore, inferenceClient: InferenceClient, eventBus: EventBus, logger: Logger);
-    protected getWorkerName(): string;
-    protected canProcessJob(job: AnyJob): boolean;
-    protected executeJob(job: AnyJob): Promise<AssessmentDetectionResult>;
-    /**
-     * Emit completion event with result data
-     * Override base class to emit job.completed event
-     */
-    protected emitCompletionEvent(job: RunningJob<AssessmentDetectionParams, AssessmentDetectionProgress>, result: AssessmentDetectionResult): Promise<void>;
-    /**
-     * Override updateJobProgress to emit events to Event Store
-     */
-    protected updateJobProgress(job: AnyJob): Promise<void>;
-    protected handleJobFailure(job: AnyJob, error: any): Promise<void>;
-    private processAssessmentDetectionJob;
-    private createAssessmentAnnotation;
-}
-
-/**
- * Comment Detection Worker
- *
- * Processes comment-detection jobs: runs AI inference to identify passages
- * that would benefit from explanatory comments and creates comment annotations.
- */
-
-declare class CommentAnnotationWorker extends JobWorker {
-    private config;
-    private eventStore;
-    private inferenceClient;
-    private eventBus;
-    private isFirstProgress;
-    constructor(jobQueue: JobQueue, config: EnvironmentConfig, eventStore: EventStore, inferenceClient: InferenceClient, eventBus: EventBus, logger: Logger);
-    protected getWorkerName(): string;
-    protected canProcessJob(job: AnyJob): boolean;
-    protected executeJob(job: AnyJob): Promise<CommentDetectionResult>;
-    /**
-     * Emit completion event with result data
-     * Override base class to emit job.completed event
-     */
-    protected emitCompletionEvent(job: RunningJob<CommentDetectionParams, CommentDetectionProgress>, result: CommentDetectionResult): Promise<void>;
-    /**
-     * Override updateJobProgress to emit events to Event Store
-     */
-    protected updateJobProgress(job: AnyJob): Promise<void>;
-    protected handleJobFailure(job: AnyJob, error: any): Promise<void>;
-    private processCommentDetectionJob;
-    private createCommentAnnotation;
-}
-
-/**
- * Tag Detection Worker
- *
- * Processes tag-detection jobs: runs AI inference to identify passages
- * serving specific structural roles (IRAC, IMRAD, Toulmin, etc.) and
- * creates tag annotations with dual-body structure.
- */
-
-declare class TagAnnotationWorker extends JobWorker {
-    private config;
-    private eventStore;
-    private inferenceClient;
-    private eventBus;
-    private isFirstProgress;
-    constructor(jobQueue: JobQueue, config: EnvironmentConfig, eventStore: EventStore, inferenceClient: InferenceClient, eventBus: EventBus, logger: Logger);
-    protected getWorkerName(): string;
-    protected canProcessJob(job: AnyJob): boolean;
-    protected executeJob(job: AnyJob): Promise<TagDetectionResult>;
-    /**
-     * Emit completion event with result data
-     * Override base class to emit job.completed event
-     */
-    protected emitCompletionEvent(job: RunningJob<TagDetectionParams, TagDetectionProgress>, result: TagDetectionResult): Promise<void>;
-    /**
-     * Override updateJobProgress to emit events to Event Store
-     */
-    protected updateJobProgress(job: AnyJob): Promise<void>;
-    protected handleJobFailure(job: AnyJob, error: any): Promise<void>;
-    private processTagDetectionJob;
-    private createTagAnnotation;
-}
+import { RepresentationStore } from '@semiont/content';
 
 /**
  * GraphDB Consumer
@@ -307,6 +99,198 @@ declare class GraphDBConsumer {
     shutdown(): Promise<void>;
 }
 
+/**
+ * Knowledge Base
+ *
+ * The inert store that records what intelligent actors decide.
+ * Groups the four KB subsystems from ARCHITECTURE.md:
+ *
+ * - Event Log (immutable append-only) — via EventStore
+ * - Materialized Views (fast single-doc queries) — via ViewStorage
+ * - 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.
+ */
+
+interface KnowledgeBase {
+    eventStore: EventStore;
+    views: ViewStorage;
+    content: RepresentationStore;
+    graph: GraphDatabase;
+}
+declare function createKnowledgeBase(eventStore: EventStore, basePath: string, projectRoot: string | undefined, graphDb: GraphDatabase, logger: Logger): KnowledgeBase;
+
+/**
+ * Gatherer Actor
+ *
+ * The read actor for the knowledge base. Subscribes to gather and browse events,
+ * queries KB stores via context modules, and emits results back to the bus.
+ *
+ * From ARCHITECTURE.md:
+ * "When a Generator Agent or Linker Agent emits a gather event, the Gatherer
+ * receives it from the bus, queries the relevant KB stores, and assembles
+ * the context needed for downstream work."
+ *
+ * Handles:
+ * - gather:requested / gather:resource-requested — LLM context assembly
+ * - browse:resource-requested — single resource metadata (materialized from events)
+ * - browse:resources-requested — list resources
+ * - browse:annotations-requested — all annotations for a resource
+ * - browse:annotation-requested — single annotation with resolved resource
+ * - browse:events-requested — resource event history
+ * - browse:annotation-history-requested — annotation event history
+ * - mark:entity-types-requested — list entity types
+ *
+ * RxJS pipeline follows the GraphDBConsumer pattern:
+ * - groupBy(resourceUri) for per-resource isolation (gather events)
+ * - mergeMap for independent request-response (browse events)
+ */
+
+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);
+    initialize(): Promise<void>;
+    private handleAnnotationGather;
+    private handleResourceGather;
+    private handleBrowseResource;
+    private handleBrowseResources;
+    private handleBrowseAnnotations;
+    private handleBrowseAnnotation;
+    private handleBrowseEvents;
+    private handleBrowseAnnotationHistory;
+    private handleEntityTypes;
+    stop(): Promise<void>;
+}
+
+/**
+ * Binder 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
+ * from the bus, searches the KB stores for matching resources, and resolves
+ * references — linking a mention to its referent."
+ *
+ * Handles:
+ * - 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 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 {
+    private kb;
+    private eventBus;
+    private publicURL?;
+    private subscriptions;
+    private readonly logger;
+    constructor(kb: KnowledgeBase, eventBus: EventBus, logger: Logger, publicURL?: string | undefined);
+    initialize(): Promise<void>;
+    private handleSearch;
+    private handleReferencedBy;
+    stop(): Promise<void>;
+}
+
+/**
+ * Stower Actor
+ *
+ * The single write gateway to the Knowledge Base. Subscribes to command
+ * events on the EventBus and translates them into domain events on the
+ * EventStore + content writes to the RepresentationStore.
+ *
+ * From ARCHITECTURE.md:
+ * The Knowledge Base has exactly three actor interfaces:
+ * - Stower (write) — this actor
+ * - Gatherer (read context)
+ * - Binder (read search)
+ *
+ * No other code should call eventStore.appendEvent() or repStore.store().
+ *
+ * Subscriptions:
+ * - yield:create       → resource.created (+ content store)   → yield:created / yield:create-failed
+ * - mark:create        → annotation.added                     → mark:created / mark:create-failed
+ * - mark:delete        → annotation.removed                   → mark:deleted / mark:delete-failed
+ * - mark:update-body   → annotation.body.updated              → (no result event yet)
+ * - mark:archive       → resource.archived                    (resource-scoped, no result event)
+ * - mark:unarchive     → resource.unarchived                  (resource-scoped, no result event)
+ * - mark:add-entity-type → entitytype.added                   → mark:entity-type-added / mark:entity-type-add-failed
+ * - mark:update-entity-types → entitytag.added / entitytag.removed
+ * - job:start          → job.started
+ * - job:report-progress → job.progress
+ * - job:complete       → job.completed
+ * - job:fail           → job.failed
+ */
+
+type ResourceDescriptor$2 = components['schemas']['ResourceDescriptor'];
+interface CreateResourceResult {
+    resourceId: ResourceId;
+    resource: ResourceDescriptor$2;
+}
+declare class Stower {
+    private kb;
+    private publicURL;
+    private eventBus;
+    private subscription;
+    private readonly logger;
+    constructor(kb: KnowledgeBase, publicURL: string, eventBus: EventBus, logger: Logger);
+    initialize(): Promise<void>;
+    private handleYieldCreate;
+    private handleMarkCreate;
+    private handleMarkDelete;
+    private handleMarkUpdateBody;
+    private handleMarkArchive;
+    private handleMarkUnarchive;
+    private handleAddEntityType;
+    private handleUpdateEntityTypes;
+    private handleJobStart;
+    private handleJobReportProgress;
+    private handleJobComplete;
+    private handleJobFail;
+    stop(): Promise<void>;
+}
+
+/**
+ * Clone Token Manager
+ *
+ * Reactive actor that handles clone token operations via the EventBus.
+ * Manages an in-memory token store for resource cloning workflows.
+ *
+ * Handles:
+ * - yield:clone-token-requested — generate a clone token for a resource
+ * - yield:clone-resource-requested — look up a resource by clone token
+ * - yield:clone-create — create a new resource from a clone token
+ *
+ * From COMPLETE-EVENT-PROTOCOL.md:
+ * "Clone tokens produce new resources — that's yield."
+ */
+
+declare class CloneTokenManager {
+    private kb;
+    private eventBus;
+    private subscriptions;
+    private readonly logger;
+    private readonly tokens;
+    constructor(kb: KnowledgeBase, eventBus: EventBus, logger: Logger);
+    initialize(): Promise<void>;
+    private handleGenerateToken;
+    private handleGetResource;
+    private handleCreateResource;
+    stop(): Promise<void>;
+}
+
 /**
  * Make-Meaning Service
  *
@@ -320,10 +304,9 @@ declare class GraphDBConsumer {
  */
 
 interface MakeMeaningService {
+    kb: KnowledgeBase;
     jobQueue: JobQueue;
     eventStore: EventStore;
-    eventBus: EventBus;
-    repStore: RepresentationStore;
     inferenceClient: InferenceClient;
     graphDb: GraphDatabase;
     workers: {
@@ -335,6 +318,10 @@ interface MakeMeaningService {
         tag: TagAnnotationWorker;
     };
     graphConsumer: GraphDBConsumer;
+    stower: Stower;
+    gatherer: Gatherer;
+    binder: Binder;
+    cloneTokenManager: CloneTokenManager;
     stop: () => Promise<void>;
 }
 declare function startMakeMeaning(config: EnvironmentConfig, eventBus: EventBus, logger: Logger): Promise<MakeMeaningService>;
@@ -343,7 +330,7 @@ declare function startMakeMeaning(config: EnvironmentConfig, eventBus: EventBus,
  * Entity Types Bootstrap Service
  *
  * On startup, checks if the entity types projection exists.
- * If not, emits entitytype.added events for each DEFAULT_ENTITY_TYPES entry.
+ * If not, emits mark:add-entity-type for each DEFAULT_ENTITY_TYPES entry.
  * This ensures the system has entity types available immediately after first deployment.
  */
 
@@ -351,7 +338,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(eventStore: EventStore, config: EnvironmentConfig, logger?: Logger): Promise<void>;
+declare function bootstrapEntityTypes(eventBus: EventBus, config: EnvironmentConfig, logger?: Logger): Promise<void>;
 /**
  * Reset the bootstrap flag (used for testing)
  */
@@ -372,14 +359,14 @@ declare function readEntityTypesProjection(config: EnvironmentConfig): Promise<s
 /**
  * Resource Operations
  *
- * Business logic for resource operations including:
- * - Resource creation (ID generation, content storage, event emission)
- * - Archive/unarchive operations
- * - Entity type tagging (add/remove)
- * - Computing diffs and emitting appropriate events
+ * Business logic for resource operations. All writes go through the EventBus
+ * — the Stower actor subscribes and handles persistence.
+ *
+ * For create: emits yield:create, awaits yield:created / yield:create-failed.
+ * For archive/unarchive: emits mark:archive / mark:unarchive on scoped bus.
+ * For entity type updates: emits mark:update-entity-types.
  */
 
-type CreateResourceResponse = components['schemas']['CreateResourceResponse'];
 type ContentFormat = components['schemas']['ContentFormat'];
 interface UpdateResourceInput {
     resourceId: ResourceId;
@@ -399,40 +386,27 @@ interface CreateResourceInput {
 }
 declare class ResourceOperations {
     /**
-     * Create a new resource
-     * Orchestrates: content storage → event emission → response building
-     */
-    static createResource(input: CreateResourceInput, userId: UserId, eventStore: EventStore, repStore: RepresentationStore, config: EnvironmentConfig): Promise<CreateResourceResponse>;
-    /**
-     * Update resource metadata by computing diffs and emitting events
-     * Handles: archived status changes, entity type additions/removals
-     */
-    static updateResource(input: UpdateResourceInput, eventStore: EventStore): Promise<void>;
-    /**
-     * Update archived status by emitting resource.archived or resource.unarchived event
-     */
-    private static updateArchivedStatus;
-    /**
-     * Update entity types by computing diff and emitting events for added/removed types
+     * Create a new resource via EventBus → Stower
      */
-    private static updateEntityTypes;
+    static createResource(input: CreateResourceInput, userId: UserId, eventBus: EventBus): Promise<ResourceId>;
     /**
-     * Compute diff between current and updated entity types
-     * Returns arrays of added and removed entity types
+     * Update resource metadata via EventBus → Stower
      */
-    private static computeEntityTypeDiff;
+    static updateResource(input: UpdateResourceInput, eventBus: EventBus): Promise<void>;
 }
 
 /**
  * Annotation Operations
  *
- * Business logic for annotation CRUD operations:
- * - Create annotations (ID generation, validation, event emission)
- * - Update annotation body (operations: add/remove/replace)
- * - Delete annotations (validation, event emission)
+ * Business logic for annotation CRUD operations. All writes go through the
+ * EventBus — the Stower actor subscribes and handles persistence.
  *
+ * - Create: emits mark:create with full annotation + userId + resourceId
+ * - Update body: emits mark:update-body
+ * - Delete: emits mark:delete with annotationId + userId + resourceId
  */
 
+type Agent = components['schemas']['Agent'];
 type Annotation$2 = components['schemas']['Annotation'];
 type CreateAnnotationRequest = components['schemas']['CreateAnnotationRequest'];
 type UpdateAnnotationBodyRequest = components['schemas']['UpdateAnnotationBodyRequest'];
@@ -444,21 +418,17 @@ interface UpdateAnnotationBodyResult {
 }
 declare class AnnotationOperations {
     /**
-     * Create a new annotation
-     */
-    static createAnnotation(request: CreateAnnotationRequest, userId: UserId, eventStore: EventStore, config: EnvironmentConfig): Promise<CreateAnnotationResult>;
-    /**
-     * Update annotation body with operations (add/remove/replace)
+     * Create a new annotation via EventBus → Stower
      */
-    static updateAnnotationBody(id: string, request: UpdateAnnotationBodyRequest, userId: UserId, eventStore: EventStore, config: EnvironmentConfig): Promise<UpdateAnnotationBodyResult>;
+    static createAnnotation(request: CreateAnnotationRequest, userId: UserId, creator: Agent, eventBus: EventBus, publicURL: string): Promise<CreateAnnotationResult>;
     /**
-     * Delete an annotation
+     * Update annotation body via EventBus → Stower
      */
-    static deleteAnnotation(id: string, resourceIdUri: string, userId: UserId, eventStore: EventStore, config: EnvironmentConfig, logger?: Logger): Promise<void>;
+    static updateAnnotationBody(id: string, request: UpdateAnnotationBodyRequest, userId: UserId, eventBus: EventBus, kb: KnowledgeBase): Promise<UpdateAnnotationBodyResult>;
     /**
-     * Apply body operations (add/remove/replace) to annotation body
+     * Delete an annotation via EventBus → Stower
      */
-    private static applyBodyOperations;
+    static deleteAnnotation(id: string, resourceIdUri: string, userId: UserId, eventBus: EventBus, kb: KnowledgeBase, logger?: Logger): Promise<void>;
 }
 
 /**
@@ -477,23 +447,23 @@ declare class ResourceContext {
     /**
      * Get resource metadata from view storage
      */
-    static getResourceMetadata(resourceId: ResourceId, config: EnvironmentConfig): Promise<ResourceDescriptor$1 | null>;
+    static getResourceMetadata(resourceId: ResourceId, kb: KnowledgeBase): Promise<ResourceDescriptor$1 | null>;
     /**
      * List all resources by scanning view storage
      */
-    static listResources(filters: ListResourcesFilters | undefined, config: EnvironmentConfig): Promise<ResourceDescriptor$1[]>;
+    static listResources(filters: ListResourcesFilters | undefined, kb: KnowledgeBase): Promise<ResourceDescriptor$1[]>;
     /**
      * Add content previews to resources (for search results)
      * Retrieves and decodes the first 200 characters of each resource's primary representation
      */
-    static addContentPreviews(resources: ResourceDescriptor$1[], config: EnvironmentConfig): Promise<Array<ResourceDescriptor$1 & {
+    static addContentPreviews(resources: ResourceDescriptor$1[], kb: KnowledgeBase): Promise<Array<ResourceDescriptor$1 & {
         content: string;
     }>>;
     /**
      * Get full content for a resource
      * Retrieves and decodes the primary representation
      */
-    static getResourceContent(resource: ResourceDescriptor$1, config: EnvironmentConfig): Promise<string | undefined>;
+    static getResourceContent(resource: ResourceDescriptor$1, kb: KnowledgeBase): Promise<string | undefined>;
 }
 
 /**
@@ -505,9 +475,6 @@ declare class ResourceContext {
  * - Building LLM context for annotations
  * - Extracting annotation text context
  * - Generating AI summaries
- *
- * NOTE: This class contains static utility methods without logger access.
- * Console statements kept for debugging - consider adding logger parameter in future.
  */
 
 type AnnotationLLMContextResponse = components['schemas']['AnnotationLLMContextResponse'];
@@ -525,22 +492,23 @@ declare class AnnotationContext {
      *
      * @param annotationUri - Full annotation URI (e.g., http://localhost:4000/annotations/abc123)
      * @param resourceId - Source resource ID
-     * @param config - Application configuration
+     * @param kb - Knowledge base stores
      * @param options - Context building options
+     * @param inferenceClient - Optional inference client for target context summary
      * @returns Rich context for LLM processing
      * @throws Error if annotation or resource not found
      */
-    static buildLLMContext(annotationUri: AnnotationUri, resourceId: ResourceId, config: EnvironmentConfig, options?: BuildContextOptions, logger?: Logger): Promise<AnnotationLLMContextResponse>;
+    static buildLLMContext(annotationUri: AnnotationUri, resourceId: ResourceId, kb: KnowledgeBase, options?: BuildContextOptions, inferenceClient?: InferenceClient, logger?: Logger): Promise<AnnotationLLMContextResponse>;
     /**
      * Get resource annotations from view storage (fast path)
      * Throws if view missing
      */
-    static getResourceAnnotations(resourceId: ResourceId, config: EnvironmentConfig): Promise<ResourceAnnotations>;
+    static getResourceAnnotations(resourceId: ResourceId, kb: KnowledgeBase): Promise<ResourceAnnotations>;
     /**
      * Get all annotations
      * @returns Array of all annotation objects
      */
-    static getAllAnnotations(resourceId: ResourceId, config: EnvironmentConfig): Promise<Annotation$1[]>;
+    static getAllAnnotations(resourceId: ResourceId, kb: KnowledgeBase): Promise<Annotation$1[]>;
     /**
      * Enrich reference annotations with resolved document names
      * Adds _resolvedDocumentName property to annotations that link to documents
@@ -551,7 +519,7 @@ declare class AnnotationContext {
      * Get resource stats (version info)
      * @returns Version and timestamp info for the annotations
      */
-    static getResourceStats(resourceId: ResourceId, config: EnvironmentConfig): Promise<{
+    static getResourceStats(resourceId: ResourceId, kb: KnowledgeBase): Promise<{
         resourceId: ResourceId;
         version: number;
         updatedAt: string;
@@ -559,12 +527,12 @@ declare class AnnotationContext {
     /**
      * Check if resource exists in view storage
      */
-    static resourceExists(resourceId: ResourceId, config: EnvironmentConfig): Promise<boolean>;
+    static resourceExists(resourceId: ResourceId, kb: KnowledgeBase): Promise<boolean>;
     /**
      * Get a single annotation by ID
      * O(1) lookup using resource ID to access view storage
      */
-    static getAnnotation(annotationId: AnnotationId, resourceId: ResourceId, config: EnvironmentConfig): Promise<Annotation$1 | null>;
+    static getAnnotation(annotationId: AnnotationId, resourceId: ResourceId, kb: KnowledgeBase): Promise<Annotation$1 | null>;
     /**
      * List annotations with optional filtering
      * @param filters - Optional filters like resourceId and type
@@ -573,15 +541,15 @@ declare class AnnotationContext {
     static listAnnotations(filters: {
         resourceId?: ResourceId;
         type?: AnnotationCategory;
-    } | undefined, config: EnvironmentConfig): Promise<Annotation$1[]>;
+    } | undefined, kb: KnowledgeBase): Promise<Annotation$1[]>;
     /**
      * Get annotation context (selected text with surrounding context)
      */
-    static getAnnotationContext(annotationId: AnnotationId, resourceId: ResourceId, contextBefore: number, contextAfter: number, config: EnvironmentConfig): Promise<AnnotationContextResponse>;
+    static getAnnotationContext(annotationId: AnnotationId, resourceId: ResourceId, contextBefore: number, contextAfter: number, kb: KnowledgeBase): Promise<AnnotationContextResponse>;
     /**
      * Generate AI summary of annotation in context
      */
-    static generateAnnotationSummary(annotationId: AnnotationId, resourceId: ResourceId, config: EnvironmentConfig, logger?: Logger): Promise<ContextualSummaryResponse>;
+    static generateAnnotationSummary(annotationId: AnnotationId, resourceId: ResourceId, kb: KnowledgeBase, inferenceClient: InferenceClient): Promise<ContextualSummaryResponse>;
     /**
      * Get resource content as string
      */
@@ -629,27 +597,27 @@ declare class GraphContext {
      * Get all resources referencing this resource (backlinks)
      * Requires graph traversal - must use graph database
      */
-    static getBacklinks(resourceId: ResourceId, config: EnvironmentConfig): Promise<Annotation[]>;
+    static getBacklinks(resourceId: ResourceId, kb: KnowledgeBase, publicURL: string): Promise<Annotation[]>;
     /**
      * Find shortest path between two resources
      * Requires graph traversal - must use graph database
      */
-    static findPath(fromResourceId: ResourceId, toResourceId: ResourceId, config: EnvironmentConfig, maxDepth?: number): Promise<GraphPath[]>;
+    static findPath(fromResourceId: ResourceId, toResourceId: ResourceId, kb: KnowledgeBase, maxDepth?: number): Promise<GraphPath[]>;
     /**
      * Get resource connections (graph edges)
      * Requires graph traversal - must use graph database
      */
-    static getResourceConnections(resourceId: ResourceId, config: EnvironmentConfig): Promise<GraphConnection[]>;
+    static getResourceConnections(resourceId: ResourceId, kb: KnowledgeBase): Promise<GraphConnection[]>;
     /**
      * Search resources by name (cross-resource query)
      * Requires full-text search - must use graph database
      */
-    static searchResources(query: string, config: EnvironmentConfig, limit?: number): Promise<ResourceDescriptor[]>;
+    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
      */
-    static buildGraphRepresentation(resourceId: ResourceId, maxRelated: number, config: EnvironmentConfig): Promise<GraphRepresentation>;
+    static buildGraphRepresentation(resourceId: ResourceId, maxRelated: number, kb: KnowledgeBase, publicURL: string): Promise<GraphRepresentation>;
 }
 
 /**
@@ -671,256 +639,9 @@ 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, config: EnvironmentConfig, inferenceClient: InferenceClient): Promise<ResourceLLMContextResponse>;
+    static getResourceContext(resourceId: ResourceId, options: LLMContextOptions, kb: KnowledgeBase, publicURL: string, inferenceClient: InferenceClient): Promise<ResourceLLMContextResponse>;
 }
 
-/**
- * Response parsers for annotation detection motivations
- *
- * Provides static methods to parse and validate AI responses for each motivation type.
- * Includes offset validation and correction logic.
- * Extracted from worker implementations to centralize parsing logic.
- *
- * NOTE: These are static utility methods without logger access.
- * Console statements kept for debugging - consider adding logger parameter in future.
- */
-/**
- * Represents a detected comment with validated position
- */
-interface CommentMatch {
-    exact: string;
-    start: number;
-    end: number;
-    prefix?: string;
-    suffix?: string;
-    comment: string;
-}
-/**
- * Represents a detected highlight with validated position
- */
-interface HighlightMatch {
-    exact: string;
-    start: number;
-    end: number;
-    prefix?: string;
-    suffix?: string;
-}
-/**
- * Represents a detected assessment with validated position
- */
-interface AssessmentMatch {
-    exact: string;
-    start: number;
-    end: number;
-    prefix?: string;
-    suffix?: string;
-    assessment: string;
-}
-/**
- * Represents a detected tag with validated position
- */
-interface TagMatch {
-    exact: string;
-    start: number;
-    end: number;
-    prefix?: string;
-    suffix?: string;
-    category: string;
-}
-declare class MotivationParsers {
-    /**
-     * Parse and validate AI response for comment detection
-     *
-     * @param response - Raw AI response string (may include markdown code fences)
-     * @param content - Original content to validate offsets against
-     * @returns Array of validated comment matches
-     */
-    static parseComments(response: string, content: string): CommentMatch[];
-    /**
-     * Parse and validate AI response for highlight detection
-     *
-     * @param response - Raw AI response string (may include markdown code fences)
-     * @param content - Original content to validate offsets against
-     * @returns Array of validated highlight matches
-     */
-    static parseHighlights(response: string, content: string): HighlightMatch[];
-    /**
-     * Parse and validate AI response for assessment detection
-     *
-     * @param response - Raw AI response string (may include markdown code fences)
-     * @param content - Original content to validate offsets against
-     * @returns Array of validated assessment matches
-     */
-    static parseAssessments(response: string, content: string): AssessmentMatch[];
-    /**
-     * Parse and validate AI response for tag detection
-     * Note: Does NOT validate offsets - caller must do that with content
-     *
-     * @param response - Raw AI response string (may include markdown code fences)
-     * @returns Array of tag matches (offsets not yet validated)
-     */
-    static parseTags(response: string): Omit<TagMatch, 'category'>[];
-    /**
-     * Validate tag offsets against content and add category
-     * Helper for tag detection after initial parsing
-     *
-     * @param tags - Parsed tags without validated offsets
-     * @param content - Original content to validate against
-     * @param category - Category to assign to validated tags
-     * @returns Array of validated tag matches
-     */
-    static validateTagOffsets(tags: Omit<TagMatch, 'category'>[], content: string, category: string): TagMatch[];
-}
-
-/**
- * Annotation Detection
- *
- * Orchestrates the full annotation detection pipeline:
- * 1. Fetch resource metadata and content
- * 2. Build AI prompts using MotivationPrompts
- * 3. Call AI inference
- * 4. Parse and validate results using MotivationParsers
- *
- * This is the high-level API for AI-powered annotation detection.
- * Workers and other consumers should use these methods instead of
- * implementing detection logic directly.
- */
-
-declare class AnnotationDetection {
-    /**
-     * Detect comments in a resource
-     *
-     * @param resourceId - The resource to analyze
-     * @param config - Environment configuration
-     * @param client - Inference client for AI operations
-     * @param instructions - Optional user instructions for comment generation
-     * @param tone - Optional tone guidance (e.g., "academic", "conversational")
-     * @param density - Optional target number of comments per 2000 words
-     * @returns Array of validated comment matches
-     */
-    static detectComments(resourceId: ResourceId, config: EnvironmentConfig, client: InferenceClient, instructions?: string, tone?: string, density?: number): Promise<CommentMatch[]>;
-    /**
-     * Detect highlights in a resource
-     *
-     * @param resourceId - The resource to analyze
-     * @param config - Environment configuration
-     * @param client - Inference client for AI operations
-     * @param instructions - Optional user instructions for highlight selection
-     * @param density - Optional target number of highlights per 2000 words
-     * @returns Array of validated highlight matches
-     */
-    static detectHighlights(resourceId: ResourceId, config: EnvironmentConfig, client: InferenceClient, instructions?: string, density?: number): Promise<HighlightMatch[]>;
-    /**
-     * Detect assessments in a resource
-     *
-     * @param resourceId - The resource to analyze
-     * @param config - Environment configuration
-     * @param client - Inference client for AI operations
-     * @param instructions - Optional user instructions for assessment generation
-     * @param tone - Optional tone guidance (e.g., "critical", "supportive")
-     * @param density - Optional target number of assessments per 2000 words
-     * @returns Array of validated assessment matches
-     */
-    static detectAssessments(resourceId: ResourceId, config: EnvironmentConfig, client: InferenceClient, instructions?: string, tone?: string, density?: number): Promise<AssessmentMatch[]>;
-    /**
-     * Detect tags in a resource for a specific category
-     *
-     * @param resourceId - The resource to analyze
-     * @param config - Environment configuration
-     * @param client - Inference client for AI operations
-     * @param schemaId - The tag schema identifier (e.g., "irac", "imrad")
-     * @param category - The specific category to detect
-     * @returns Array of validated tag matches
-     */
-    static detectTags(resourceId: ResourceId, config: EnvironmentConfig, client: InferenceClient, schemaId: string, category: string): Promise<TagMatch[]>;
-    /**
-     * Load resource content from representation store
-     * Helper method used by all detection methods
-     *
-     * @param resourceId - The resource ID to load
-     * @param config - Environment configuration
-     * @returns Resource content as string, or null if not available
-     */
-    private static loadResourceContent;
-}
-
-/**
- * Prompt builders for annotation detection motivations
- *
- * Provides static methods to build AI prompts for each Web Annotation motivation type.
- * Extracted from worker implementations to centralize prompt logic.
- */
-declare class MotivationPrompts {
-    /**
-     * Build a prompt for detecting comment-worthy passages
-     *
-     * @param content - The text content to analyze (will be truncated to 8000 chars)
-     * @param instructions - Optional user-provided instructions
-     * @param tone - Optional tone guidance (e.g., "academic", "conversational")
-     * @param density - Optional target number of comments per 2000 words
-     * @returns Formatted prompt string
-     */
-    static buildCommentPrompt(content: string, instructions?: string, tone?: string, density?: number): string;
-    /**
-     * Build a prompt for detecting highlight-worthy passages
-     *
-     * @param content - The text content to analyze (will be truncated to 8000 chars)
-     * @param instructions - Optional user-provided instructions
-     * @param density - Optional target number of highlights per 2000 words
-     * @returns Formatted prompt string
-     */
-    static buildHighlightPrompt(content: string, instructions?: string, density?: number): string;
-    /**
-     * Build a prompt for detecting assessment-worthy passages
-     *
-     * @param content - The text content to analyze (will be truncated to 8000 chars)
-     * @param instructions - Optional user-provided instructions
-     * @param tone - Optional tone guidance (e.g., "critical", "supportive")
-     * @param density - Optional target number of assessments per 2000 words
-     * @returns Formatted prompt string
-     */
-    static buildAssessmentPrompt(content: string, instructions?: string, tone?: string, density?: number): string;
-    /**
-     * Build a prompt for detecting structural tags
-     *
-     * @param content - The full text content to analyze (NOT truncated for structural analysis)
-     * @param category - The specific category to detect
-     * @param schemaName - Human-readable schema name
-     * @param schemaDescription - Schema description
-     * @param schemaDomain - Schema domain
-     * @param categoryDescription - Category description
-     * @param categoryExamples - Example questions/guidance for this category
-     * @returns Formatted prompt string
-     */
-    static buildTagPrompt(content: string, category: string, schemaName: string, schemaDescription: string, schemaDomain: string, categoryDescription: string, categoryExamples: string[]): string;
-}
-
-/**
- * Entity reference extracted from text
- */
-interface ExtractedEntity {
-    exact: string;
-    entityType: string;
-    startOffset: number;
-    endOffset: number;
-    prefix?: string;
-    suffix?: string;
-}
-/**
- * Extract entity references from text using AI
- *
- * @param text - The text to analyze
- * @param entityTypes - Array of entity types to detect (optionally with examples)
- * @param client - Inference client for AI operations
- * @param includeDescriptiveReferences - Include anaphoric/cataphoric references (default: false)
- * @param logger - Optional logger for debugging entity extraction
- * @returns Array of extracted entities with their character offsets
- */
-declare function extractEntities(exact: string, entityTypes: string[] | {
-    type: string;
-    examples?: string[];
-}[], client: InferenceClient, includeDescriptiveReferences?: boolean, logger?: Logger): Promise<ExtractedEntity[]>;
-
 /**
  * Resource Generation Functions
  *
@@ -932,13 +653,6 @@ declare function extractEntities(exact: string, entityTypes: string[] | {
  *
  */
 
-/**
- * Generate resource content using inference
- */
-declare function generateResourceFromTopic(topic: string, entityTypes: string[], client: InferenceClient, userPrompt?: string, locale?: string, context?: YieldContext, temperature?: number, maxTokens?: number, logger?: Logger): Promise<{
-    title: string;
-    content: string;
-}>;
 /**
  * Generate an intelligent summary for a resource
  */
@@ -948,15 +662,7 @@ declare function generateResourceSummary(resourceName: string, content: string,
  */
 declare function generateReferenceSuggestions(referenceTitle: string, client: InferenceClient, entityType?: string, currentContent?: string): Promise<string[] | null>;
 
-/**
- * ID generation utilities
- */
-/**
- * Generate a UUID v4-like ID (without dashes)
- */
-declare function generateUuid(): string;
-
 declare const PACKAGE_NAME = "@semiont/make-meaning";
 declare const VERSION = "0.1.0";
 
-export { AnnotationContext, AnnotationDetection, AnnotationOperations, AssessmentAnnotationWorker, type AssessmentMatch, type BuildContextOptions, CommentAnnotationWorker, type CommentMatch, type CreateAnnotationResult, type CreateResourceInput, type ExtractedEntity, GenerationWorker, GraphContext, GraphDBConsumer, type GraphEdge, type GraphNode, type GraphRepresentation, HighlightAnnotationWorker, type HighlightMatch, LLMContext, type LLMContextOptions, type ListResourcesFilters, type MakeMeaningService, MotivationParsers, MotivationPrompts, PACKAGE_NAME, ReferenceAnnotationWorker, ResourceContext, ResourceOperations, TagAnnotationWorker, type TagMatch, type UpdateAnnotationBodyResult, type UpdateResourceInput, VERSION, bootstrapEntityTypes, extractEntities, generateReferenceSuggestions, generateResourceFromTopic, generateResourceSummary, generateUuid, readEntityTypesProjection, resetBootstrap, startMakeMeaning };
+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 };