@semiont/make-meaning 0.5.25 → 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,17 +339,17 @@ 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;
     /**
      * Context-driven search: multi-source retrieval + composite scoring
      *
      * Retrieval sources:
-     * 1. Name match — graph.searchResources(searchTerm)
+     * 1. Name match — graph.listResources({ search: searchTerm })
      * 2. Entity type match — graph.listResources({ entityTypes })
      * 3. Graph neighborhood — connections from GatheredContext
      *
@@ -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,13 +1432,50 @@ 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 {
     search?: string;
     archived?: boolean;
+    entityType?: string;
+    offset?: number;
+    limit?: number;
+}
+interface ListResourcesResult {
+    /** 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 {
     /**
@@ -1394,17 +1483,36 @@ declare class ResourceContext {
      */
     static getResourceMetadata(resourceId: ResourceId, kb: KnowledgeBase): Promise<ResourceDescriptor | null>;
     /**
-     * List resources, optionally filtered.
+     * List resources, optionally filtered, as one page plus the size of the whole
+     * match set. Every filter is applied before pagination on both paths — a
+     * filter applied afterwards narrows the page rather than the match set, which
+     * is how a search scoped to an entity type can come back empty while hundreds
+     * of resources match.
      *
-     * When `search` is set, delegates to `kb.graph.searchResources`, which runs
-     * the name match in the graph engine instead of scanning every view in JS.
-     * The graph result is then narrowed by `archived` if requested.
+     * When `search` is set, the entire query — filtering, ordering and
+     * pagination — runs inside the graph engine.
      *
-     * When `search` is unset, falls back to scanning all materialized views.
-     * (TODO: also push the listing path through the graph for large KBs.)
+     * When `search` is unset, the materialized views answer instead. They are the
+     * 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<ResourceDescriptor[]>;
-    private static sortByDateDesc;
+    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
@@ -1449,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
@@ -1540,11 +1648,6 @@ declare class GraphContext {
      * Requires graph traversal - must use graph database
      */
     static getResourceConnections(resourceId: ResourceId, kb: KnowledgeBase): Promise<GraphConnection[]>;
-    /**
-     * Search resources by name (cross-resource query)
-     * Requires full-text search - must use graph database
-     */
-    static searchResources(query: string, kb: KnowledgeBase, limit?: number): Promise<ResourceDescriptor[]>;
     /**
      * Build the unified knowledge graph for a resource's neighborhood:
      * resources AND annotations as typed nodes, typed/directional edges.
@@ -1620,4 +1723,4 @@ declare function generateResourceSummary(resourceName: string, content: string,
 declare function generateReferenceSuggestions(referenceTitle: string, client: InferenceClient, entityType?: string, currentContent?: string): Promise<string[] | null>;
 
 export { AnnotationContext, AnnotationOperations, BACKUP_FORMAT, Browser, CloneTokenManager, FORMAT_VERSION, Gatherer$1 as Gatherer, GraphContext, LLMContext, LocalContentTransport, LocalTransport, Matcher, ResourceContext, ResourceOperations, Smelter, Stower, asBusRequestPrimitive, bootstrapEntityTypes, createKnowledgeBase, createSmelterActorStateUnit, exportBackup, exportLinkedData, generateReferenceSuggestions, generateResourceSummary, importBackup, importLinkedData, isBackupManifest, readEntityTypesProjection, registerAnnotationAssemblyHandler, registerAnnotationLookupHandlers, registerBindUpdateBodyHandler, registerBusHandlers, registerJobCommandHandlers, startMakeMeaning, stopKnowledgeSystem, validateManifestVersion };
-export type { BackupContentReader, BackupEventStoreReader, BackupExporterOptions, BackupImportResult, BackupImporterOptions, BackupManifestHeader, BackupStreamSummary, BuildContextOptions, ContentBlobResolver, CreateAnnotationResult, CreateResourceInput, CreateResourceResult, KnowledgeBase, KnowledgeSystem, LLMContextOptions, LinkedDataContentReader, LinkedDataExporterOptions, LinkedDataImportResult, LinkedDataImporterOptions, LinkedDataViewReader, ListResourcesFilters, LocalTransportConfig, MakeMeaningConfig, MakeMeaningService, ReconcileState, ReconcileSummary, ReplayStats, SmelterActorStateUnit, SmelterActorStateUnitOptions, SmelterEvent, SmelterInput, SmelterTiming, SmelterWorkItem, UpdateAnnotationBodyResult };
+export type { BackupContentReader, BackupEventStoreReader, BackupExporterOptions, BackupImportResult, BackupImporterOptions, BackupManifestHeader, BackupStreamSummary, BuildContextOptions, ContentBlobResolver, CreateAnnotationResult, CreateResourceInput, CreateResourceResult, KnowledgeBase, KnowledgeSystem, LLMContextOptions, LinkedDataContentReader, LinkedDataExporterOptions, LinkedDataImportResult, LinkedDataImporterOptions, LinkedDataViewReader, ListResourcesFilters, ListResourcesResult, LocalTransportConfig, MakeMeaningConfig, MakeMeaningService, ReconcileState, ReconcileSummary, ReplayStats, SmelterActorStateUnit, SmelterActorStateUnitOptions, SmelterEvent, SmelterInput, SmelterTiming, SmelterWorkItem, UpdateAnnotationBodyResult };