@semiont/make-meaning 0.5.12 → 0.5.14

package/dist/index.d.ts

@@ -44,6 +44,16 @@ interface WorkerInferenceConfig {
 }
 /** Narrow config type — only the fields make-meaning actually reads */
 interface MakeMeaningConfig {
+    /**
+     * Resource-gather policy. `settleTimeoutMs` bounds the semanticContext
+     * read-your-writes barrier (SMELTER-INDEX-SYNC D3/D5) — REQUIRED: the TOML
+     * loader owns the one default (15s at `[environments.<env>.make-meaning.gather]`);
+     * hand-built configs (scripts, tests) state their policy explicitly. Must
+     * nest inside downstream watchdogs (A4).
+     */
+    gather: {
+        settleTimeoutMs: number;
+    };
     services: {
         graph?: GraphServiceConfig;
         vectors?: VectorsServiceConfig;
@@ -276,10 +286,14 @@ declare class Gatherer$1 {
     private kb;
     private eventBus;
     private inferenceClient;
+    /** Settle bound for the resource-gather barrier — operator-owned config (D5), threaded from `MakeMeaningConfig.gather`. */
+    private settleTimeoutMs;
     private embeddingProvider?;
     private subscriptions;
     private readonly logger;
-    constructor(kb: KnowledgeBase, eventBus: EventBus, inferenceClient: InferenceClient, logger: Logger, embeddingProvider?: EmbeddingProvider | undefined);
+    constructor(kb: KnowledgeBase, eventBus: EventBus, inferenceClient: InferenceClient, 
+    /** Settle bound for the resource-gather barrier — operator-owned config (D5), threaded from `MakeMeaningConfig.gather`. */
+    settleTimeoutMs: number, logger: Logger, embeddingProvider?: EmbeddingProvider | undefined);
     initialize(): Promise<void>;
     private handleAnnotationGather;
     private handleResourceGather;
@@ -1378,20 +1392,6 @@ declare class AnnotationContext {
 
 type KnowledgeGraph = components['schemas']['KnowledgeGraph'];
 declare class GraphContext {
-    /**
-     * Backoff schedule for the projection-lag grace in `buildKnowledgeGraph`
-     * (GRAPH-PROJECTION-SYNC P1). Total wait is bounded at 375 ms — the Weaver
-     * applies in tens of milliseconds when merely lagging; anything slower is
-     * treated as a real miss.
-     */
-    private static readonly PROJECTION_LAG_BACKOFF_MS;
-    /**
-     * Bounded wait for the applied-offset barrier (GRAPH-PROJECTION-SYNC P2).
-     * The Weaver applies in tens of milliseconds when merely lagging; a
-     * barrier that hasn't woken in 500 ms means signals have stalled and the
-     * poll floor above owns the remainder.
-     */
-    private static readonly PROJECTION_BARRIER_TIMEOUT_MS;
     /**
      * Get all resources referencing this resource (backlinks)
      * Requires graph traversal - must use graph database
@@ -1426,7 +1426,9 @@ declare class GraphContext {
      *  - annotations on the resource → `annotation` nodes + `annotation-of` edges,
      *    so siblingEntityTypes = union of those nodes' entityTypes
      */
-    static buildKnowledgeGraph(resourceId: ResourceId, kb: KnowledgeBase): Promise<KnowledgeGraph>;
+    static buildKnowledgeGraph(resourceId: ResourceId, kb: KnowledgeBase, 
+    /** Breadcrumb sink for the projection-lag degrade path; the degrade counter fires regardless. */
+    logger?: Logger): Promise<KnowledgeGraph>;
 }
 
 /**
@@ -1452,7 +1454,16 @@ declare class LLMContext {
      * Get comprehensive LLM context for a resource
      * Includes: main resource, related resources, annotations, graph, content, summary, references
      */
-    static getResourceContext(resourceId: ResourceId, options: LLMContextOptions, kb: KnowledgeBase, inferenceClient: InferenceClient, logger: Logger): Promise<GatheredContext>;
+    static getResourceContext(resourceId: ResourceId, options: LLMContextOptions, kb: KnowledgeBase, inferenceClient: InferenceClient, 
+    /**
+     * Bound on the semanticContext read-your-writes barrier
+     * (SMELTER-INDEX-SYNC D3/D5). Operator-owned deployment policy: born in
+     * `[environments.<env>.make-meaning.gather] settleTimeoutMs` (the TOML
+     * loader holds the ONE default, 15s), threaded here as a plain argument
+     * via `MakeMeaningConfig.gather` → Gatherer. Must nest inside downstream
+     * watchdogs (A4) — e.g. my-chat's 90s generation stall watchdog.
+     */
+    settleTimeoutMs: number, logger: Logger): Promise<GatheredContext>;
 }
 
 /**

package/dist/index.js

@@ -1,7 +1,7 @@
-import { FsJobQueue } from '@semiont/jobs';
+import { STALL_THRESHOLD_MS, 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, softwareToAgent } from '@semiont/core';
-import { withActorSpan, recordBusEmit, withSpan, SpanKind, registerJobQueueProvider, registerVectorIndexSizeProvider } from '@semiont/observability';
+import { getResourceEntityTypes, getResourceId, getTargetSource, resourceId, getPrimaryRepresentation, decodeRepresentation, 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, softwareToAgent } from '@semiont/core';
+import { recordGatherDegrade, withActorSpan, recordBusEmit, withSpan, SpanKind, registerJobQueueProvider, registerVectorIndexSizeProvider } from '@semiont/observability';
 import { createInferenceClient } from '@semiont/inference';
 import { getGraphDatabase } from '@semiont/graph';
 import { WorkingTreeStore, deriveStorageUri, calculateChecksum } from '@semiont/content';
@@ -9908,6 +9908,131 @@ async function createKnowledgeBase(eventStore, project, graphDb, eventBus, logge
   }
   return kb;
 }
+var PROJECTION_LAG_BACKOFF_MS = [25, 50, 100, 200];
+var PROJECTION_BARRIER_TIMEOUT_MS = 500;
+var GRAPH_BARRIER_BUDGET_MS = PROJECTION_BARRIER_TIMEOUT_MS + PROJECTION_LAG_BACKOFF_MS.reduce((a, b) => a + b, 0);
+var GraphContext = class {
+  /**
+   * Get all resources referencing this resource (backlinks)
+   * Requires graph traversal - must use graph database
+   */
+  static async getBacklinks(resourceId10, kb) {
+    return kb.graph.getResourceReferencedBy(resourceId10);
+  }
+  /**
+   * Find shortest path between two resources
+   * Requires graph traversal - must use graph database
+   */
+  static async findPath(fromResourceId, toResourceId, kb, maxDepth) {
+    return kb.graph.findPath(fromResourceId, toResourceId, maxDepth);
+  }
+  /**
+   * Get resource connections (graph edges)
+   * Requires graph traversal - must use graph database
+   */
+  static async getResourceConnections(resourceId10, kb) {
+    return kb.graph.getResourceConnections(resourceId10);
+  }
+  /**
+   * Search resources by name (cross-resource query)
+   * Requires full-text search - must use graph database
+   */
+  static async searchResources(query, kb, limit) {
+    return kb.graph.searchResources(query, limit);
+  }
+  /**
+   * Build the unified knowledge graph for a resource's neighborhood:
+   * resources AND annotations as typed nodes, typed/directional edges.
+   *
+   * This is the single graph builder (CONTEXT-UNIFICATION D3) — both the
+   * matcher (ranking) and the resource/viz path consume it. The flattened
+   * signals the matcher reads today (`connections`, `citedBy`/count,
+   * `siblingEntityTypes`, `bidirectional`) are all derivable from this:
+   *  - peer connections → resource nodes + main→peer edges carrying `bidirectional`
+   *  - inbound citations → citing-resource nodes + `citation` edges (citing→main),
+   *    so citedByCount = inbound citation-edge count
+   *  - annotations on the resource → `annotation` nodes + `annotation-of` edges,
+   *    so siblingEntityTypes = union of those nodes' entityTypes
+   */
+  static async buildKnowledgeGraph(resourceId10, kb, logger) {
+    let mainDoc = await kb.graph.getResource(resourceId10);
+    if (!mainDoc) {
+      const view = await kb.views.get(resourceId10);
+      if (view) {
+        if (view.lastSequence !== void 0) {
+          try {
+            await kb.weaveProgress.whenApplied(
+              String(resourceId10),
+              view.lastSequence,
+              PROJECTION_BARRIER_TIMEOUT_MS
+            );
+            mainDoc = await kb.graph.getResource(resourceId10);
+          } catch (error) {
+            if (!(error instanceof WeaveProgressTimeout)) throw error;
+          }
+        }
+        if (!mainDoc) {
+          for (const delayMs of PROJECTION_LAG_BACKOFF_MS) {
+            await new Promise((resolve2) => setTimeout(resolve2, delayMs));
+            mainDoc = await kb.graph.getResource(resourceId10);
+            if (mainDoc) break;
+          }
+        }
+        if (!mainDoc) {
+          recordGatherDegrade("graph");
+          logger?.warn("[gather DEGRADED] graph projection did not catch up \u2014 resource present in views, absent in graph", {
+            resourceId: String(resourceId10),
+            lastSequence: view.lastSequence,
+            barrierTimeoutMs: PROJECTION_BARRIER_TIMEOUT_MS
+          });
+          throw new Error(
+            `Graph projection did not catch up for ${String(resourceId10)} \u2014 present in views, absent in graph (Weaver lag, not a missing resource)`
+          );
+        }
+      }
+    }
+    if (!mainDoc) {
+      throw new Error("Resource not found");
+    }
+    const mainId = String(resourceId10);
+    const [connections, referencedBy, annotations] = await Promise.all([
+      kb.graph.getResourceConnections(resourceId10),
+      kb.graph.getResourceReferencedBy(resourceId10),
+      kb.graph.getResourceAnnotations(resourceId10)
+    ]);
+    const nodes = [];
+    const edges = [];
+    const seen = /* @__PURE__ */ new Set();
+    const addResourceNode = (id, label, entityTypes) => {
+      if (!id || seen.has(id)) return;
+      nodes.push({ id, type: "resource", label, entityTypes });
+      seen.add(id);
+    };
+    addResourceNode(mainId, mainDoc.name, getResourceEntityTypes(mainDoc));
+    for (const conn of connections) {
+      const peerId = getResourceId(conn.targetResource);
+      if (!peerId) continue;
+      addResourceNode(peerId, conn.targetResource.name, getResourceEntityTypes(conn.targetResource));
+      edges.push({ source: mainId, target: peerId, type: conn.relationshipType || "link", bidirectional: conn.bidirectional });
+    }
+    const citedSeen = /* @__PURE__ */ new Set();
+    for (const ann of referencedBy) {
+      const source = getTargetSource(ann.target);
+      if (!source || source === String(resourceId10) || citedSeen.has(source)) continue;
+      citedSeen.add(source);
+      const view = await kb.views.get(resourceId(source));
+      addResourceNode(source, view?.resource?.name ?? source, view?.resource ? getResourceEntityTypes(view.resource) : []);
+      edges.push({ source, target: mainId, type: "citation" });
+    }
+    for (const ann of annotations) {
+      if (!ann.id || seen.has(ann.id)) continue;
+      nodes.push({ id: ann.id, type: "annotation", label: ann.motivation ?? "annotation", entityTypes: getEntityTypes(ann) });
+      seen.add(ann.id);
+      edges.push({ source: ann.id, target: mainId, type: "annotation-of" });
+    }
+    return { nodes, edges };
+  }
+};
 
 // src/gatherer.ts
 var import_rxjs = __toESM(require_cjs());
@@ -10014,130 +10139,6 @@ var ResourceContext = class _ResourceContext {
     return void 0;
   }
 };
-var GraphContext = class _GraphContext {
-  /**
-   * Backoff schedule for the projection-lag grace in `buildKnowledgeGraph`
-   * (GRAPH-PROJECTION-SYNC P1). Total wait is bounded at 375 ms — the Weaver
-   * applies in tens of milliseconds when merely lagging; anything slower is
-   * treated as a real miss.
-   */
-  static PROJECTION_LAG_BACKOFF_MS = [25, 50, 100, 200];
-  /**
-   * Bounded wait for the applied-offset barrier (GRAPH-PROJECTION-SYNC P2).
-   * The Weaver applies in tens of milliseconds when merely lagging; a
-   * barrier that hasn't woken in 500 ms means signals have stalled and the
-   * poll floor above owns the remainder.
-   */
-  static PROJECTION_BARRIER_TIMEOUT_MS = 500;
-  /**
-   * Get all resources referencing this resource (backlinks)
-   * Requires graph traversal - must use graph database
-   */
-  static async getBacklinks(resourceId10, kb) {
-    return kb.graph.getResourceReferencedBy(resourceId10);
-  }
-  /**
-   * Find shortest path between two resources
-   * Requires graph traversal - must use graph database
-   */
-  static async findPath(fromResourceId, toResourceId, kb, maxDepth) {
-    return kb.graph.findPath(fromResourceId, toResourceId, maxDepth);
-  }
-  /**
-   * Get resource connections (graph edges)
-   * Requires graph traversal - must use graph database
-   */
-  static async getResourceConnections(resourceId10, kb) {
-    return kb.graph.getResourceConnections(resourceId10);
-  }
-  /**
-   * Search resources by name (cross-resource query)
-   * Requires full-text search - must use graph database
-   */
-  static async searchResources(query, kb, limit) {
-    return kb.graph.searchResources(query, limit);
-  }
-  /**
-   * Build the unified knowledge graph for a resource's neighborhood:
-   * resources AND annotations as typed nodes, typed/directional edges.
-   *
-   * This is the single graph builder (CONTEXT-UNIFICATION D3) — both the
-   * matcher (ranking) and the resource/viz path consume it. The flattened
-   * signals the matcher reads today (`connections`, `citedBy`/count,
-   * `siblingEntityTypes`, `bidirectional`) are all derivable from this:
-   *  - peer connections → resource nodes + main→peer edges carrying `bidirectional`
-   *  - inbound citations → citing-resource nodes + `citation` edges (citing→main),
-   *    so citedByCount = inbound citation-edge count
-   *  - annotations on the resource → `annotation` nodes + `annotation-of` edges,
-   *    so siblingEntityTypes = union of those nodes' entityTypes
-   */
-  static async buildKnowledgeGraph(resourceId10, kb) {
-    let mainDoc = await kb.graph.getResource(resourceId10);
-    if (!mainDoc) {
-      const view = await kb.views.get(resourceId10);
-      if (view) {
-        if (view.lastSequence !== void 0) {
-          try {
-            await kb.weaveProgress.whenApplied(
-              String(resourceId10),
-              view.lastSequence,
-              _GraphContext.PROJECTION_BARRIER_TIMEOUT_MS
-            );
-            mainDoc = await kb.graph.getResource(resourceId10);
-          } catch {
-          }
-        }
-        if (!mainDoc) {
-          for (const delayMs of _GraphContext.PROJECTION_LAG_BACKOFF_MS) {
-            await new Promise((resolve2) => setTimeout(resolve2, delayMs));
-            mainDoc = await kb.graph.getResource(resourceId10);
-            if (mainDoc) break;
-          }
-        }
-      }
-    }
-    if (!mainDoc) {
-      throw new Error("Resource not found");
-    }
-    const mainId = String(resourceId10);
-    const [connections, referencedBy, annotations] = await Promise.all([
-      kb.graph.getResourceConnections(resourceId10),
-      kb.graph.getResourceReferencedBy(resourceId10),
-      kb.graph.getResourceAnnotations(resourceId10)
-    ]);
-    const nodes = [];
-    const edges = [];
-    const seen = /* @__PURE__ */ new Set();
-    const addResourceNode = (id, label, entityTypes) => {
-      if (!id || seen.has(id)) return;
-      nodes.push({ id, type: "resource", label, entityTypes });
-      seen.add(id);
-    };
-    addResourceNode(mainId, mainDoc.name, getResourceEntityTypes(mainDoc));
-    for (const conn of connections) {
-      const peerId = getResourceId(conn.targetResource);
-      if (!peerId) continue;
-      addResourceNode(peerId, conn.targetResource.name, getResourceEntityTypes(conn.targetResource));
-      edges.push({ source: mainId, target: peerId, type: conn.relationshipType || "link", bidirectional: conn.bidirectional });
-    }
-    const citedSeen = /* @__PURE__ */ new Set();
-    for (const ann of referencedBy) {
-      const source = getTargetSource(ann.target);
-      if (!source || source === String(resourceId10) || citedSeen.has(source)) continue;
-      citedSeen.add(source);
-      const view = await kb.views.get(resourceId(source));
-      addResourceNode(source, view?.resource?.name ?? source, view?.resource ? getResourceEntityTypes(view.resource) : []);
-      edges.push({ source, target: mainId, type: "citation" });
-    }
-    for (const ann of annotations) {
-      if (!ann.id || seen.has(ann.id)) continue;
-      nodes.push({ id: ann.id, type: "annotation", label: ann.motivation ?? "annotation", entityTypes: getEntityTypes(ann) });
-      seen.add(ann.id);
-      edges.push({ source: ann.id, target: mainId, type: "annotation-of" });
-    }
-    return { nodes, edges };
-  }
-};
 
 // src/annotation-context.ts
 var AnnotationContext = class {
@@ -10252,7 +10253,7 @@ var AnnotationContext = class {
       }
     }
     logger?.debug("Building knowledge graph", { resourceId: resourceId10 });
-    const graph = await GraphContext.buildKnowledgeGraph(resourceId10, kb);
+    const graph = await GraphContext.buildKnowledgeGraph(resourceId10, kb, logger);
     const views = deriveViews(graph, String(resourceId10), annotationId5);
     const entityTypeStats = await kb.graph.getEntityTypeStats();
     const entityTypeFrequencies = {};
@@ -10561,19 +10562,18 @@ Entity types: ${entityTypes.join(", ")}`;
     return inferenceClient.generateText(summaryPrompt, 500, 0.5);
   }
 };
-var SMELT_SETTLE_TIMEOUT_MS = 15e3;
 var LLMContext = class {
   /**
    * Get comprehensive LLM context for a resource
    * Includes: main resource, related resources, annotations, graph, content, summary, references
    */
-  static async getResourceContext(resourceId10, options, kb, inferenceClient, logger) {
+  static async getResourceContext(resourceId10, options, kb, inferenceClient, settleTimeoutMs, logger) {
     const mainDoc = await ResourceContext.getResourceMetadata(resourceId10, kb);
     if (!mainDoc) {
       throw new Error("Resource not found");
     }
     const mainContent = options.includeContent ? await ResourceContext.getResourceContent(mainDoc, kb) : void 0;
-    const graph = await GraphContext.buildKnowledgeGraph(resourceId10, kb);
+    const graph = await GraphContext.buildKnowledgeGraph(resourceId10, kb, logger);
     const resourceIdStr = resourceId10.toString();
     const relatedDocs = [];
     const relatedNodes = graph.nodes.filter((node) => node.type === "resource" && node.id !== resourceIdStr).slice(0, Math.max(0, options.maxResources - 1));
@@ -10620,16 +10620,17 @@ var LLMContext = class {
         const contentChecksum = getPrimaryRepresentation(mainDoc)?.checksum;
         if (contentChecksum) {
           try {
-            const outcome = await kb.smeltProgress.whenSettled(resourceIdStr, contentChecksum, SMELT_SETTLE_TIMEOUT_MS);
+            const outcome = await kb.smeltProgress.whenSettled(resourceIdStr, contentChecksum, settleTimeoutMs);
             if (outcome === "indexed") {
               matches = await search();
             }
           } catch (error) {
             if (!(error instanceof SmeltProgressTimeout)) throw error;
+            recordGatherDegrade("vectors");
             logger.warn("[gather DEGRADED] semanticContext absent \u2014 the vector projection did not settle within the barrier", {
               resourceId: resourceIdStr,
               contentChecksum,
-              timeoutMs: SMELT_SETTLE_TIMEOUT_MS
+              timeoutMs: settleTimeoutMs
             });
           }
         }
@@ -10667,16 +10668,18 @@ var LLMContext = class {
 
 // src/gatherer.ts
 var Gatherer = class {
-  constructor(kb, eventBus, inferenceClient, logger, embeddingProvider) {
+  constructor(kb, eventBus, inferenceClient, settleTimeoutMs, logger, embeddingProvider) {
     this.kb = kb;
     this.eventBus = eventBus;
     this.inferenceClient = inferenceClient;
+    this.settleTimeoutMs = settleTimeoutMs;
     this.embeddingProvider = embeddingProvider;
     this.logger = logger;
   }
   kb;
   eventBus;
   inferenceClient;
+  settleTimeoutMs;
   embeddingProvider;
   subscriptions = [];
   logger;
@@ -10753,6 +10756,7 @@ var Gatherer = class {
         event.options,
         this.kb,
         this.inferenceClient,
+        this.settleTimeoutMs,
         this.logger
       );
       this.eventBus.get("gather:resource-complete").next({
@@ -12837,6 +12841,7 @@ async function createKnowledgeSystemFromConfig(project, config, eventBus, logger
     kb,
     eventBus,
     createInferenceClient(resolveActorInference(config, "gatherer"), logger.child({ component: "inference-client-gatherer" })),
+    config.gather.settleTimeoutMs,
     logger.child({ component: "gatherer" }),
     embeddingProvider
   );
@@ -12860,6 +12865,14 @@ async function startMakeMeaning(project, config, eventBus, logger, options) {
   if (!config.services?.graph) {
     throw new Error("services.graph is required for make-meaning service");
   }
+  if (!Number.isFinite(config.gather.settleTimeoutMs) || config.gather.settleTimeoutMs <= 0) {
+    throw new Error(`gather.settleTimeoutMs must be a positive number of milliseconds, got ${config.gather.settleTimeoutMs}`);
+  }
+  if (config.gather.settleTimeoutMs + GRAPH_BARRIER_BUDGET_MS >= STALL_THRESHOLD_MS) {
+    throw new Error(
+      `gather.settleTimeoutMs (${config.gather.settleTimeoutMs}ms) plus the graph barrier budget (${GRAPH_BARRIER_BUDGET_MS}ms) must nest inside the job-worker stall watchdog (${STALL_THRESHOLD_MS}ms) \u2014 lower settleTimeoutMs (A4)`
+    );
+  }
   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);