@semiont/make-meaning 0.5.2 → 0.5.4

package/dist/smelter.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Smelter Actor
+ *
+ * Takes raw content, refines it into embedding vectors, persists them to the
+ * EmbeddingStore (.semiont/embeddings/), and indexes them into the VectorStore
+ * (Qdrant). Peer to the Graph Consumer.
+ *
+ * Pipeline:
+ *   1. Subscribe to resource and annotation events from the EventStore
+ *   2. Chunk resource text into overlapping passages
+ *   3. Embed each chunk via the configured EmbeddingProvider
+ *   4. Write vectors to EmbeddingStore (overwrite-in-place, git-durable)
+ *   5. Index vectors into the VectorStore (Qdrant) for fast similarity search
+ *
+ * Uses the same burst-buffer RxJS pipeline as GraphDBConsumer.
+ *
+ * ## Per-resource serialization
+ *
+ * Smelter processes events strictly in order per resourceId via
+ * `groupBy(resourceId) + concatMap(...)`. This is the stream-consumer
+ * flavor of per-resource serialization — the same invariant enforced by
+ * `GraphDBConsumer`, `Gatherer`, and (in a different shape) `ViewManager`.
+ * See `packages/core/src/serialize-per-key.ts` for the shared primitive
+ * used by RPC-style services.
+ */
+import { type EventStore, type ViewStorage } from '@semiont/event-sourcing';
+import type { Logger } from '@semiont/core';
+import type { EventBus } from '@semiont/core';
+import type { VectorStore } from '@semiont/vectors';
+import type { EmbeddingProvider } from '@semiont/vectors';
+import type { ChunkingConfig } from '@semiont/vectors';
+import type { WorkingTreeStore } from '@semiont/content';
+import type { EmbeddingStore } from './embedding-store.js';
+export declare class Smelter {
+    private eventBus;
+    private vectorStore;
+    private embeddingProvider;
+    private contentStore;
+    private embeddingStore;
+    private viewStorage;
+    private static readonly SMELTER_RELEVANT_EVENTS;
+    private static readonly BURST_WINDOW_MS;
+    private static readonly MAX_BATCH_SIZE;
+    private static readonly IDLE_TIMEOUT_MS;
+    private _globalSubscriptions;
+    private eventSubject;
+    private pipelineSubscription;
+    private readonly logger;
+    private readonly chunkingConfig;
+    constructor(_eventStore: EventStore, eventBus: EventBus, vectorStore: VectorStore, embeddingProvider: EmbeddingProvider, contentStore: WorkingTreeStore, embeddingStore: EmbeddingStore, viewStorage: ViewStorage, logger: Logger, chunkingConfig?: ChunkingConfig);
+    initialize(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Rebuild the vector store from the EmbeddingStore (.semiont/embeddings/).
+     *
+     * For each stored file, checks whether the model matches the configured
+     * provider. On mismatch, re-embeds from the stored text and overwrites the
+     * file before upserting into Qdrant. On match, loads the stored vectors
+     * directly — no embedding provider calls needed.
+     */
+    rebuildAll(): Promise<void>;
+    private processBatch;
+    /**
+     * Batch-optimized processing for consecutive events of the same type.
+     */
+    private applyBatchByType;
+    /**
+     * Batch-embed chunks from multiple yield:created events in a single
+     * embedBatch() call, then write to EmbeddingStore and index per resource.
+     */
+    private batchResourceCreated;
+    /**
+     * Batch-embed exact texts from multiple mark:added events in a single
+     * embedBatch() call, then write to EmbeddingStore and index per annotation.
+     */
+    private batchAnnotationAdded;
+    private safeProcessEvent;
+    private processEvent;
+    private handleResourceCreated;
+    /**
+     * Re-embed a resource whose content has changed in-place.
+     *
+     * Used by yield:updated and yield:representation-added handlers. Reads the
+     * current storageUri from the materialized view (which is updated before the
+     * EventBus fires), deletes stale Qdrant vectors, and overwrites the
+     * EmbeddingStore file with fresh chunks.
+     */
+    private reembedResource;
+    private handleResourceUpdated;
+    private handleRepresentationAdded;
+    private handleResourceArchived;
+    private handleAnnotationAdded;
+    private handleAnnotationRemoved;
+}
+//# sourceMappingURL=smelter.d.ts.map

package/dist/smelter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"smelter.d.ts","sourceRoot":"","sources":["../src/smelter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAIH,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAE5E,OAAO,KAAK,EAAE,MAAM,EAA4C,MAAM,eAAe,CAAC;AAEtF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,WAAW,EAAqC,MAAM,kBAAkB,CAAC;AACvF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAI3D,qBAAa,OAAO;IAkBhB,OAAO,CAAC,QAAQ;IAChB,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,iBAAiB;IACzB,OAAO,CAAC,YAAY;IACpB,OAAO,CAAC,cAAc;IACtB,OAAO,CAAC,WAAW;IAtBrB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,uBAAuB,CAG5C;IAEH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAM;IAC7C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,cAAc,CAAO;IAC7C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAO;IAE9C,OAAO,CAAC,oBAAoB,CAAsB;IAClD,OAAO,CAAC,YAAY,CAA8B;IAClD,OAAO,CAAC,oBAAoB,CAA6B;IACzD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiB;gBAG9C,WAAW,EAAE,UAAU,EACf,QAAQ,EAAE,QAAQ,EAClB,WAAW,EAAE,WAAW,EACxB,iBAAiB,EAAE,iBAAiB,EACpC,YAAY,EAAE,gBAAgB,EAC9B,cAAc,EAAE,cAAc,EAC9B,WAAW,EAAE,WAAW,EAChC,MAAM,EAAE,MAAM,EACd,cAAc,CAAC,EAAE,cAAc;IAM3B,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAyC3B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ3B;;;;;;;OAOG;IACG,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;YAwInB,YAAY;IAoB1B;;OAEG;YACW,gBAAgB;IAiB9B;;;OAGG;YACW,oBAAoB;IA6ClC;;;OAGG;YACW,oBAAoB;YAqDpB,gBAAgB;YAahB,YAAY;YAuBZ,qBAAqB;IAqDnC;;;;;;;OAOG;YACW,eAAe;YAgCf,qBAAqB;YAIrB,yBAAyB;YAIzB,sBAAsB;YAOtB,qBAAqB;YAsCrB,uBAAuB;CAWtC"}

package/dist/stower.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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)
+ * - Matcher (read search)
+ *
+ * No other code should call eventStore.appendEvent() or repStore.store().
+ *
+ * Subscriptions:
+ * - yield:create       → resource.created (+ content store)   → yield:created / yield:create-failed
+ * - yield:update       → resource.updated (+ content store)   → yield:updated / yield:update-failed
+ * - yield:mv           → resource.moved (+ working tree move) → yield:moved / yield:move-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 (+ file removal)   (resource-scoped, no result event)
+ * - mark:unarchive     → resource.unarchived                  (resource-scoped, no result event)
+ * - frame:add-entity-type → entitytype.added                   → frame:entity-type-added / frame:entity-type-add-failed
+ * - frame:add-tag-schema  → tagschema.added                    → frame:tag-schema-added / frame:tag-schema-add-failed
+ * - mark:update-entity-types → entitytag.added / entitytag.removed
+ * - job:start          → job.started
+ * - job:complete       → job.completed
+ * - job:fail           → job.failed
+ *
+ * Note: `job:report-progress` is intentionally NOT persisted. Progress
+ * events are ephemeral UI feedback and would clutter the event log
+ * (historical logs show ~3× as many progress entries as start+complete
+ * combined). UI consumers subscribe to the bus directly for live
+ * progress; the event log keeps only the durable lifecycle boundaries.
+ */
+import type { Logger, ResourceDescriptor } from '@semiont/core';
+import { EventBus } from '@semiont/core';
+import type { ResourceId } from '@semiont/core';
+import type { KnowledgeBase } from './knowledge-base';
+export interface CreateResourceResult {
+    resourceId: ResourceId;
+    resource: ResourceDescriptor;
+}
+export declare class Stower {
+    private kb;
+    private eventBus;
+    private subscription;
+    private readonly logger;
+    constructor(kb: KnowledgeBase, eventBus: EventBus, logger: Logger);
+    initialize(): Promise<void>;
+    private handleYieldCreate;
+    private handleYieldUpdate;
+    private handleYieldMv;
+    private handleMarkCreate;
+    private handleMarkDelete;
+    private handleMarkUpdateBody;
+    private handleMarkArchive;
+    private handleMarkUnarchive;
+    private handleAddEntityType;
+    private handleAddTagSchema;
+    private handleUpdateEntityTypes;
+    private handleJobStart;
+    private handleJobComplete;
+    private handleJobFail;
+    stop(): Promise<void>;
+}
+//# sourceMappingURL=stower.d.ts.map

