@equationalapplications/core-llm-wiki 6.2.0 → 6.4.0

package/dist/{testing-D0m2V9-E.d.mts → testing-DWpAgNLt.d.mts}

@@ -195,6 +195,16 @@ interface WikiConfig {
     maxChunkLength?: number;
     chunkOverlap?: number;
     chunkConcurrency?: number;
+    /**
+     * Maximum characters of `title + body + tags` passed to `llmProvider.embed()`
+     * when embedding a fact. Longer input is clipped, not rejected.
+     *
+     * Default 6000 (~1,500 tokens), which fits common embedding windows including
+     * nomic-embed-text's 2,048 tokens with headroom. Values above the 16,000
+     * hard ceiling are clamped to it; the ceiling is a security control and
+     * configuration cannot raise it.
+     */
+    maxEmbedChars?: number;
     /**
      * Max MiniSearch candidates passed to cosine scoring.
      * When set, MiniSearch pre-filters before the cosine scan.
@@ -250,6 +260,23 @@ interface ReadOptions {
      * Only meaningful when `entityId` is an array; ignored for single-string calls.
      */
     includeZeroWeightEntities?: boolean;
+    /**
+     * Minimum number of results to retain from each named entity before the global
+     * `maxResults` cut. Applied after scoring: the top-N scored results from each
+     * named entity are reserved, then remaining slots fill by score as usual.
+     *
+     * An entity with fewer than N matching results contributes what it has — this is
+     * not an error. Floors cannot resurrect a result excluded by `preFilterLimit`.
+     *
+     * Only meaningful when `entityId` is an array; ignored for single-string calls.
+     * Ignored when `query` is empty — that path uses recency ordering and ignores
+     * `tierWeights` as well.
+     *
+     * Throws `WikiInvalidReadOptions` when a floor cannot be satisfied by
+     * construction: floors summing above `maxResults`, a floor on an entity excluded
+     * by `tierWeights: 0`, or a floor keyed to an entity not in `entityId`.
+     */
+    tierFloors?: Record<string, number>;
 }
 interface WikiFact {
     id: string;
@@ -588,6 +615,8 @@ interface MemoryBundle {
         query: string;
         entityIds: string[];
         tierWeights?: Record<string, number>;
+        /** Sanitized per-entity result floors, when `tierFloors` was supplied and non-empty. */
+        tierFloors?: Record<string, number>;
     };
 }
 interface MemoryDump {
@@ -787,6 +816,15 @@ declare class WikiIngestEmptyError extends Error {
         chunks: number;
     });
 }
+/**
+ * Thrown by `read()` when `ReadOptions` contains a request that cannot be
+ * satisfied by construction — as opposed to one that merely finds no data.
+ */
+declare class WikiInvalidReadOptions extends Error {
+    readonly field: string;
+    readonly reason: string;
+    constructor(field: string, reason: string);
+}
 
 interface WikiOutboxEvent<T = unknown> {
     id: string;
@@ -1244,10 +1282,23 @@ declare class MetadataRepository extends BaseRepository {
         mode: OntologyMode;
         manifest: OntologyManifest;
     } | null>;
+    /**
+     * Write an entity's manifest.
+     *
+     * `opts.ifAbsent` selects the conflict behaviour:
+     * - omitted / `false` — upsert. An existing row is replaced.
+     * - `true` — create-if-absent. An existing row is left exactly as it is.
+     *
+     * Returns whether this call actually wrote a row. Under `ifAbsent` a `false`
+     * result means another writer got there first; the check and the write are one
+     * statement, so there is no window between them.
+     */
     setManifest(entityId: string, data: {
         mode: OntologyMode;
         manifest: OntologyManifest;
-    }, tx: SQLiteAdapter): Promise<void>;
+    }, tx: SQLiteAdapter, opts?: {
+        ifAbsent?: boolean;
+    }): Promise<boolean>;
     mergeManifestUpdates(entityId: string, updates: OntologyUpdates, tx: SQLiteAdapter): Promise<OntologyManifest>;
 }
 
