@semiont/make-meaning 0.5.2 → 0.5.3

package/README.md

@@ -170,6 +170,19 @@ const kb = await createKnowledgeBase(eventStore, project, graphDb, logger);
 
 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.
 
+### Pure projection validators
+
+The dispatcher in [`src/handlers/job-commands.ts`](src/handlers/job-commands.ts) does projection-validated job creation: when a `mark.assist` (linking) or `yield.fromAnnotation` job arrives with `entityTypes`, the dispatcher validates that every tag is registered; when a tagging job arrives with a `schemaId`, the dispatcher resolves it against the registered tag-schema set.
+
+Both rules are pure functions in [`src/views/projection-validators.ts`](src/views/projection-validators.ts):
+
+- `resolveTagSchema(schemas, schemaId)` → `{ schema } | { error }` — id lookup with the standard "Tag schema not registered" / "tag-annotation requires schemaId" error formats.
+- `validateEntityTypes(registered, requested)` → `{ ok: true } | { ok: false; unknown }` — set membership check that lists the offending tags in caller order.
+
+The dispatcher is the I/O shell: read the projection (via the readers in `src/views/`), pass it to the validator (pure), then either stash the resolved value or rethrow as `job:create-failed`. Validator unit tests run in single-digit milliseconds with no filesystem, no event-bus, no mock JobQueue — the dispatcher integration tests in `__tests__/handlers/job-commands.test.ts` keep the wiring covered.
+
+This pattern (functional core, imperative shell) is shared with `@semiont/event-sourcing`'s projection reducers; see [`docs/system/PROJECTION-PATTERN.md`](../../docs/system/PROJECTION-PATTERN.md) for the architectural narrative, the full axiom catalog, and guidance for adding new validators.
+
 ## Documentation
 
 - **[Architecture](./docs/architecture.md)** — Actor model, data flow, storage architecture

package/dist/index.d.ts