package/dist/stower.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stower.d.ts","sourceRoot":"","sources":["../src/stower.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAKH,OAAO,KAAK,EAAwB,MAAM,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACtF,OAAO,EAAE,QAAQ,EAA0E,MAAM,eAAe,CAAC;AACjH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAGhD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEtD,MAAM,WAAW,oBAAoB;IACnC,UAAU,EAAE,UAAU,CAAC;IACvB,QAAQ,EAAE,kBAAkB,CAAC;CAC9B;AAED,qBAAa,MAAM;IAKf,OAAO,CAAC,EAAE;IACV,OAAO,CAAC,QAAQ;IALlB,OAAO,CAAC,YAAY,CAA6B;IACjD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAGtB,EAAE,EAAE,aAAa,EACjB,QAAQ,EAAE,QAAQ,EAC1B,MAAM,EAAE,MAAM;IAKV,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;YAkCnB,iBAAiB;YAqGjB,iBAAiB;YA4BjB,aAAa;YAuCb,gBAAgB;YA2BhB,gBAAgB;YAwBhB,oBAAoB;YA2BpB,iBAAiB;YAgBjB,mBAAmB;YAuBnB,mBAAmB;YAoBnB,kBAAkB;YAoBlB,uBAAuB;YA6BvB,cAAc;YAiBd,iBAAiB;YAkBjB,aAAa;IAkBrB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAK5B"}