@@ -2339,10 +2390,44 @@ declare class WikiMemory {
      * Seeds or replaces an entity's ontology manifest and optional mode override.
      * Validates manifest invariants (unique type slugs, edge endpoints reference node types).
      * Invalidates the in-memory ontology cache for this entity.
+     *
+     * Delegates to `setOntologyManifests` so there is a single write path. The
+     * observable contract is unchanged: same upsert semantics, same cache
+     * invalidation, same `void` result.
      */
     setOntologyManifest(entityId: string, manifest: OntologyManifest, options?: {
         mode?: OntologyMode;
     }): Promise<void>;
+    /**
+     * Write several entities' ontology manifests in a single transaction.
+     *
+     * All succeed or none do. The transaction is opened on this instance's
+     * serialized adapter — callers pass data, never a transaction handle, because
+     * a consumer holds the unwrapped adapter and a transaction opened on it would
+     * bypass the serialization mutex applied in the constructor.
+     *
+     * Returns which entities were written. `skipped` is only ever non-empty under
+     * `opts.ifAbsent`.
+     *
+     * Sharp edge: `ifAbsent` checks for a PERSISTED row, not for an effective
+     * manifest. An entity whose manifest currently comes from
+     * `WikiConfig.ontology.seedManifests` has no row until the seed is
+     * materialized on first access that supplies a transaction (in practice, an
+     * ingest). Until then `ifAbsent` treats the entity as absent, writes the new
+     * manifest over the configured seed, and reports it in `written`; the same
+     * call after the seed has been materialized reports it in `skipped`. See the
+     * `ifAbsent` notes in the package README.
+     */
+    setOntologyManifests(entries: Array<{
+        entityId: string;
+        manifest: OntologyManifest;
+        mode?: OntologyMode;
+    }>, opts?: {
+        ifAbsent?: boolean;
+    }): Promise<{
+        written: string[];
+        skipped: string[];
+    }>;
     /** Append a verification event to a fact. Does NOT touch `updated_at`. */
     writeOkfTrust(entryId: string, entityId: string, verified: {
         by: string;
@@ -2373,4 +2458,4 @@ declare class WikiMemory {
     setGeneratedByTask(taskId: string, entityId: string, actor: string): Promise<void>;
 }
 
-export { WikiSourceRefHashCollision as $, WikiBusyError as A, type WikiBusyOperation as B, type ChunkFailure as C, type DegradedRecord as D, type EntityStatus as E, type FormatContextOptions as F, type GraphNeighborhood as G, HEAL_BATCH_SIZE as H, type IngestDocumentResult as I, type WikiCheckpoint as J, type WikiConfig as K, type LLMProvider as L, type MemoryBundle as M, WikiDuplicateHashError as N, type OntologyManifest as O, type PromptOverrides as P, type WikiEdge as Q, type ReadOptions as R, type SQLiteAdapter as S, type WikiEvent as T, type WikiFact as U, type VectorRanker as V, type WikiOptions as W, WikiIngestEmptyError as X, type WikiMemoryTestAccess as Y, type WikiOutboxEvent as Z, WikiParseError as _, type MemoryDump as a, WikiStrictOntologyViolation as a0, type WikiTask as a1, WikiTransactionError as a2, EmbeddingService as a3, ImportExportService as a4, IngestionService as a5, JobManager as a6, MaintenanceService as a7, RetrievalService as a8, SearchService as a9, WriteService as aa, type FormattedMemoryDump as b, WikiMemory as c, type ExtractedFact as d, type ExtractedFactEdge as e, type ExtractedFactWithOntology as f, type ExtractedTask as g, type GraphTraversalOptions as h, HEAL_RECHECK_MS as i, HOOK_TIMEOUT_MARKER as j, type HealResult as k, ONTOLOGY_BACKFILL_BATCH_SIZE as l, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS as m, ONTOLOGY_BACKFILL_RECHECK_MS as n, type OntologyBackfillResult as o, type OntologyConfig as p, type OntologyEdgeType as q, type OntologyMode as r, type OntologyNodeType as s, type OntologyPromptContext as t, type OntologyUpdates as u, PromptService as v, PrunePartialFailureError as w, type VectorRankerFallback as x, type VectorRankerRankArgs as y, type VectorRankerSemanticResult as z };
+export { WikiParseError as $, WikiBusyError as A, type WikiBusyOperation as B, type ChunkFailure as C, type DegradedRecord as D, type EntityStatus as E, type FormatContextOptions as F, type GraphNeighborhood as G, HEAL_BATCH_SIZE as H, type IngestDocumentResult as I, type WikiCheckpoint as J, type WikiConfig as K, type LLMProvider as L, type MemoryBundle as M, WikiDuplicateHashError as N, type OntologyManifest as O, type PromptOverrides as P, type WikiEdge as Q, type ReadOptions as R, type SQLiteAdapter as S, type WikiEvent as T, type WikiFact as U, type VectorRanker as V, type WikiOptions as W, WikiIngestEmptyError as X, WikiInvalidReadOptions as Y, type WikiMemoryTestAccess as Z, type WikiOutboxEvent as _, type MemoryDump as a, WikiSourceRefHashCollision as a0, WikiStrictOntologyViolation as a1, type WikiTask as a2, WikiTransactionError as a3, EmbeddingService as a4, ImportExportService as a5, IngestionService as a6, JobManager as a7, MaintenanceService as a8, RetrievalService as a9, SearchService as aa, WriteService as ab, type FormattedMemoryDump as b, WikiMemory as c, type ExtractedFact as d, type ExtractedFactEdge as e, type ExtractedFactWithOntology as f, type ExtractedTask as g, type GraphTraversalOptions as h, HEAL_RECHECK_MS as i, HOOK_TIMEOUT_MARKER as j, type HealResult as k, ONTOLOGY_BACKFILL_BATCH_SIZE as l, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS as m, ONTOLOGY_BACKFILL_RECHECK_MS as n, type OntologyBackfillResult as o, type OntologyConfig as p, type OntologyEdgeType as q, type OntologyMode as r, type OntologyNodeType as s, type OntologyPromptContext as t, type OntologyUpdates as u, PromptService as v, PrunePartialFailureError as w, type VectorRankerFallback as x, type VectorRankerRankArgs as y, type VectorRankerSemanticResult as z };

package/dist/{testing-D0m2V9-E.d.ts → testing-DWpAgNLt.d.ts}

@@ -195,6 +195,16 @@ interface WikiConfig {
     maxChunkLength?: number;
     chunkOverlap?: number;
     chunkConcurrency?: number;
+    /**
+     * Maximum characters of `title + body + tags` passed to `llmProvider.embed()`
+     * when embedding a fact. Longer input is clipped, not rejected.
+     *
+     * Default 6000 (~1,500 tokens), which fits common embedding windows including
+     * nomic-embed-text's 2,048 tokens with headroom. Values above the 16,000
+     * hard ceiling are clamped to it; the ceiling is a security control and
+     * configuration cannot raise it.
+     */
+    maxEmbedChars?: number;
     /**
      * Max MiniSearch candidates passed to cosine scoring.
      * When set, MiniSearch pre-filters before the cosine scan.
@@ -250,6 +260,23 @@ interface ReadOptions {
      * Only meaningful when `entityId` is an array; ignored for single-string calls.
      */
     includeZeroWeightEntities?: boolean;
+    /**
+     * Minimum number of results to retain from each named entity before the global
+     * `maxResults` cut. Applied after scoring: the top-N scored results from each
+     * named entity are reserved, then remaining slots fill by score as usual.
+     *
+     * An entity with fewer than N matching results contributes what it has — this is
+     * not an error. Floors cannot resurrect a result excluded by `preFilterLimit`.
+     *
+     * Only meaningful when `entityId` is an array; ignored for single-string calls.
+     * Ignored when `query` is empty — that path uses recency ordering and ignores
+     * `tierWeights` as well.
+     *
+     * Throws `WikiInvalidReadOptions` when a floor cannot be satisfied by
+     * construction: floors summing above `maxResults`, a floor on an entity excluded
+     * by `tierWeights: 0`, or a floor keyed to an entity not in `entityId`.
+     */
+    tierFloors?: Record<string, number>;
 }
 interface WikiFact {
     id: string;
@@ -588,6 +615,8 @@ interface MemoryBundle {
         query: string;
         entityIds: string[];
         tierWeights?: Record<string, number>;
+        /** Sanitized per-entity result floors, when `tierFloors` was supplied and non-empty. */
+        tierFloors?: Record<string, number>;
     };
 }
 interface MemoryDump {
@@ -787,6 +816,15 @@ declare class WikiIngestEmptyError extends Error {
         chunks: number;
     });
 }
+/**
+ * Thrown by `read()` when `ReadOptions` contains a request that cannot be
+ * satisfied by construction — as opposed to one that merely finds no data.
+ */
+declare class WikiInvalidReadOptions extends Error {
+    readonly field: string;
+    readonly reason: string;
+    constructor(field: string, reason: string);
+}
 
 interface WikiOutboxEvent<T = unknown> {
     id: string;
@@ -1244,10 +1282,23 @@ declare class MetadataRepository extends BaseRepository {
         mode: OntologyMode;
         manifest: OntologyManifest;
     } | null>;
+    /**
+     * Write an entity's manifest.
+     *
+     * `opts.ifAbsent` selects the conflict behaviour:
+     * - omitted / `false` — upsert. An existing row is replaced.
+     * - `true` — create-if-absent. An existing row is left exactly as it is.
+     *
+     * Returns whether this call actually wrote a row. Under `ifAbsent` a `false`
+     * result means another writer got there first; the check and the write are one
+     * statement, so there is no window between them.
+     */
     setManifest(entityId: string, data: {
         mode: OntologyMode;
         manifest: OntologyManifest;
-    }, tx: SQLiteAdapter): Promise<void>;
+    }, tx: SQLiteAdapter, opts?: {
+        ifAbsent?: boolean;
+    }): Promise<boolean>;
     mergeManifestUpdates(entityId: string, updates: OntologyUpdates, tx: SQLiteAdapter): Promise<OntologyManifest>;
 }
 