@@ -215,6 +215,7 @@ declare function createKnowledgeBase(eventStore: EventStore, project: SemiontPro
  * - 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
@@ -247,6 +248,7 @@ declare class Stower {
     private handleMarkArchive;
     private handleMarkUnarchive;
     private handleAddEntityType;
+    private handleAddTagSchema;
     private handleUpdateEntityTypes;
     private handleJobStart;
     private handleJobComplete;
@@ -366,6 +368,7 @@ declare class Matcher {
  * - browse:annotation-history-requested — annotation event history
  * - browse:referenced-by-requested — find annotations in the KB graph that reference a resource
  * - browse:entity-types-requested — list entity types from the project projection
+ * - browse:tag-schemas-requested — list tag schemas from the project projection
  * - browse:directory-requested — list a project directory, merging fs + ViewStorage
  */
 
@@ -386,6 +389,7 @@ declare class Browser {
     private handleBrowseAnnotationHistory;
     private handleReferencedBy;
     private handleEntityTypes;
+    private handleTagSchemas;
     private handleBrowseDirectory;
     stop(): Promise<void>;
 }
@@ -617,7 +621,7 @@ declare function registerAnnotationLookupHandlers(eventBus: EventBus, kb: Knowle
  */
 declare function registerBindUpdateBodyHandler(eventBus: EventBus, parentLogger: Logger): void;
 
-declare function registerJobCommandHandlers(eventBus: EventBus, jobQueue: JobQueue, parentLogger: Logger): void;
+declare function registerJobCommandHandlers(eventBus: EventBus, jobQueue: JobQueue, project: SemiontProject, parentLogger: Logger): void;
 
 /**
  * Bus command handlers — pure bus-event translators that bridge the
@@ -636,7 +640,7 @@ declare function registerJobCommandHandlers(eventBus: EventBus, jobQueue: JobQue
  * Register all bus command handlers on the make-meaning EventBus. Called
  * during `startMakeMeaning` after the JobQueue and KnowledgeSystem exist.
  */
-declare function registerBusHandlers(eventBus: EventBus, knowledgeSystem: KnowledgeSystem, jobQueue: JobQueue, logger: Logger): void;
+declare function registerBusHandlers(eventBus: EventBus, knowledgeSystem: KnowledgeSystem, jobQueue: JobQueue, project: SemiontProject, logger: Logger): void;
 
 /**
  * Entity Types Bootstrap

package/dist/index.js

@@ -8,7 +8,7 @@ import { getGraphDatabase } from '@semiont/graph';
 import { WorkingTreeStore, deriveStorageUri, getExtensionForMimeType } from '@semiont/content';
 import { getEntityTypes, DEFAULT_ENTITY_TYPES } from '@semiont/ontology';
 import { promises } from 'fs';
-import * as path2 from 'path';
+import * as path3 from 'path';
 import { createGzip, createGunzip } from 'zlib';
 import { pipeline, Readable } from 'stream';
 import { promisify } from 'util';
@@ -11347,6 +11347,7 @@ var Stower = class {
       pipe("mark:delete", (e) => this.handleMarkDelete(e)),
       pipe("mark:update-body", (e) => this.handleMarkUpdateBody(e)),
       pipe("frame:add-entity-type", (e) => this.handleAddEntityType(e)),
+      pipe("frame:add-tag-schema", (e) => this.handleAddTagSchema(e)),
       pipe("mark:archive", (e) => this.handleMarkArchive(e)),
       pipe("mark:unarchive", (e) => this.handleMarkUnarchive(e)),
       pipe("mark:update-entity-types", (e) => this.handleUpdateEntityTypes(e)),
@@ -11634,6 +11635,24 @@ var Stower = class {
       });
     }
   }
+  async handleAddTagSchema(event) {
+    if (!event._userId) {
+      throw new Error("frame:add-tag-schema missing _userId (gateway injection)");
+    }
+    try {
+      await this.kb.eventStore.appendEvent({
+        type: "frame:tag-schema-added",
+        userId: userId(event._userId),
+        version: 1,
+        payload: { schema: event.schema }
+      });
+    } catch (error) {
+      this.logger.error("Failed to add tag schema", { schemaId: event.schema?.id, error: errField(error) });
+      this.eventBus.get("frame:tag-schema-add-failed").next({
+        message: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
   async handleUpdateEntityTypes(event) {
     if (!event._userId) {
       throw new Error("mark:update-entity-types missing _userId (gateway injection)");
@@ -11721,7 +11740,7 @@ var Stower = class {
 var import_rxjs5 = __toESM(require_cjs());
 var import_operators5 = __toESM(require_operators());
 async function readEntityTypesProjection(project) {
-  const entityTypesPath = path2.join(
+  const entityTypesPath = path3.join(
     project.stateDir,
     "projections",
     "__system__",
@@ -11738,6 +11757,24 @@ async function readEntityTypesProjection(project) {
     throw error;
   }
 }
+async function readTagSchemasProjection(project) {
+  const tagSchemasPath = path3.join(
+    project.stateDir,
+    "projections",
+    "__system__",
+    "tagschemas.json"
+  );
+  try {
+    const content = await promises.readFile(tagSchemasPath, "utf-8");
+    const projection = JSON.parse(content);
+    return projection.tagSchemas || [];
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+}
 
 // src/browser.ts
 var Browser = class {
@@ -11767,6 +11804,7 @@ var Browser = class {
       pipe("browse:annotation-history-requested", (e) => this.handleBrowseAnnotationHistory(e)).subscribe({ error: errorHandler }),
       pipe("browse:referenced-by-requested", (e) => this.handleReferencedBy(e)).subscribe({ error: errorHandler }),
       pipe("browse:entity-types-requested", (e) => this.handleEntityTypes(e)).subscribe({ error: errorHandler }),
+      pipe("browse:tag-schemas-requested", (e) => this.handleTagSchemas(e)).subscribe({ error: errorHandler }),
       pipe("browse:directory-requested", (e) => this.handleBrowseDirectory(e)).subscribe({ error: errorHandler })
     );
   }
@@ -12011,14 +12049,29 @@ var Browser = class {
       });
     }
   }
+  async handleTagSchemas(event) {
+    try {
+      const tagSchemas = await readTagSchemasProjection(this.project);
+      this.eventBus.get("browse:tag-schemas-result").next({
+        correlationId: event.correlationId,
+        response: { tagSchemas }
+      });
+    } catch (error) {
+      this.logger.error("Tag schemas read failed", { error: errField(error) });
+      this.eventBus.get("browse:tag-schemas-failed").next({
+        correlationId: event.correlationId,
+        message: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
   // ========================================================================
   // Filesystem read handler
   // ========================================================================
   async handleBrowseDirectory(event) {
     const { correlationId, path: reqPath, sort = "name" } = event;
     const projectRoot = this.project.root;
-    const resolved = path2.resolve(projectRoot, reqPath);
-    if (!resolved.startsWith(projectRoot + path2.sep) && resolved !== projectRoot) {
+    const resolved = path3.resolve(projectRoot, reqPath);
+    if (!resolved.startsWith(projectRoot + path3.sep) && resolved !== projectRoot) {
       this.eventBus.get("browse:directory-failed").next({
         correlationId,
         path: reqPath,
@@ -12042,12 +12095,12 @@ var Browser = class {
     const allViews = await this.views.getAll();
     const prefix = `file://${resolved}`;
     const viewsByUri = new Map(
-      allViews.filter((v) => v.resource.storageUri?.startsWith(prefix + "/") || v.resource.storageUri?.startsWith(prefix + path2.sep)).map((v) => [v.resource.storageUri, v])
+      allViews.filter((v) => v.resource.storageUri?.startsWith(prefix + "/") || v.resource.storageUri?.startsWith(prefix + path3.sep)).map((v) => [v.resource.storageUri, v])
     );
     const entries = [];
     for (const dirent of visible) {
-      const entryPath = path2.join(resolved, dirent.name);
-      const relPath = path2.relative(projectRoot, entryPath);
+      const entryPath = path3.join(resolved, dirent.name);
+      const relPath = path3.relative(projectRoot, entryPath);
       if (dirent.isDirectory()) {
         let mtime = (/* @__PURE__ */ new Date(0)).toISOString();
         try {
@@ -12585,6 +12638,31 @@ function registerBindUpdateBodyHandler(eventBus, parentLogger) {
     logger.warn("Bind body-update failed after forwarding", { correlationId: cid, message });
   });
 }
+
+// src/views/projection-validators.ts
+function resolveTagSchema(tagSchemas, schemaId) {
+  if (typeof schemaId !== "string" || !schemaId) {
+    return { error: "tag-annotation requires schemaId" };
+  }
+  const schema = tagSchemas.find((s) => s.id === schemaId);
+  if (!schema) {
+    return { error: `Tag schema not registered: ${schemaId}` };
+  }
+  return { schema };
+}
+function validateEntityTypes(registered, requested) {
+  if (!requested || requested.length === 0) {
+    return { ok: true };
+  }
+  const set = new Set(registered);
+  const unknown = requested.filter((t) => !set.has(t));
+  return unknown.length > 0 ? { ok: false, unknown } : { ok: true };
+}
+function entityTypesNotRegisteredMessage(unknown) {
+  return `Entity type not registered: ${unknown.join(", ")}`;
+}
+
+// src/handlers/job-commands.ts
 function parseDidUser(did) {
   const parts = did.split(":");
   const usersIdx = parts.indexOf("users");
@@ -12592,7 +12670,7 @@ function parseDidUser(did) {
   const email = decodeURIComponent(parts.slice(usersIdx + 1).join(":"));
   return { userId: did, email, domain };
 }
-function registerJobCommandHandlers(eventBus, jobQueue, parentLogger) {
+function registerJobCommandHandlers(eventBus, jobQueue, project, parentLogger) {
   const logger = parentLogger.child({ component: "job-commands" });
   eventBus.get("job:create").subscribe(async (command) => {
     const { correlationId, jobType, resourceId: resId, params, _userId } = command;
@@ -12620,9 +12698,25 @@ function registerJobCommandHandlers(eventBus, jobQueue, parentLogger) {
         }
       };
       const jobParams = job.params;
+      if ((jobType === "reference-annotation" || jobType === "generation") && Array.isArray(jobParams.entityTypes) && jobParams.entityTypes.length > 0) {
+        const registered = await readEntityTypesProjection(project);
+        const result = validateEntityTypes(registered, jobParams.entityTypes);
+        if (!result.ok) {
+          throw new Error(entityTypesNotRegisteredMessage(result.unknown));
+        }
+      }
       if (jobType === "reference-annotation" && jobParams.entityTypes) {
         jobParams.entityTypes = jobParams.entityTypes.map((et) => entityType(et));
       }
+      if (jobType === "tag-annotation") {
+        const schemas = await readTagSchemasProjection(project);
+        const result = resolveTagSchema(schemas, jobParams.schemaId);
+        if (result.error !== void 0) {
+          throw new Error(result.error);
+        }
+        jobParams.schema = result.schema;
+        delete jobParams.schemaId;
+      }
       await jobQueue.createJob(job);
       logger.info("Job created via bus", { jobId: job.metadata.id, jobType, correlationId });
       eventBus.get("job:created").next({
@@ -12668,11 +12762,11 @@ function registerJobCommandHandlers(eventBus, jobQueue, parentLogger) {
 }
 
 // src/handlers/index.ts
-function registerBusHandlers(eventBus, knowledgeSystem, jobQueue, logger) {
+function registerBusHandlers(eventBus, knowledgeSystem, jobQueue, project, logger) {
   registerAnnotationAssemblyHandler(eventBus, logger);
   registerAnnotationLookupHandlers(eventBus, knowledgeSystem.kb, knowledgeSystem.gatherer, logger);
   registerBindUpdateBodyHandler(eventBus, logger);
-  registerJobCommandHandlers(eventBus, jobQueue, logger);
+  registerJobCommandHandlers(eventBus, jobQueue, project, logger);
 }
 
 // src/service.ts
@@ -12783,7 +12877,7 @@ async function startMakeMeaning(project, config, eventBus, logger, options) {
   const skipRebuild = options?.skipRebuild ?? process.env.SEMIONT_SKIP_REBUILD === "true";
   const { jobQueue, jobStatusSubscription } = await createJobQueue(project, eventBus, logger);
   const knowledgeSystem = await createKnowledgeSystemFromConfig(project, config, eventBus, logger, skipRebuild);
-  registerBusHandlers(eventBus, knowledgeSystem, jobQueue, logger);
+  registerBusHandlers(eventBus, knowledgeSystem, jobQueue, project, logger);
   return {
     knowledgeSystem,
     jobQueue,