@semiont/make-meaning 0.5.10 → 0.5.11

package/README.md

@@ -13,7 +13,7 @@ This package implements the actor model from [ACTOR-MODEL.md](../../docs/system/
 Five **access actors** mediate every read and write — the bus-facing interface of the Knowledge Base:
 
 - **Stower** (write) — the single write gateway to the Knowledge Base; handles all resource and annotation mutations and job lifecycle events
-- **Browser** (read) — handles all KB read queries: resources, annotations, events, annotation history, referenced-by lookups, entity type and tag-schema listing, and directory browse (merging filesystem listings with KB metadata)
+- **Browser** (read) — handles all KB read queries: resources, annotations, events, annotation history, referenced-by lookups, entity type and tag-schema listing, the collaborator directory (the KB's declared software agents, derived from the workers/actors inference config), and directory browse (merging filesystem listings with KB metadata)
 - **Gatherer** (context assembly) — assembles gathered context for annotations (`gather:requested`) and resources (`gather:resource-requested`); searches vectors for semantically similar passages (adds `semanticContext` to `GatheredContext`)
 - **Matcher** (search/link) — context-driven candidate search with multi-source retrieval, composite structural scoring, and optional LLM semantic scoring
 - **CloneTokenManager** (yield) — manages clone token lifecycle for resource cloning
@@ -130,7 +130,7 @@ graph TB
     end
 
     BUS -->|"yield:create, yield:update, yield:mv<br/>mark:create, mark:delete, mark:update-body<br/>frame:add-entity-type, frame:add-tag-schema<br/>mark:archive, mark:unarchive, mark:update-entity-types<br/>job:start, job:complete, job:fail"| STOWER
-    BUS -->|"browse:resource-requested, browse:resources-requested<br/>browse:annotations-requested, browse:annotation-requested<br/>browse:events-requested, browse:annotation-history-requested<br/>browse:referenced-by-requested, browse:entity-types-requested<br/>browse:tag-schemas-requested, browse:directory-requested"| BROWSER
+    BUS -->|"browse:resource-requested, browse:resources-requested<br/>browse:annotations-requested, browse:annotation-requested<br/>browse:events-requested, browse:annotation-history-requested<br/>browse:referenced-by-requested, browse:entity-types-requested<br/>browse:tag-schemas-requested, browse:agents-requested<br/>browse:directory-requested"| BROWSER
     BUS -->|"gather:requested<br/>gather:resource-requested"| GATHERER
     BUS -->|"match:search-requested"| MATCHER
     BUS -->|"domain events:<br/>yield:created, yield:updated<br/>yield:representation-added<br/>mark:added, mark:removed, mark:archived"| SMELTER
@@ -138,7 +138,7 @@ graph TB
     BUS -->|"yield:clone-token-requested<br/>yield:clone-resource-requested<br/>yield:clone-create"| CTM
 
     STOWER -->|"yield:create-ok, yield:update-ok, yield:move-ok<br/>mark:delete-ok, *-failed replies<br/>(domain events are republished onto the bus<br/>by the EventStore: yield:created, mark:added, ...)"| BUS
-    BROWSER -->|"browse:resource-result, browse:resources-result<br/>browse:annotations-result, browse:annotation-result<br/>browse:events-result, browse:annotation-history-result<br/>browse:referenced-by-result, browse:entity-types-result<br/>browse:tag-schemas-result, browse:directory-result"| BUS
+    BROWSER -->|"browse:resource-result, browse:resources-result<br/>browse:annotations-result, browse:annotation-result<br/>browse:events-result, browse:annotation-history-result<br/>browse:referenced-by-result, browse:entity-types-result<br/>browse:tag-schemas-result, browse:agents-result<br/>browse:directory-result"| BUS
     GATHERER -->|"gather:complete, gather:failed<br/>gather:resource-complete, gather:resource-failed"| BUS
     MATCHER -->|"match:search-results, match:search-failed"| BUS
     CTM -->|"yield:clone-token-generated<br/>yield:clone-resource-result<br/>yield:clone-created"| BUS

package/dist/index.d.ts

@@ -49,6 +49,16 @@ interface MakeMeaningConfig {
         vectors?: VectorsServiceConfig;
         embedding?: EmbeddingServiceConfig;
     };
+    /**
+     * The KB's canonical identity domain — the SAME value `/api/tokens/agent`
+     * mints agent DIDs from (backend `site.domain`). The agent roster consumes
+     * it verbatim, so directory DIDs and work-stamped `generator` DIDs are
+     * equal by construction; it is never derived from service topology
+     * (.plans/bugs/agent-did-host-skew.md).
+     */
+    site?: {
+        domain: string;
+    };
     /** Per-actor inference config */
     actors?: ActorInferenceConfig;
     /** Per-worker-type inference config */
@@ -235,9 +245,10 @@ interface CreateResourceResult {
 declare class Stower {
     private kb;
     private eventBus;
+    private project;
     private subscription;
     private readonly logger;
-    constructor(kb: KnowledgeBase, eventBus: EventBus, logger: Logger);
+    constructor(kb: KnowledgeBase, eventBus: EventBus, project: SemiontProject, logger: Logger);
     initialize(): Promise<void>;
     private handleYieldCreate;
     private handleYieldUpdate;
@@ -374,6 +385,8 @@ declare class Matcher {
  * - 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:agents-requested — the collaborator directory: the KB's declared software
+ *   agents, derived from the workers + actors inference config (COLLABORATOR-DIRECTORY)
  * - browse:directory-requested — list a project directory, merging fs + ViewStorage
  */
 
@@ -382,9 +395,10 @@ declare class Browser {
     private kb;
     private eventBus;
     private project;
+    private config;
     private subscriptions;
     private readonly logger;
-    constructor(views: ViewStorage, kb: KnowledgeBase, eventBus: EventBus, project: SemiontProject, logger: Logger);
+    constructor(views: ViewStorage, kb: KnowledgeBase, eventBus: EventBus, project: SemiontProject, config: MakeMeaningConfig, logger: Logger);
     initialize(): Promise<void>;
     private handleBrowseResource;
     private handleBrowseResources;
@@ -395,6 +409,7 @@ declare class Browser {
     private handleReferencedBy;
     private handleEntityTypes;
     private handleTagSchemas;
+    private handleBrowseAgents;
     private handleBrowseDirectory;
     stop(): Promise<void>;
 }
@@ -1023,6 +1038,8 @@ interface ReplayStats {
 
 interface BackupImporterOptions {
     eventBus: EventBus;
+    /** Replay appends historical events directly (facts, not commands). */
+    eventStore: EventStore;
     contentStore: WorkingTreeStore;
     logger?: Logger;
 }

package/dist/index.js

@@ -1,6 +1,6 @@
 import { FsJobQueue } from '@semiont/jobs';
 import { FilesystemViewStorage, resolveStorageUri, EventQuery, createEventStore } from '@semiont/event-sourcing';
-import { getPrimaryRepresentation, decodeRepresentation, getResourceEntityTypes, getResourceId, getTargetSource, resourceId, getBodySource, getTargetSelector, deriveViews, getTextPositionSelector, annotationId, errField, userId, generateUuid, getExactText, busRequest, cloneToken, baseMediaType, isSupportedMediaType, capabilitiesOf, didToAgent, assembleAnnotation, jobId, entityType, baseUrl, busLog, BRIDGED_CHANNELS, burstBuffer, textExtractionOf, getPrimaryMediaType, extensionForMediaType, applyBodyOperations, findBodyItem } from '@semiont/core';
+import { getPrimaryRepresentation, decodeRepresentation, getResourceEntityTypes, getResourceId, getTargetSource, resourceId, getBodySource, getTargetSelector, deriveViews, getTextPositionSelector, annotationId, errField, userId, generateUuid, getExactText, busRequest, cloneToken, baseMediaType, isSupportedMediaType, capabilitiesOf, didToAgent, assembleAnnotation, jobId, entityType, baseUrl, busLog, BRIDGED_CHANNELS, burstBuffer, textExtractionOf, getPrimaryMediaType, extensionForMediaType, applyBodyOperations, findBodyItem, softwareToAgent } from '@semiont/core';
 import { withActorSpan, recordBusEmit, withSpan, SpanKind, registerJobQueueProvider, registerVectorIndexSizeProvider } from '@semiont/observability';
 import { createInferenceClient } from '@semiont/inference';
 import { getGraphDatabase } from '@semiont/graph';
@@ -9733,6 +9733,15 @@ function resolveActorInference(config, actor) {
     `No inference config found for actor '${actor}'. Set actors.${actor}.inference in your config.`
   );
 }
+function resolveWorkerInference(config, workerType) {
+  const specific = config.workers?.[workerType];
+  if (specific) return specific;
+  const defaultWorker = config.workers?.default;
+  if (defaultWorker) return defaultWorker;
+  throw new Error(
+    `No inference config found for worker '${workerType}'. Set workers.${workerType}.inference or workers.default.inference in your config.`
+  );
+}
 
 // src/service.ts
 var import_rxjs7 = __toESM(require_cjs());
@@ -10055,7 +10064,7 @@ var GraphDBConsumer = class _GraphDBConsumer {
         {
           const rid = resourceId(event.resourceId);
           const doc = await graphDb.getResource(rid);
-          if (doc) {
+          if (doc && !(doc.entityTypes || []).includes(event.payload.entityType)) {
             await graphDb.updateResource(rid, {
               entityTypes: [...doc.entityTypes || [], event.payload.entityType]
             });
@@ -11345,14 +11354,59 @@ For each candidate, output a line with the number and score, like:
 // src/stower.ts
 var import_rxjs4 = __toESM(require_cjs());
 var import_operators4 = __toESM(require_operators());
+async function readEntityTypesProjection(project) {
+  const entityTypesPath = path3.join(
+    project.stateDir,
+    "projections",
+    "__system__",
+    "entitytypes.json"
+  );
+  try {
+    const content = await promises.readFile(entityTypesPath, "utf-8");
+    const projection = JSON.parse(content);
+    return projection.entityTypes || [];
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+}
+
+// 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/stower.ts
 var Stower = class {
-  constructor(kb, eventBus, logger) {
+  constructor(kb, eventBus, project, logger) {
     this.kb = kb;
     this.eventBus = eventBus;
+    this.project = project;
     this.logger = logger;
   }
   kb;
   eventBus;
+  project;
   subscription = null;
   logger;
   async initialize() {
@@ -11688,22 +11742,38 @@ var Stower = class {
     const uid = userId(event._userId);
     const added = event.updatedEntityTypes.filter((et) => !event.currentEntityTypes.includes(et));
     const removed = event.currentEntityTypes.filter((et) => !event.updatedEntityTypes.includes(et));
-    for (const entityType2 of added) {
-      await this.kb.eventStore.appendEvent({
-        type: "mark:entity-tag-added",
-        resourceId: resourceId(event.resourceId),
-        userId: uid,
-        version: 1,
-        payload: { entityType: entityType2 }
-      });
-    }
-    for (const entityType2 of removed) {
-      await this.kb.eventStore.appendEvent({
-        type: "mark:entity-tag-removed",
-        resourceId: resourceId(event.resourceId),
-        userId: uid,
-        version: 1,
-        payload: { entityType: entityType2 }
+    try {
+      if (added.length > 0) {
+        const registered = await readEntityTypesProjection(this.project);
+        const result = validateEntityTypes(registered, added);
+        if (!result.ok) {
+          throw new Error(entityTypesNotRegisteredMessage(result.unknown));
+        }
+      }
+      for (const entityType2 of added) {
+        await this.kb.eventStore.appendEvent({
+          type: "mark:entity-tag-added",
+          resourceId: resourceId(event.resourceId),
+          userId: uid,
+          version: 1,
+          payload: { entityType: entityType2 }
+        });
+      }
+      for (const entityType2 of removed) {
+        await this.kb.eventStore.appendEvent({
+          type: "mark:entity-tag-removed",
+          resourceId: resourceId(event.resourceId),
+          userId: uid,
+          version: 1,
+          payload: { entityType: entityType2 }
+        });
+      }
+      this.eventBus.get("mark:update-entity-types-ok").next({ correlationId: event.correlationId });
+    } catch (error) {
+      this.logger.error("Failed to update entity types", { error: errField(error) });
+      this.eventBus.get("mark:update-entity-types-failed").next({
+        correlationId: event.correlationId,
+        message: error instanceof Error ? error.message : String(error)
       });
     }
   }
@@ -11767,24 +11837,6 @@ var Stower = class {
 // src/browser.ts
 var import_rxjs5 = __toESM(require_cjs());
 var import_operators5 = __toESM(require_operators());
-async function readEntityTypesProjection(project) {
-  const entityTypesPath = path3.join(
-    project.stateDir,
-    "projections",
-    "__system__",
-    "entitytypes.json"
-  );
-  try {
-    const content = await promises.readFile(entityTypesPath, "utf-8");
-    const projection = JSON.parse(content);
-    return projection.entityTypes || [];
-  } catch (error) {
-    if (error.code === "ENOENT") {
-      return [];
-    }
-    throw error;
-  }
-}
 async function readTagSchemasProjection(project) {
   const tagSchemasPath = path3.join(
     project.stateDir,
@@ -11815,20 +11867,66 @@ async function assembleResourceGraph(kb, resourceId10) {
   });
   return { resource: stored.resource, annotations, entityReferences };
 }
+var JOB_TYPES = [
+  "reference-annotation",
+  "highlight-annotation",
+  "assessment-annotation",
+  "comment-annotation",
+  "tag-annotation",
+  "generation"
+];
+function deriveAgentRoster(config) {
+  const domain = config.site?.domain;
+  if (!domain) {
+    throw new Error(
+      "site.domain is required to mint agent DIDs \u2014 the directory must use the same canonical domain /api/tokens/agent mints worker DIDs from (no topology fallback)"
+    );
+  }
+  const roster = /* @__PURE__ */ new Map();
+  const admit = (inference, jobType) => {
+    const key = `${inference.type}\0${inference.model}`;
+    let entry = roster.get(key);
+    if (!entry) {
+      entry = {
+        agent: softwareToAgent({ domain, provider: inference.type, model: inference.model }),
+        servesJobTypes: []
+      };
+      roster.set(key, entry);
+    }
+    if (jobType) entry.servesJobTypes.push(jobType);
+  };
+  for (const jobType of JOB_TYPES) {
+    try {
+      admit(resolveWorkerInference(config, jobType), jobType);
+    } catch {
+    }
+  }
+  for (const actor of ["gatherer", "matcher"]) {
+    try {
+      admit(resolveActorInference(config, actor));
+    } catch {
+    }
+  }
+  return [...roster.values()].map(
+    ({ agent, servesJobTypes }) => servesJobTypes.length ? { agent, servesJobTypes } : { agent }
+  );
+}
 
 // src/browser.ts
 var Browser = class {
-  constructor(views, kb, eventBus, project, logger) {
+  constructor(views, kb, eventBus, project, config, logger) {
     this.views = views;
     this.kb = kb;
     this.eventBus = eventBus;
     this.project = project;
+    this.config = config;
     this.logger = logger;
   }
   views;
   kb;
   eventBus;
   project;
+  config;
   subscriptions = [];
   logger;
   async initialize() {
@@ -11861,6 +11959,7 @@ var Browser = class {
       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:agents-requested", (e) => this.handleBrowseAgents(e)).subscribe({ error: errorHandler }),
       pipe("browse:directory-requested", (e) => this.handleBrowseDirectory(e)).subscribe({ error: errorHandler })
     );
   }
@@ -12109,6 +12208,21 @@ var Browser = class {
       });
     }
   }
+  async handleBrowseAgents(event) {
+    try {
+      const agents = deriveAgentRoster(this.config);
+      this.eventBus.get("browse:agents-result").next({
+        correlationId: event.correlationId,
+        response: { agents }
+      });
+    } catch (error) {
+      this.logger.error("Agent roster derivation failed", { error: errField(error) });
+      this.eventBus.get("browse:agents-failed").next({
+        correlationId: event.correlationId,
+        message: error instanceof Error ? error.message : String(error)
+      });
+    }
+  }
   // ========================================================================
   // Filesystem read handler
   // ========================================================================
@@ -12669,31 +12783,6 @@ 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");
@@ -12944,7 +13033,7 @@ async function createKnowledgeSystemFromConfig(project, config, eventBus, logger
     if (annotation === null) return event;
     return { ...event, annotation };
   });
-  const stower = new Stower(kb, eventBus, logger.child({ component: "stower" }));
+  const stower = new Stower(kb, eventBus, project, logger.child({ component: "stower" }));
   await stower.initialize();
   await bootstrapEntityTypes(eventBus, eventStore, logger.child({ component: "entity-types-bootstrap" }));
   const gatherer = new Gatherer(
@@ -12963,7 +13052,7 @@ async function createKnowledgeSystemFromConfig(project, config, eventBus, logger
     embeddingProvider
   );
   await matcher.initialize();
-  const browser = new Browser(kb.views, kb, eventBus, project, logger.child({ component: "browser" }));
+  const browser = new Browser(kb.views, kb, eventBus, project, config, logger.child({ component: "browser" }));
   await browser.initialize();
   const cloneTokenManager = new CloneTokenManager(kb, eventBus, logger.child({ component: "clone-token-manager" }));
   await cloneTokenManager.initialize();
@@ -13875,7 +13964,7 @@ function awaitReply(eventBus, command, payload, okChannel, failedChannel, timeou
   return (0, import_rxjs11.firstValueFrom)(result$);
 }
 var REPLAY_TIMEOUT_MS = 3e4;
-async function replayEventStream(jsonl, eventBus, resolveBlob, contentStore, logger) {
+async function replayEventStream(jsonl, eventBus, eventStore, resolveBlob, contentStore, logger) {
   const lines = jsonl.trim().split("\n").filter((l) => l.length > 0);
   const storedEvents = lines.map((line) => JSON.parse(line));
   const stats = {
@@ -13885,12 +13974,12 @@ async function replayEventStream(jsonl, eventBus, resolveBlob, contentStore, log
     entityTypesAdded: 0
   };
   for (const stored of storedEvents) {
-    await replayEvent(stored, eventBus, resolveBlob, contentStore, stats, logger);
+    await replayEvent(stored, eventBus, eventStore, resolveBlob, contentStore, stats, logger);
     stats.eventsReplayed++;
   }
   return { stats };
 }
-async function replayEvent(event, eventBus, resolveBlob, contentStore, stats, logger) {
+async function replayEvent(event, eventBus, eventStore, resolveBlob, contentStore, stats, logger) {
   switch (event.type) {
     case "frame:entity-type-added":
       await replayEntityTypeAdded(event, eventBus, logger);
@@ -13918,7 +14007,7 @@ async function replayEvent(event, eventBus, resolveBlob, contentStore, stats, lo
       break;
     case "mark:entity-tag-added":
     case "mark:entity-tag-removed":
-      await replayEntityTagChange(event, eventBus, logger);
+      await replayEntityTagChange(event, eventStore, logger);
       break;
     // Job events are transient — skip during replay
     case "job:started":
@@ -14034,25 +14123,18 @@ async function replayResourceUnarchived(event, eventBus, logger) {
   });
   logger?.debug("Replayed resource.unarchived", { resourceId: event.resourceId });
 }
-async function replayEntityTagChange(event, eventBus, logger) {
-  const resourceId10 = event.resourceId;
-  const entityType2 = event.payload.entityType;
+async function replayEntityTagChange(event, eventStore, logger) {
+  const base = {
+    resourceId: event.resourceId,
+    userId: event.userId,
+    version: event.version
+  };
   if (event.type === "mark:entity-tag-added") {
-    eventBus.get("mark:update-entity-types").next({
-      resourceId: resourceId10,
-      _userId: event.userId,
-      currentEntityTypes: [],
-      updatedEntityTypes: [entityType2]
-    });
+    await eventStore.appendEvent({ ...base, type: "mark:entity-tag-added", payload: event.payload });
   } else {
-    eventBus.get("mark:update-entity-types").next({
-      resourceId: resourceId10,
-      _userId: event.userId,
-      currentEntityTypes: [entityType2],
-      updatedEntityTypes: []
-    });
+    await eventStore.appendEvent({ ...base, type: "mark:entity-tag-removed", payload: event.payload });
   }
-  logger?.debug("Replayed entity tag change", { type: event.type, entityType: entityType2 });
+  logger?.debug("Replayed entity tag change", { type: event.type, entityType: event.payload.entityType });
 }
 
 // src/exchange/backup-importer.ts
@@ -14071,7 +14153,7 @@ function buildBlobResolver(entries) {
   };
 }
 async function importBackup(archive, options) {
-  const { eventBus, contentStore, logger } = options;
+  const { eventBus, eventStore, contentStore, logger } = options;
   const entries = /* @__PURE__ */ new Map();
   for await (const entry of readTarGz(archive)) {
     entries.set(entry.name, entry.data);
@@ -14099,6 +14181,7 @@ async function importBackup(archive, options) {
     const result = await replayEventStream(
       systemData.toString("utf8"),
       eventBus,
+      eventStore,
       resolveBlob,
       contentStore,
       logger
@@ -14115,6 +14198,7 @@ async function importBackup(archive, options) {
     const result = await replayEventStream(
       eventData.toString("utf8"),
       eventBus,
+      eventStore,
       resolveBlob,
       contentStore,
       logger