@@ -2339,10 +2390,44 @@ declare class WikiMemory {
      * Seeds or replaces an entity's ontology manifest and optional mode override.
      * Validates manifest invariants (unique type slugs, edge endpoints reference node types).
      * Invalidates the in-memory ontology cache for this entity.
+     *
+     * Delegates to `setOntologyManifests` so there is a single write path. The
+     * observable contract is unchanged: same upsert semantics, same cache
+     * invalidation, same `void` result.
      */
     setOntologyManifest(entityId: string, manifest: OntologyManifest, options?: {
         mode?: OntologyMode;
     }): Promise<void>;
+    /**
+     * Write several entities' ontology manifests in a single transaction.
+     *
+     * All succeed or none do. The transaction is opened on this instance's
+     * serialized adapter — callers pass data, never a transaction handle, because
+     * a consumer holds the unwrapped adapter and a transaction opened on it would
+     * bypass the serialization mutex applied in the constructor.
+     *
+     * Returns which entities were written. `skipped` is only ever non-empty under
+     * `opts.ifAbsent`.
+     *
+     * Sharp edge: `ifAbsent` checks for a PERSISTED row, not for an effective
+     * manifest. An entity whose manifest currently comes from
+     * `WikiConfig.ontology.seedManifests` has no row until the seed is
+     * materialized on first access that supplies a transaction (in practice, an
+     * ingest). Until then `ifAbsent` treats the entity as absent, writes the new
+     * manifest over the configured seed, and reports it in `written`; the same
+     * call after the seed has been materialized reports it in `skipped`. See the
+     * `ifAbsent` notes in the package README.
+     */
+    setOntologyManifests(entries: Array<{
+        entityId: string;
+        manifest: OntologyManifest;
+        mode?: OntologyMode;
+    }>, opts?: {
+        ifAbsent?: boolean;
+    }): Promise<{
+        written: string[];
+        skipped: string[];
+    }>;
     /** Append a verification event to a fact. Does NOT touch `updated_at`. */
     writeOkfTrust(entryId: string, entityId: string, verified: {
         by: string;
@@ -2373,4 +2458,4 @@ declare class WikiMemory {
     setGeneratedByTask(taskId: string, entityId: string, actor: string): Promise<void>;
 }
 
-export { WikiSourceRefHashCollision as $, WikiBusyError as A, type WikiBusyOperation as B, type ChunkFailure as C, type DegradedRecord as D, type EntityStatus as E, type FormatContextOptions as F, type GraphNeighborhood as G, HEAL_BATCH_SIZE as H, type IngestDocumentResult as I, type WikiCheckpoint as J, type WikiConfig as K, type LLMProvider as L, type MemoryBundle as M, WikiDuplicateHashError as N, type OntologyManifest as O, type PromptOverrides as P, type WikiEdge as Q, type ReadOptions as R, type SQLiteAdapter as S, type WikiEvent as T, type WikiFact as U, type VectorRanker as V, type WikiOptions as W, WikiIngestEmptyError as X, type WikiMemoryTestAccess as Y, type WikiOutboxEvent as Z, WikiParseError as _, type MemoryDump as a, WikiStrictOntologyViolation as a0, type WikiTask as a1, WikiTransactionError as a2, EmbeddingService as a3, ImportExportService as a4, IngestionService as a5, JobManager as a6, MaintenanceService as a7, RetrievalService as a8, SearchService as a9, WriteService as aa, type FormattedMemoryDump as b, WikiMemory as c, type ExtractedFact as d, type ExtractedFactEdge as e, type ExtractedFactWithOntology as f, type ExtractedTask as g, type GraphTraversalOptions as h, HEAL_RECHECK_MS as i, HOOK_TIMEOUT_MARKER as j, type HealResult as k, ONTOLOGY_BACKFILL_BATCH_SIZE as l, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS as m, ONTOLOGY_BACKFILL_RECHECK_MS as n, type OntologyBackfillResult as o, type OntologyConfig as p, type OntologyEdgeType as q, type OntologyMode as r, type OntologyNodeType as s, type OntologyPromptContext as t, type OntologyUpdates as u, PromptService as v, PrunePartialFailureError as w, type VectorRankerFallback as x, type VectorRankerRankArgs as y, type VectorRankerSemanticResult as z };
+export { WikiParseError as $, WikiBusyError as A, type WikiBusyOperation as B, type ChunkFailure as C, type DegradedRecord as D, type EntityStatus as E, type FormatContextOptions as F, type GraphNeighborhood as G, HEAL_BATCH_SIZE as H, type IngestDocumentResult as I, type WikiCheckpoint as J, type WikiConfig as K, type LLMProvider as L, type MemoryBundle as M, WikiDuplicateHashError as N, type OntologyManifest as O, type PromptOverrides as P, type WikiEdge as Q, type ReadOptions as R, type SQLiteAdapter as S, type WikiEvent as T, type WikiFact as U, type VectorRanker as V, type WikiOptions as W, WikiIngestEmptyError as X, WikiInvalidReadOptions as Y, type WikiMemoryTestAccess as Z, type WikiOutboxEvent as _, type MemoryDump as a, WikiSourceRefHashCollision as a0, WikiStrictOntologyViolation as a1, type WikiTask as a2, WikiTransactionError as a3, EmbeddingService as a4, ImportExportService as a5, IngestionService as a6, JobManager as a7, MaintenanceService as a8, RetrievalService as a9, SearchService as aa, WriteService as ab, type FormattedMemoryDump as b, WikiMemory as c, type ExtractedFact as d, type ExtractedFactEdge as e, type ExtractedFactWithOntology as f, type ExtractedTask as g, type GraphTraversalOptions as h, HEAL_RECHECK_MS as i, HOOK_TIMEOUT_MARKER as j, type HealResult as k, ONTOLOGY_BACKFILL_BATCH_SIZE as l, ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS as m, ONTOLOGY_BACKFILL_RECHECK_MS as n, type OntologyBackfillResult as o, type OntologyConfig as p, type OntologyEdgeType as q, type OntologyMode as r, type OntologyNodeType as s, type OntologyPromptContext as t, type OntologyUpdates as u, PromptService as v, PrunePartialFailureError as w, type VectorRankerFallback as x, type VectorRankerRankArgs as y, type VectorRankerSemanticResult as z };

package/dist/testing.d.mts

@@ -1,3 +1,3 @@
-export { a3 as EmbeddingService, a4 as ImportExportService, a5 as IngestionService, a6 as JobManager, a6 as JobManagerType, a7 as MaintenanceService, a8 as RetrievalService, a9 as SearchService, a9 as SearchServiceType, Y as WikiMemoryTestAccess, aa as WriteService } from './testing-D0m2V9-E.mjs';
+export { a4 as EmbeddingService, a5 as ImportExportService, a6 as IngestionService, a7 as JobManager, a7 as JobManagerType, a8 as MaintenanceService, a9 as RetrievalService, aa as SearchService, aa as SearchServiceType, Z as WikiMemoryTestAccess, ab as WriteService } from './testing-DWpAgNLt.mjs';
 import '@equationalapplications/core-okf';
 import 'minisearch';

package/dist/testing.d.ts

@@ -1,3 +1,3 @@
-export { a3 as EmbeddingService, a4 as ImportExportService, a5 as IngestionService, a6 as JobManager, a6 as JobManagerType, a7 as MaintenanceService, a8 as RetrievalService, a9 as SearchService, a9 as SearchServiceType, Y as WikiMemoryTestAccess, aa as WriteService } from './testing-D0m2V9-E.js';
+export { a4 as EmbeddingService, a5 as ImportExportService, a6 as IngestionService, a7 as JobManager, a7 as JobManagerType, a8 as MaintenanceService, a9 as RetrievalService, aa as SearchService, aa as SearchServiceType, Z as WikiMemoryTestAccess, ab as WriteService } from './testing-DWpAgNLt.js';
 import '@equationalapplications/core-okf';
 import 'minisearch';

package/dist/testing.js

@@ -129,6 +129,15 @@ var WikiIngestEmptyError = class extends Error {
     this.chunks = params.chunks;
   }
 };
+var WikiInvalidReadOptions = class _WikiInvalidReadOptions extends Error {
+  constructor(field, reason) {
+    super(`Invalid ReadOptions.${field}: ${reason}`);
+    this.name = "WikiInvalidReadOptions";
+    this.field = field;
+    this.reason = reason;
+    Object.setPrototypeOf(this, _WikiInvalidReadOptions.prototype);
+  }
+};
 
 // src/utils/pure.ts
 var MAX_REPAIR_CANDIDATES = 5;
@@ -616,6 +625,10 @@ function jaccardScore(a, b) {
   return intersection.size / union.size;
 }
 
+// src/utils/embedDefaults.ts
+var DEFAULT_MAX_EMBED_CHARS = 6e3;
+var EMBED_CHARS_CEILING = 16e3;
+
 // src/services/EmbeddingService.ts
 var EmbeddingService = class {
   constructor(db, options, entryRepo, metadataRepo) {
@@ -663,7 +676,9 @@ var EmbeddingService = class {
         tagsStr = fact.tags;
       }
     }
-    const text = clip(`${fact.title} ${fact.body} ${tagsStr}`.trim(), 16e3);
+    const configuredMaxEmbedChars = this.options.config?.maxEmbedChars;
+    const maxEmbedChars = Number.isFinite(configuredMaxEmbedChars) ? Math.min(Math.max(0, Math.trunc(configuredMaxEmbedChars)), EMBED_CHARS_CEILING) : DEFAULT_MAX_EMBED_CHARS;
+    const text = clip(`${fact.title} ${fact.body} ${tagsStr}`.trim(), maxEmbedChars);
     try {
       const vector = await embedFn(text);
       if (vector.length === 0 || !vector.every((v) => typeof v === "number" && isFinite(v))) {
@@ -2989,6 +3004,63 @@ function applyTierWeight(score, entityId, sanitizedTierWeights) {
 function shouldExposeReadMetadata(entityId) {
   return Array.isArray(entityId);
 }
+function validateTierFloors(entityIds, tierFloors, sanitizedTierWeights, includeZeroWeightEntities, maxResults) {
+  if (tierFloors === void 0) return void 0;
+  const known = new Set(entityIds);
+  for (const key of Object.keys(tierFloors)) {
+    const raw = tierFloors[key];
+    if (raw === void 0 || !Number.isFinite(raw)) continue;
+    if (!known.has(key)) {
+      throw new WikiInvalidReadOptions(
+        "tierFloors",
+        `"${key}" is not one of the entity IDs passed to read(); a floor on an unrequested entity can never be satisfied`
+      );
+    }
+  }
+  const sanitized = /* @__PURE__ */ Object.create(null);
+  let total = 0;
+  for (const entityId of entityIds) {
+    const raw = tierFloors[entityId];
+    if (raw === void 0 || !Number.isFinite(raw)) continue;
+    const floor = Math.max(0, Math.trunc(raw));
+    if (floor > 0 && includeZeroWeightEntities !== true && sanitizedTierWeights?.[entityId] === 0) {
+      throw new WikiInvalidReadOptions(
+        "tierFloors",
+        `"${entityId}" has tierWeight 0 and includeZeroWeightEntities is not set, so it is excluded from retrieval and its floor of ${floor} can never be met`
+      );
+    }
+    sanitized[entityId] = floor;
+    total += floor;
+  }
+  if (total > maxResults) {
+    throw new WikiInvalidReadOptions(
+      "tierFloors",
+      `floors sum to ${total}, which exceeds maxResults (${maxResults})`
+    );
+  }
+  return sanitized;
+}
+function selectWithFloors(sortedRows, floors, maxResults) {
+  if (maxResults <= 0) return [];
+  if (floors === void 0 || Object.keys(floors).length === 0) {
+    return sortedRows.slice(0, maxResults);
+  }
+  const selected = /* @__PURE__ */ new Set();
+  const taken = /* @__PURE__ */ Object.create(null);
+  for (let i = 0; i < sortedRows.length; i++) {
+    const entityId = sortedRows[i].entity_id;
+    const floor = floors[entityId] ?? 0;
+    if (floor <= 0) continue;
+    const count = taken[entityId] ?? 0;
+    if (count >= floor) continue;
+    taken[entityId] = count + 1;
+    selected.add(i);
+  }
+  for (let i = 0; i < sortedRows.length && selected.size < maxResults; i++) {
+    if (!selected.has(i)) selected.add(i);
+  }
+  return Array.from(selected).sort((a, b) => a - b).map((i) => sortedRows[i]);
+}
 
 // src/services/RetrievalService.ts
 var RetrievalService = class {
@@ -3023,13 +3095,20 @@ var RetrievalService = class {
     }
     const rawMaxResults = options?.maxResults ?? config?.maxResults ?? config?.maxFtsResults ?? 10;
     const maxResults = Number.isFinite(rawMaxResults) ? Math.max(0, Math.trunc(rawMaxResults)) : 10;
+    const trimmedQuery = query.trim();
+    const sanitizedTierFloors = trimmedQuery && exposeMetadata ? validateTierFloors(
+      entityIds,
+      options?.tierFloors,
+      sanitizedTierWeights,
+      options?.includeZeroWeightEntities,
+      maxResults
+    ) : void 0;
     const rawPreFilterLimit = options?.preFilterLimit === null ? void 0 : options?.preFilterLimit ?? config?.preFilterLimit;
     const effectivePreFilterLimit = rawPreFilterLimit === void 0 ? void 0 : Number.isFinite(rawPreFilterLimit) ? Math.max(0, Math.trunc(rawPreFilterLimit)) : void 0;
     const hybridWeight = options?.hybridWeight ?? config?.hybridWeight;
     const weight = hybridWeight !== void 0 && !Number.isNaN(hybridWeight) ? Math.max(0, Math.min(1, hybridWeight)) : void 0;
     const skipEmbed = weight === 0;
     const embedFn = this.options.llmProvider.embed;
-    const trimmedQuery = query.trim();
     let facts = [];
     let scoreByFactId;
     if (maxResults === 0) ; else if (trimmedQuery) {
@@ -3140,13 +3219,74 @@ var RetrievalService = class {
                     access_count: metadata?.access_count ?? null
                   };
                 });
+                const floorShortfallByEntity = /* @__PURE__ */ Object.create(null);
+                let totalFloorShortfall = 0;
+                if (sanitizedTierFloors) {
+                  const scoredCounts = /* @__PURE__ */ new Map();
+                  for (const s of scored) {
+                    scoredCounts.set(s.entity_id, (scoredCounts.get(s.entity_id) ?? 0) + 1);
+                  }
+                  for (const [entityId2, floor] of Object.entries(sanitizedTierFloors)) {
+                    if (floor <= 0) continue;
+                    const currentCount = scoredCounts.get(entityId2) ?? 0;
+                    const shortfall = Math.max(0, floor - currentCount);
+                    if (shortfall > 0) {
+                      floorShortfallByEntity[entityId2] = shortfall;
+                      totalFloorShortfall += shortfall;
+                    }
+                  }
+                }
+                const reservedIds = /* @__PURE__ */ new Set();
+                const reserved = [];
+                if (totalFloorShortfall > 0) {
+                  for (const [entityId2, shortfall] of Object.entries(floorShortfallByEntity)) {
+                    const entityOmitted = [];
+                    for (const row of candidateRows) {
+                      if (scoredIds.has(row.id) || reservedIds.has(row.id)) continue;
+                      if (row.entity_id !== entityId2) continue;
+                      const kwScore = miniSearchScores?.get(row.id) ?? 0;
+                      entityOmitted.push({ row, kwScore });
+                    }
+                    entityOmitted.sort((a, b) => this._compareScoredRows(
+                      { id: a.row.id, score: a.kwScore, updated_at: a.row.updated_at, access_count: a.row.access_count },
+                      { id: b.row.id, score: b.kwScore, updated_at: b.row.updated_at, access_count: b.row.access_count }
+                    ));
+                    for (let i = 0; i < Math.min(shortfall, entityOmitted.length); i++) {
+                      reserved.push(entityOmitted[i]);
+                      reservedIds.add(entityOmitted[i].row.id);
+                    }
+                  }
+                }
                 const isHybrid = weight !== void 0 && weight < 1;
+                if (reserved.length > 0) {
+                  if (isHybrid) {
+                    for (const { row, kwScore } of reserved) {
+                      scored.push({
+                        id: row.id,
+                        entity_id: row.entity_id,
+                        score: (1 - weight) * kwScore,
+                        updated_at: row.updated_at,
+                        access_count: row.access_count
+                      });
+                    }
+                  } else {
+                    for (const { row } of reserved) {
+                      scored.push({
+                        id: row.id,
+                        entity_id: row.entity_id,
+                        score: -2,
+                        updated_at: row.updated_at,
+                        access_count: row.access_count
+                      });
+                    }
+                  }
+                }
                 const maxBackfill = isHybrid ? maxResults : Math.max(0, maxResults - scored.length);
                 if (maxBackfill > 0) {
                   if (isHybrid) {
                     const topK = [];
                     for (const row of candidateRows) {
-                      if (scoredIds.has(row.id)) continue;
+                      if (scoredIds.has(row.id) || reservedIds.has(row.id)) continue;
                       const kwScore = miniSearchScores?.get(row.id) ?? 0;
                       const candidate = { row, kwScore };
                       if (topK.length < maxBackfill) {
@@ -3226,7 +3366,7 @@ var RetrievalService = class {
                   } else {
                     const omitted = [];
                     for (const row of candidateRows) {
-                      if (scoredIds.has(row.id)) continue;
+                      if (scoredIds.has(row.id) || reservedIds.has(row.id)) continue;
                       omitted.push({ id: row.id, entity_id: row.entity_id, score: -2, updated_at: row.updated_at, access_count: row.access_count });
                     }
                     if (omitted.length > 0) {
@@ -3274,8 +3414,11 @@ var RetrievalService = class {
                     // read() re-sorts after applying tier weights
                   });
                 } else if (policy === "keyword") {
-                  const keywordOversampledLimit = Math.max(maxResults * 2, maxResults + 50);
-                  const topResults = this.searchService.searchKeyword(trimmedQuery, scoredEntityIds, keywordOversampledLimit);
+                  const hasActiveFloorsKeywordFallback = sanitizedTierFloors !== void 0 && Object.values(sanitizedTierFloors).some((f) => f > 0);
+                  const keywordOversampledLimit = hasActiveFloorsKeywordFallback ? Number.MAX_SAFE_INTEGER : Math.max(maxResults * 2, maxResults + 50);
+                  const preFilteredIds = effectivePreFilterLimit !== void 0 ? new Set(candidateRows.map((r) => r.id)) : void 0;
+                  const keywordResults = this.searchService.searchKeyword(trimmedQuery, scoredEntityIds, keywordOversampledLimit);
+                  const topResults = preFilteredIds === void 0 ? keywordResults : keywordResults.filter((r) => preFilteredIds.has(r.id));
                   const topResultIds = new Set(topResults.map((r) => r.id));
                   const candidateMap = new Map(candidateRows.filter((r) => topResultIds.has(r.id)).map((row) => [row.id, row]));
                   scored = topResults.map((result) => {
@@ -3300,7 +3443,7 @@ var RetrievalService = class {
                 }
               }
             } else {
-              const jsCosineNeedsTierSort = sanitizedTierWeights !== void 0 && Object.values(sanitizedTierWeights).some((w) => w !== 1);
+              const jsCosineNeedsTierSort = sanitizedTierWeights !== void 0 && Object.values(sanitizedTierWeights).some((w) => w !== 1) || sanitizedTierFloors !== void 0 && Object.values(sanitizedTierFloors).some((f) => f > 0);
               scored = await this.searchService.rankSemantic({
                 entityId: entityCacheKey,
                 queryVec,
@@ -3319,7 +3462,7 @@ var RetrievalService = class {
                 score: applyTierWeight(row.score, row.entity_id, sanitizedTierWeights)
               }));
               this._tieBreakSort(scored);
-              const selectedScored = scored.slice(0, maxResults);
+              const selectedScored = selectWithFloors(scored, sanitizedTierFloors, maxResults);
               const topIds = selectedScored.map((s) => s.id);
               if (exposeMetadata && trimmedQuery) {
                 scoreByFactId = new Map(selectedScored.map((s) => [s.id, Number.isFinite(s.score) ? s.score : 0]));
@@ -3374,7 +3517,8 @@ var RetrievalService = class {
         }
       }
       if (!usedEmbed && scoredEntityIds.length > 0) {
-        const fallbackOversampledLimit = Math.max(maxResults * 2, maxResults + 50);
+        const hasActiveFloors = sanitizedTierFloors !== void 0 && Object.values(sanitizedTierFloors).some((f) => f > 0);
+        const fallbackOversampledLimit = hasActiveFloors ? Number.MAX_SAFE_INTEGER : Math.max(maxResults * 2, maxResults + 50);
         const results = this.searchService.searchKeyword(trimmedQuery, scoredEntityIds, fallbackOversampledLimit);
         const candidates = results.map((r) => ({
           id: r.id,
@@ -3384,7 +3528,7 @@ var RetrievalService = class {
           access_count: null
         }));
         this._tieBreakSort(candidates);
-        const topCandidates = candidates.slice(0, maxResults);
+        const topCandidates = selectWithFloors(candidates, sanitizedTierFloors, maxResults);
         const topIds = topCandidates.map((c) => c.id);
         if (topIds.length > 0) {
           facts = await this._hydrateFactsByIds(topIds, entityIds);
@@ -3414,6 +3558,7 @@ var RetrievalService = class {
     if (exposeMetadata) {
       bundle.metadata = { query, entityIds };
       if (sanitizedTierWeights && Object.keys(sanitizedTierWeights).length > 0) bundle.metadata.tierWeights = sanitizedTierWeights;
+      if (sanitizedTierFloors && Object.keys(sanitizedTierFloors).length > 0) bundle.metadata.tierFloors = sanitizedTierFloors;
       if (factScores && Object.keys(factScores).length > 0) bundle.factScores = factScores;
     }
     return bundle;