package/dist/views/entity-types-reader.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Entity Types Projection Reader
+ *
+ * Reads entity types from the view storage projection file.
+ * This file is maintained by ViewMaterializer in response to entitytype.added events.
+ */
+import type { SemiontProject } from '@semiont/core/node';
+/**
+ * Read entity types from view storage projection
+ */
+export declare function readEntityTypesProjection(project: SemiontProject): Promise<string[]>;
+//# sourceMappingURL=entity-types-reader.d.ts.map

package/dist/views/entity-types-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-types-reader.d.ts","sourceRoot":"","sources":["../../src/views/entity-types-reader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD;;GAEG;AACH,wBAAsB,yBAAyB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAsB1F"}

package/dist/views/projection-validators.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Projection validators — pure functions that take a projection's
+ * current state plus a caller-supplied command input and decide
+ * whether the input is valid against the registered vocabulary.
+ *
+ * Used by the dispatcher in `handlers/job-commands.ts`. The dispatcher
+ * reads the projection (I/O), passes it here (pure), and either
+ * resolves the input or rejects with the error these functions return.
+ *
+ * Sibling to the projection-reducers in `@semiont/event-sourcing` —
+ * reducers handle the write side of projections; validators handle
+ * the read side. Both are I/O-free so the test for "unknown schemaId
+ * rejects" doesn't need a filesystem or a Stower.
+ *
+ * Load-bearing properties (mutual exclusion, soundness, completeness,
+ * order preservation, no-mutation) are pinned by axiom-style
+ * fast-check tests in `__tests__/views/projection-validators.test.ts`.
+ * See `docs/system/PROJECTION-PATTERN.md` for the full axiom catalog
+ * and the architectural narrative.
+ */
+import type { TagSchema } from '@semiont/core';
+/**
+ * Result of {@link resolveTagSchema}.
+ *
+ * Discriminated union — callers narrow on the absence of `error` to
+ * get a typed `TagSchema`.
+ */
+export type ResolveTagSchemaResult = {
+    schema: TagSchema;
+    error?: undefined;
+} | {
+    schema?: undefined;
+    error: string;
+};
+/**
+ * Look up a tag schema by id in the per-KB tag-schema projection.
+ *
+ * Pure read of `tagSchemas` (the unwrapped projection content; what
+ * `readTagSchemasProjection` returns). Returns either the resolved
+ * schema or a caller-facing error message.
+ *
+ * Two failure modes:
+ *  - Empty/missing schemaId → "tag-annotation requires schemaId"
+ *  - Non-empty but unregistered → "Tag schema not registered: <id>"
+ *
+ * Both messages are surfaced verbatim to the bus via `job:create-failed`.
+ */
+export declare function resolveTagSchema(tagSchemas: readonly TagSchema[], schemaId: unknown): ResolveTagSchemaResult;
+/**
+ * Result of {@link validateEntityTypes}.
+ *
+ * Two cases — `ok: true` when all supplied tags are in the registered
+ * set (or none were supplied at all), `ok: false` plus the offending
+ * unknown tags otherwise.
+ */
+export type ValidateEntityTypesResult = {
+    ok: true;
+} | {
+    ok: false;
+    unknown: string[];
+};
+/**
+ * Validate that every caller-supplied entity type is in the per-KB
+ * entity-type projection.
+ *
+ * Pure read of `registered` (the unwrapped projection content; what
+ * `readEntityTypesProjection` returns). Empty/missing `requested`
+ * skips the check entirely — "no tags supplied" is not a validation
+ * failure, and the validator should never trigger an unnecessary
+ * projection read for it.
+ */
+export declare function validateEntityTypes(registered: readonly string[], requested: readonly string[] | undefined): ValidateEntityTypesResult;
+/**
+ * Format the standard error message for an entity-type validation
+ * failure. Kept here so the dispatcher and any future caller agree on
+ * the wire format — same `Entity type not registered: <comma-list>`
+ * shape that `mark.assist` and `yield.fromAnnotation` callers handle.
+ */
+export declare function entityTypesNotRegisteredMessage(unknown: readonly string[]): string;
+//# sourceMappingURL=projection-validators.d.ts.map

