@equationalapplications/core-llm-wiki 6.2.0 → 6.4.0

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { M as MemoryBundle, F as FormatContextOptions, G as GraphNeighborhood, a as MemoryDump, b as FormattedMemoryDump, O as OntologyManifest, R as ReadOptions, S as SQLiteAdapter, W as WikiOptions, c as WikiMemory } from './testing-D0m2V9-E.mjs';
-export { C as ChunkFailure, D as DegradedRecord, E as EntityStatus, d as ExtractedFact, e as ExtractedFactEdge, f as ExtractedFactWithOntology, g as ExtractedTask, h as GraphTraversalOptions, H as HEAL_BATCH_SIZE, i as HEAL_RECHECK_MS, j as HOOK_TIMEOUT_MARKER, k as HealResult, I as IngestDocumentResult, L as LLMProvider, l as ONTOLOGY_BACKFILL_BATCH_SIZE, m as ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, n as ONTOLOGY_BACKFILL_RECHECK_MS, o as OntologyBackfillResult, p as OntologyConfig, q as OntologyEdgeType, r as OntologyMode, s as OntologyNodeType, t as OntologyPromptContext, u as OntologyUpdates, P as PromptOverrides, v as PromptService, w as PrunePartialFailureError, V as VectorRanker, x as VectorRankerFallback, y as VectorRankerRankArgs, z as VectorRankerSemanticResult, A as WikiBusyError, B as WikiBusyOperation, J as WikiCheckpoint, K as WikiConfig, N as WikiDuplicateHashError, Q as WikiEdge, T as WikiEvent, U as WikiFact, X as WikiIngestEmptyError, Y as WikiMemoryTestAccess, Z as WikiOutboxEvent, _ as WikiParseError, $ as WikiSourceRefHashCollision, a0 as WikiStrictOntologyViolation, a1 as WikiTask, a2 as WikiTransactionError } from './testing-D0m2V9-E.mjs';
+import { M as MemoryBundle, F as FormatContextOptions, G as GraphNeighborhood, a as MemoryDump, b as FormattedMemoryDump, O as OntologyManifest, R as ReadOptions, S as SQLiteAdapter, W as WikiOptions, c as WikiMemory } from './testing-DWpAgNLt.mjs';
+export { C as ChunkFailure, D as DegradedRecord, E as EntityStatus, d as ExtractedFact, e as ExtractedFactEdge, f as ExtractedFactWithOntology, g as ExtractedTask, h as GraphTraversalOptions, H as HEAL_BATCH_SIZE, i as HEAL_RECHECK_MS, j as HOOK_TIMEOUT_MARKER, k as HealResult, I as IngestDocumentResult, L as LLMProvider, l as ONTOLOGY_BACKFILL_BATCH_SIZE, m as ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, n as ONTOLOGY_BACKFILL_RECHECK_MS, o as OntologyBackfillResult, p as OntologyConfig, q as OntologyEdgeType, r as OntologyMode, s as OntologyNodeType, t as OntologyPromptContext, u as OntologyUpdates, P as PromptOverrides, v as PromptService, w as PrunePartialFailureError, V as VectorRanker, x as VectorRankerFallback, y as VectorRankerRankArgs, z as VectorRankerSemanticResult, A as WikiBusyError, B as WikiBusyOperation, J as WikiCheckpoint, K as WikiConfig, N as WikiDuplicateHashError, Q as WikiEdge, T as WikiEvent, U as WikiFact, X as WikiIngestEmptyError, Y as WikiInvalidReadOptions, Z as WikiMemoryTestAccess, _ as WikiOutboxEvent, $ as WikiParseError, a0 as WikiSourceRefHashCollision, a1 as WikiStrictOntologyViolation, a2 as WikiTask, a3 as WikiTransactionError } from './testing-DWpAgNLt.mjs';
 import { OkfFile } from '@equationalapplications/core-okf';
 import 'minisearch';
 
