@semiont/make-meaning 0.5.26 → 0.5.27

package/README.md

@@ -187,7 +187,7 @@ The EventBus is created by the backend (or script) and passed into `startMakeMea
 
 ### 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.
+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.fromContext` 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):
 

package/dist/index.d.ts

@@ -54,10 +54,26 @@ interface MakeMeaningConfig {
     gather: {
         settleTimeoutMs: number;
     };
+    /**
+     * Search policy. `semanticFloor` is the minimum cosine score a vector hit
+     * needs to appear in the semantic fallback (SEMANTIC-FALLBACK decision #1)
+     * — REQUIRED: the TOML loader owns the one default (0.6 at
+     * `[environments.<env>.make-meaning.search]`); hand-built configs
+     * (scripts, tests) state their policy explicitly.
+     */
+    search: {
+        semanticFloor: number;
+    };
     services: {
         graph?: GraphServiceConfig;
-        vectors?: VectorsServiceConfig;
-        embedding?: EmbeddingServiceConfig;
+        /** REQUIRED (MANDATORY-EMBEDDING D0+D1, type-level per the 2026-08-12
+         *  ruling): the config NAMES its store — `memory` is a first-class
+         *  explicit choice, never a fallback. The TOML loader refuses configs
+         *  without it; the type makes hand-built configs state their choice. */
+        vectors: VectorsServiceConfig;
+        /** REQUIRED (same ruling): the embedding provider is the KB's semantic
+         *  identity — always named, never detected or defaulted. */
+        embedding: EmbeddingServiceConfig;
     };
     /**
      * The KB's canonical identity domain — the SAME value `/api/tokens/agent`
@@ -181,14 +197,17 @@ interface KnowledgeBase {
     graph: GraphDatabase;
     weaveProgress: WeaveProgress;
     smeltProgress: SmeltProgress;
-    vectors?: VectorStore;
+    vectors: VectorStore;
     projectionsDir: string;
 }
 interface CreateKnowledgeBaseOptions {
-    vectorStore?: VectorStore;
+    /** Required (MANDATORY-EMBEDDING D0): a KB without vector search is not a
+     *  configuration we support; `MemoryVectorStore` is the explicit named
+     *  choice for stores that may rebuild on restart. */
+    vectorStore: VectorStore;
     skipRebuild?: boolean;
 }
-declare function createKnowledgeBase(eventStore: EventStore, project: SemiontProject, graphDb: GraphDatabase, eventBus: EventBus, logger: Logger, options?: CreateKnowledgeBaseOptions): Promise<KnowledgeBase>;
+declare function createKnowledgeBase(eventStore: EventStore, project: SemiontProject, graphDb: GraphDatabase, eventBus: EventBus, logger: Logger, options: CreateKnowledgeBaseOptions): Promise<KnowledgeBase>;
 
 /**
  * Stower Actor
@@ -290,12 +309,12 @@ declare class Gatherer$1 {
     private inferenceClient;
     /** Settle bound for the resource-gather barrier — operator-owned config (D5), threaded from `MakeMeaningConfig.gather`. */
     private settleTimeoutMs;
-    private embeddingProvider?;
+    private embeddingProvider;
     private subscriptions;
     private readonly logger;
     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);
+    settleTimeoutMs: number, logger: Logger, embeddingProvider: EmbeddingProvider);
     initialize(): Promise<void>;
     private handleAnnotationGather;
     private handleResourceGather;