package/dist/views/projection-validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projection-validators.d.ts","sourceRoot":"","sources":["../../src/views/projection-validators.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAI/C;;;;;GAKG;AACH,MAAM,MAAM,sBAAsB,GAC9B;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAE,GACxC;IAAE,MAAM,CAAC,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1C;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAC9B,UAAU,EAAE,SAAS,SAAS,EAAE,EAChC,QAAQ,EAAE,OAAO,GAChB,sBAAsB,CASxB;AAID;;;;;;GAMG;AACH,MAAM,MAAM,yBAAyB,GACjC;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GACZ;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAErC;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,SAAS,MAAM,EAAE,EAC7B,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GACvC,yBAAyB,CAO3B;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAElF"}

package/dist/views/tag-schemas-reader.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Tag Schemas Projection Reader
+ *
+ * Reads tag schemas from the view storage projection file.
+ * This file is maintained by ViewMaterializer in response to
+ * `frame:tag-schema-added` events.
+ */
+import type { SemiontProject } from '@semiont/core/node';
+import type { TagSchema } from '@semiont/core';
+/**
+ * Read tag schemas from view storage projection
+ */
+export declare function readTagSchemasProjection(project: SemiontProject): Promise<TagSchema[]>;
+//# sourceMappingURL=tag-schemas-reader.d.ts.map

package/dist/views/tag-schemas-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-schemas-reader.d.ts","sourceRoot":"","sources":["../../src/views/tag-schemas-reader.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAE/C;;GAEG;AACH,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAqB5F"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@semiont/make-meaning",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "type": "module",
   "description": "Making meaning from resources through context assembly, pattern detection, and relationship reasoning",
   "main": "./dist/index.js",
@@ -20,7 +20,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "npm run typecheck && tsup",
+    "build": "npm run typecheck && tsup && tsc -p tsconfig.build.json",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf dist",
     "test": "vitest run",
@@ -42,8 +42,9 @@
   },
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.0",
+    "fast-check": "^4.3.0",
     "tsup": "^8.0.1",
-    "typescript": "^5.6.3"
+    "typescript": "^6.0.2"
   },
   "keywords": [
     "semantic-annotation",