@@ -119,6 +119,18 @@ declare const DEFAULT_MAX_CHUNK_LENGTH = 12000;
  */
 declare const DEFAULT_CHUNK_OVERLAP = 400;
 
+/**
+ * Default clamp on embed input length, in characters (~1,500 tokens).
+ * Chosen to fit common embedding windows including nomic-embed-text's 2,048 tokens.
+ */
+declare const DEFAULT_MAX_EMBED_CHARS = 6000;
+/**
+ * Hard upper bound on embed input length, in characters.
+ * An unbounded-input guard from `5e04bad fix(core): security hardening phase 2`.
+ * Configuration may lower the effective limit but must never raise it past this.
+ */
+declare const EMBED_CHARS_CEILING = 16000;
+
 interface LibrarianOptions {
     /** If provided, replaces the default Librarian system instructions. */
     systemPrompt?: string;
@@ -145,4 +157,4 @@ declare const ONTOLOGY_BACKFILL_SYSTEM_PROMPT = "You are a knowledge classificat
 
 declare function createWiki(db: SQLiteAdapter, options: WikiOptions): WikiMemory;
 
-export { DEFAULT_CHUNK_OVERLAP, DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT, DEFAULT_MAX_CHUNK_LENGTH, FormatContextOptions, type FormatOkfBundleOptions, FormattedMemoryDump, GraphNeighborhood, HEAL_ANCHORS_PER_CANDIDATE, HEAL_MAX_FACT_BODY_CHARS_L3, HEAL_MAX_TASKS, type LibrarianOptions, type LibrarianPromptVariables, MemoryBundle, MemoryDump, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, type OkfFormatProfile, type OkfImportOptions, OntologyManifest, ReadOptions, SQLiteAdapter, WikiMemory, WikiOptions, chunkText, configureRandomSource, createWiki, formatContext, formatGraphContext, formatMemoryDump, formatOkfBundle, hydrateLibrarianPrompt, mapLibrarianOptionsToReadOptions, parseEmbedding, parseOkfBundle, safeSlice, validateLibrarianPromptTemplate, validateManifest };
+export { DEFAULT_CHUNK_OVERLAP, DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT, DEFAULT_MAX_CHUNK_LENGTH, DEFAULT_MAX_EMBED_CHARS, EMBED_CHARS_CEILING, FormatContextOptions, type FormatOkfBundleOptions, FormattedMemoryDump, GraphNeighborhood, HEAL_ANCHORS_PER_CANDIDATE, HEAL_MAX_FACT_BODY_CHARS_L3, HEAL_MAX_TASKS, type LibrarianOptions, type LibrarianPromptVariables, MemoryBundle, MemoryDump, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, type OkfFormatProfile, type OkfImportOptions, OntologyManifest, ReadOptions, SQLiteAdapter, WikiMemory, WikiOptions, chunkText, configureRandomSource, createWiki, formatContext, formatGraphContext, formatMemoryDump, formatOkfBundle, hydrateLibrarianPrompt, mapLibrarianOptionsToReadOptions, parseEmbedding, parseOkfBundle, safeSlice, validateLibrarianPromptTemplate, validateManifest };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { M as MemoryBundle, F as FormatContextOptions, G as GraphNeighborhood, a as MemoryDump, b as FormattedMemoryDump, O as OntologyManifest, R as ReadOptions, S as SQLiteAdapter, W as WikiOptions, c as WikiMemory } from './testing-D0m2V9-E.js';
-export { C as ChunkFailure, D as DegradedRecord, E as EntityStatus, d as ExtractedFact, e as ExtractedFactEdge, f as ExtractedFactWithOntology, g as ExtractedTask, h as GraphTraversalOptions, H as HEAL_BATCH_SIZE, i as HEAL_RECHECK_MS, j as HOOK_TIMEOUT_MARKER, k as HealResult, I as IngestDocumentResult, L as LLMProvider, l as ONTOLOGY_BACKFILL_BATCH_SIZE, m as ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, n as ONTOLOGY_BACKFILL_RECHECK_MS, o as OntologyBackfillResult, p as OntologyConfig, q as OntologyEdgeType, r as OntologyMode, s as OntologyNodeType, t as OntologyPromptContext, u as OntologyUpdates, P as PromptOverrides, v as PromptService, w as PrunePartialFailureError, V as VectorRanker, x as VectorRankerFallback, y as VectorRankerRankArgs, z as VectorRankerSemanticResult, A as WikiBusyError, B as WikiBusyOperation, J as WikiCheckpoint, K as WikiConfig, N as WikiDuplicateHashError, Q as WikiEdge, T as WikiEvent, U as WikiFact, X as WikiIngestEmptyError, Y as WikiMemoryTestAccess, Z as WikiOutboxEvent, _ as WikiParseError, $ as WikiSourceRefHashCollision, a0 as WikiStrictOntologyViolation, a1 as WikiTask, a2 as WikiTransactionError } from './testing-D0m2V9-E.js';
+import { M as MemoryBundle, F as FormatContextOptions, G as GraphNeighborhood, a as MemoryDump, b as FormattedMemoryDump, O as OntologyManifest, R as ReadOptions, S as SQLiteAdapter, W as WikiOptions, c as WikiMemory } from './testing-DWpAgNLt.js';
+export { C as ChunkFailure, D as DegradedRecord, E as EntityStatus, d as ExtractedFact, e as ExtractedFactEdge, f as ExtractedFactWithOntology, g as ExtractedTask, h as GraphTraversalOptions, H as HEAL_BATCH_SIZE, i as HEAL_RECHECK_MS, j as HOOK_TIMEOUT_MARKER, k as HealResult, I as IngestDocumentResult, L as LLMProvider, l as ONTOLOGY_BACKFILL_BATCH_SIZE, m as ONTOLOGY_BACKFILL_MAX_PROMPT_CHARS, n as ONTOLOGY_BACKFILL_RECHECK_MS, o as OntologyBackfillResult, p as OntologyConfig, q as OntologyEdgeType, r as OntologyMode, s as OntologyNodeType, t as OntologyPromptContext, u as OntologyUpdates, P as PromptOverrides, v as PromptService, w as PrunePartialFailureError, V as VectorRanker, x as VectorRankerFallback, y as VectorRankerRankArgs, z as VectorRankerSemanticResult, A as WikiBusyError, B as WikiBusyOperation, J as WikiCheckpoint, K as WikiConfig, N as WikiDuplicateHashError, Q as WikiEdge, T as WikiEvent, U as WikiFact, X as WikiIngestEmptyError, Y as WikiInvalidReadOptions, Z as WikiMemoryTestAccess, _ as WikiOutboxEvent, $ as WikiParseError, a0 as WikiSourceRefHashCollision, a1 as WikiStrictOntologyViolation, a2 as WikiTask, a3 as WikiTransactionError } from './testing-DWpAgNLt.js';
 import { OkfFile } from '@equationalapplications/core-okf';
 import 'minisearch';
 
@@ -119,6 +119,18 @@ declare const DEFAULT_MAX_CHUNK_LENGTH = 12000;
  */
 declare const DEFAULT_CHUNK_OVERLAP = 400;
 
+/**
+ * Default clamp on embed input length, in characters (~1,500 tokens).
+ * Chosen to fit common embedding windows including nomic-embed-text's 2,048 tokens.
+ */
+declare const DEFAULT_MAX_EMBED_CHARS = 6000;
+/**
+ * Hard upper bound on embed input length, in characters.
+ * An unbounded-input guard from `5e04bad fix(core): security hardening phase 2`.
+ * Configuration may lower the effective limit but must never raise it past this.
+ */
+declare const EMBED_CHARS_CEILING = 16000;
+
 interface LibrarianOptions {
     /** If provided, replaces the default Librarian system instructions. */
     systemPrompt?: string;
@@ -145,4 +157,4 @@ declare const ONTOLOGY_BACKFILL_SYSTEM_PROMPT = "You are a knowledge classificat
 
 declare function createWiki(db: SQLiteAdapter, options: WikiOptions): WikiMemory;
 
-export { DEFAULT_CHUNK_OVERLAP, DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT, DEFAULT_MAX_CHUNK_LENGTH, FormatContextOptions, type FormatOkfBundleOptions, FormattedMemoryDump, GraphNeighborhood, HEAL_ANCHORS_PER_CANDIDATE, HEAL_MAX_FACT_BODY_CHARS_L3, HEAL_MAX_TASKS, type LibrarianOptions, type LibrarianPromptVariables, MemoryBundle, MemoryDump, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, type OkfFormatProfile, type OkfImportOptions, OntologyManifest, ReadOptions, SQLiteAdapter, WikiMemory, WikiOptions, chunkText, configureRandomSource, createWiki, formatContext, formatGraphContext, formatMemoryDump, formatOkfBundle, hydrateLibrarianPrompt, mapLibrarianOptionsToReadOptions, parseEmbedding, parseOkfBundle, safeSlice, validateLibrarianPromptTemplate, validateManifest };
+export { DEFAULT_CHUNK_OVERLAP, DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT, DEFAULT_MAX_CHUNK_LENGTH, DEFAULT_MAX_EMBED_CHARS, EMBED_CHARS_CEILING, FormatContextOptions, type FormatOkfBundleOptions, FormattedMemoryDump, GraphNeighborhood, HEAL_ANCHORS_PER_CANDIDATE, HEAL_MAX_FACT_BODY_CHARS_L3, HEAL_MAX_TASKS, type LibrarianOptions, type LibrarianPromptVariables, MemoryBundle, MemoryDump, ONTOLOGY_BACKFILL_SYSTEM_PROMPT, type OkfFormatProfile, type OkfImportOptions, OntologyManifest, ReadOptions, SQLiteAdapter, WikiMemory, WikiOptions, chunkText, configureRandomSource, createWiki, formatContext, formatGraphContext, formatMemoryDump, formatOkfBundle, hydrateLibrarianPrompt, mapLibrarianOptionsToReadOptions, parseEmbedding, parseOkfBundle, safeSlice, validateLibrarianPromptTemplate, validateManifest };

package/dist/index.js

@@ -306,6 +306,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/db/serializedAdapter.ts
 function isDriverError(err) {
@@ -2784,15 +2793,29 @@ var MetadataRepository = class extends BaseRepository {
       manifest
     };
   }
-  async setManifest(entityId, data, tx) {
+  /**
+   * 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.
+   */
+  async setManifest(entityId, data, tx, opts) {
     validateManifest(data.manifest);
     const executor = this.getExecutor(tx);
-    await executor.runAsync(
+    const conflictClause = opts?.ifAbsent ? "ON CONFLICT(entity_id) DO NOTHING" : `ON CONFLICT(entity_id) DO UPDATE SET
+           mode = excluded.mode, manifest_json = excluded.manifest_json, updated_at = excluded.updated_at`;
+    const result = await executor.runAsync(
       `INSERT INTO ${this.prefix}entity_manifests (entity_id, mode, manifest_json, updated_at)
        VALUES (?, ?, ?, ?)
-       ON CONFLICT(entity_id) DO UPDATE SET mode = excluded.mode, manifest_json = excluded.manifest_json, updated_at = excluded.updated_at`,
+       ${conflictClause}`,
       [entityId, data.mode, JSON.stringify(data.manifest), Date.now()]
     );
+    return result.changes > 0;
   }
   async mergeManifestUpdates(entityId, updates, tx) {
     const current = await this.getManifest(entityId, tx) ?? {
@@ -6127,6 +6150,10 @@ After running the migration SQL, restart your application.`
   }
 };
 
+// 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) {
@@ -6174,7 +6201,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))) {
@@ -6285,6 +6314,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 {
@@ -6319,13 +6405,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) {
@@ -6436,13 +6529,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) {
@@ -6522,7 +6676,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) {
@@ -6570,8 +6724,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) => {
@@ -6596,7 +6753,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,
@@ -6615,7 +6772,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]));
@@ -6670,7 +6827,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,
@@ -6680,7 +6838,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);
@@ -6710,6 +6868,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;
@@ -7701,13 +7860,64 @@ var WikiMemory = class {
    * 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.
    */
   async setOntologyManifest(entityId, manifest, options) {
-    const mode = options?.mode ?? this.ontologyService.resolveMode();
-    await this.db.withTransactionAsync(
-      (tx) => this.metadataRepo.setManifest(entityId, { mode, manifest }, tx)
-    );
-    this.ontologyService.invalidateCache(entityId);
+    await this.setOntologyManifests([{ entityId, manifest, mode: options?.mode }]);
+  }
+  /**
+   * 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.
+   */
+  async setOntologyManifests(entries, opts) {
+    if (entries.length === 0) return { written: [], skipped: [] };
+    const seen = /* @__PURE__ */ new Set();
+    for (const entry of entries) {
+      if (seen.has(entry.entityId)) {
+        throw new Error(`Duplicate entityId in batch: ${entry.entityId}`);
+      }
+      seen.add(entry.entityId);
+    }
+    for (const entry of entries) {
+      validateManifest(entry.manifest);
+    }
+    const written = [];
+    const skipped = [];
+    await this.db.withTransactionAsync(async (tx) => {
+      for (const entry of entries) {
+        const mode = entry.mode ?? this.ontologyService.resolveMode();
+        const wrote = await this.metadataRepo.setManifest(
+          entry.entityId,
+          { mode, manifest: entry.manifest },
+          tx,
+          { ifAbsent: opts?.ifAbsent === true }
+        );
+        (wrote ? written : skipped).push(entry.entityId);
+      }
+    });
+    for (const entry of entries) {
+      this.ontologyService.invalidateCache(entry.entityId);
+    }
+    return { written, skipped };
   }
   /** Append a verification event to a fact. Does NOT touch `updated_at`. */
   async writeOkfTrust(entryId, entityId, verified) {
@@ -8657,6 +8867,8 @@ function createWiki(db, options) {
 exports.DEFAULT_CHUNK_OVERLAP = DEFAULT_CHUNK_OVERLAP;
 exports.DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT = DEFAULT_LIBRARIAN_SYNTHESIS_PROMPT;
 exports.DEFAULT_MAX_CHUNK_LENGTH = DEFAULT_MAX_CHUNK_LENGTH;
+exports.DEFAULT_MAX_EMBED_CHARS = DEFAULT_MAX_EMBED_CHARS;
+exports.EMBED_CHARS_CEILING = EMBED_CHARS_CEILING;
 exports.HEAL_ANCHORS_PER_CANDIDATE = HEAL_ANCHORS_PER_CANDIDATE;
 exports.HEAL_BATCH_SIZE = HEAL_BATCH_SIZE;
 exports.HEAL_MAX_FACT_BODY_CHARS_L3 = HEAL_MAX_FACT_BODY_CHARS_L3;
@@ -8672,6 +8884,7 @@ exports.PrunePartialFailureError = PrunePartialFailureError;
 exports.WikiBusyError = WikiBusyError;
 exports.WikiDuplicateHashError = WikiDuplicateHashError;
 exports.WikiIngestEmptyError = WikiIngestEmptyError;
+exports.WikiInvalidReadOptions = WikiInvalidReadOptions;
 exports.WikiMemory = WikiMemory;
 exports.WikiParseError = WikiParseError;
 exports.WikiSourceRefHashCollision = WikiSourceRefHashCollision;