@@ -320,10 +339,10 @@ declare class Matcher {
     private kb;
     private eventBus;
     private inferenceClient;
-    private embeddingProvider?;
+    private embeddingProvider;
     private subscriptions;
     private readonly logger;
-    constructor(kb: KnowledgeBase, eventBus: EventBus, logger: Logger, inferenceClient: InferenceClient, embeddingProvider?: EmbeddingProvider | undefined);
+    constructor(kb: KnowledgeBase, eventBus: EventBus, logger: Logger, inferenceClient: InferenceClient, embeddingProvider: EmbeddingProvider);
     initialize(): Promise<void>;
     private handleSearch;
     /**
@@ -364,6 +383,31 @@ declare class Matcher {
     stop(): Promise<void>;
 }
 
+/**
+ * LimitsDiscovery — the Browser's discovery pool for per-`(provider, model)`
+ * inference ceilings (INFERENCE-LIMITS-EXPOSURE P2).
+ *
+ * D1: the ONLY storage is in-memory — the pool's client instances, whose
+ * `limits()` single-flights and caches success internally, and deliberately
+ * clears its promise on failure so a briefly-down provider recovers on a
+ * later request (absent → present, no restart needed).
+ *
+ * D3: enrichment must never fail or block the directory reply. Three guards
+ * carry that, each pinned in `limits-discovery.test.ts`:
+ *  - construction is guarded per pair — a throwing factory (e.g. an
+ *    Anthropic section whose apiKey is left to worker-process env
+ *    expansion) is a discovery failure, never a Browser startup failure;
+ *  - every consult is raced against `LIMITS_ENRICH_BUDGET_MS`;
+ *  - every failure path yields the entry WITHOUT `limits` — the same
+ *    absence semantics `servesJobTypes` already has.
+ */
+
+type CollaboratorEntry = components['schemas']['CollaboratorEntry'];
+interface LimitsDiscovery {
+    /** The entries, each with `limits` attached where discovery answered within budget. */
+    enrich(entries: CollaboratorEntry[]): Promise<CollaboratorEntry[]>;
+}
+
 /**
  * Browser Actor
  *
@@ -391,9 +435,17 @@ declare class Browser {
     private eventBus;
     private project;
     private config;
+    /** Discovered per-(provider, model) ceilings for the roster (INFERENCE-LIMITS-EXPOSURE P2). */
+    private limitsDiscovery;
+    /** For the semantic search fallback — mandatory (MANDATORY-EMBEDDING D0). */
+    private embeddingProvider;
     private subscriptions;
     private readonly logger;
-    constructor(views: ViewStorage, kb: KnowledgeBase, eventBus: EventBus, project: SemiontProject, config: MakeMeaningConfig, logger: Logger);
+    constructor(views: ViewStorage, kb: KnowledgeBase, eventBus: EventBus, project: SemiontProject, config: MakeMeaningConfig, 
+    /** Discovered per-(provider, model) ceilings for the roster (INFERENCE-LIMITS-EXPOSURE P2). */
+    limitsDiscovery: LimitsDiscovery, 
+    /** For the semantic search fallback — mandatory (MANDATORY-EMBEDDING D0). */
+    embeddingProvider: EmbeddingProvider, logger: Logger);
     initialize(): Promise<void>;
     /**
      * Serve a resource's derived coordinate map (ANCHORED-TEXT-CACHE Lane 5).
@@ -580,7 +632,7 @@ declare class LocalTransport implements ITransport {
     private readonly bridgeSubs;
     private disposed;
     constructor(cfg: LocalTransportConfig);
-    emit<K extends keyof EventMap>(channel: K, payload: EventMap[K], resourceScope?: ResourceId): Promise<void>;
+    emit<K extends keyof EventMap>(channel: K, payload: EventMap[K], resourceScope?: ResourceId): Promise<number>;
     on<K extends keyof EventMap>(channel: K, handler: (payload: EventMap[K]) => void): () => void;
     stream<K extends keyof EventMap>(channel: K): Observable<EventMap[K]>;
     subscribeToResource(_resourceId: ResourceId): () => void;
@@ -1380,8 +1432,11 @@ declare class AnnotationOperations {
 /**
  * Resource Context
  *
- * Assembles resource context from view storage and content store
- * Does NOT touch the graph - graph queries go through GraphContext
+ * Assembles resource context from view storage and content store.
+ * Graph queries go through GraphContext — with one deliberate exception:
+ * `listResources`' search path runs inside the graph engine, and its
+ * semantic fallback (SEMANTIC-FALLBACK) reads the vector index. Both are
+ * single-index reads; anything that FUSES sources belongs to the Matcher.
  */
 
 interface ListResourcesFilters {
@@ -1392,9 +1447,35 @@ interface ListResourcesFilters {
     limit?: number;
 }
 interface ListResourcesResult {
-    resources: ResourceDescriptor[];
+    /** Semantic hits carry `content` — the passage that matched, not a preview. */
+    resources: Array<ResourceDescriptor & {
+        content?: string;
+    }>;
     /** Size of the whole match set, not of the returned page. */
     total: number;
+    /**
+     * Which kind of answer this is (SEMANTIC-FALLBACK): 'lexical' for the
+     * graph/view paths (including an honestly-empty page), 'semantic' when an
+     * empty lexical search was answered from the vector index. REQUIRED — an
+     * optional discriminator defaulting to lexical would let a missing value
+     * silently read as lexical.
+     */
+    matchKind: 'lexical' | 'semantic';
+}
+/**
+ * What the semantic fallback needs, passed as plain arguments (the
+ * buildContext idiom — providers are parameters, not fields). Both the
+ * provider and `kb.vectors` are mandatory (MANDATORY-EMBEDDING D0; the old
+ * unconfigured branches — SEMANTIC-FALLBACK S3/S4 — were deliberately
+ * retired with that change). What still degrades is FAILURE: a throwing
+ * embed yields the empty lexical page (S5), because mandatory does not
+ * mean always up.
+ */
+interface SemanticFallbackDeps {
+    embeddingProvider: EmbeddingProvider;
+    /** Minimum cosine score for a hit to appear — `search.semanticFloor`. */
+    semanticFloor: number;
+    logger: Logger;
 }
 declare class ResourceContext {
     /**
@@ -1415,7 +1496,23 @@ declare class ResourceContext {
      * barrier-stamped projection, so an unsearched listing is read-your-writes
      * where the graph is only eventually consistent.
      */
-    static listResources(filters: ListResourcesFilters | undefined, kb: KnowledgeBase): Promise<ListResourcesResult>;
+    static listResources(filters: ListResourcesFilters | undefined, kb: KnowledgeBase, semantic: SemanticFallbackDeps): Promise<ListResourcesResult>;
+    /**
+     * Answer an empty lexical search from the vector index (SEMANTIC-FALLBACK):
+     * embed the query once, fold chunk hits per resource, floor them, and label
+     * the answer 'semantic' so the UI can say "no title matches, but these
+     * documents discuss it".
+     *
+     * Degradation is the contract (axioms S3–S5): unconfigured vectors, an
+     * absent provider, or ANY failure inside the fallback yields the same
+     * empty page the caller already had, labelled 'lexical' — a broken
+     * fallback must never turn a working empty search into an error.
+     *
+     * The floor is applied HERE rather than passed as `scoreThreshold`, so the
+     * below-floor hits exist to be counted — the debug line is the evidence
+     * decision #1's guessed 0.6 gets tuned from.
+     */
+    private static semanticFallback;
     /**
      * Add content previews to resources (for search results)
      * Retrieves and decodes the first 200 characters of each resource's primary representation
@@ -1460,7 +1557,7 @@ declare class AnnotationContext {
      * @returns Rich context for LLM processing
      * @throws Error if annotation or resource not found
      */
-    static buildLLMContext(annotationId: AnnotationId, resourceId: ResourceId, kb: KnowledgeBase, options?: BuildContextOptions, inferenceClient?: InferenceClient, logger?: Logger, embeddingProvider?: EmbeddingProvider): Promise<GatheredContext>;
+    static buildLLMContext(annotationId: AnnotationId, resourceId: ResourceId, kb: KnowledgeBase, embeddingProvider: EmbeddingProvider, options?: BuildContextOptions, inferenceClient?: InferenceClient, logger?: Logger): Promise<GatheredContext>;
     /**
      * Get resource annotations from view storage (fast path)
      * Throws if view missing