@johpaz/hive-sdk 0.3.1 → 0.4.0

package/README.md

@@ -230,4 +230,4 @@ npm view @johpaz/hive-sdk dist-tags   # verificar después del release
 
 ---
 
-*Hive SDK v0.3.1 — MIT*
+*Hive SDK v0.4.0 — MIT*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johpaz/hive-sdk",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "private": false,
   "description": "Hive SDK — The Agent Harness SDK. Build, deploy, and scale AI agent applications with multi-channel support, context engineering, and swarm orchestration.",
   "license": "MIT",

package/packages/core/src/agent/capability-search.ts

@@ -20,6 +20,7 @@
 
 import type { IndexDoc } from "@johpaz/hive-db";
 import { getHiveDb } from "../storage/hivedb.ts";
+import { currentTenant, qualifyDocId, unqualifyDocId, scopedFilterValue } from "../storage/tenant.ts";
 import { logger } from "../utils/logger.ts";
 
 const log = logger.child("capability-search");
@@ -87,12 +88,19 @@ export async function searchCapabilities(
 
   // Filters are AND-ed by the engine, so multi-type search runs one query per
   // type; the single-type and all-types cases are one engine call.
+  //
+  // El índice semántico es UNO solo para todos los inquilinos (no hay
+  // "colección" que prefijar), así que el tenant entra como un filtro más que
+  // el motor AND-ea con el resto. Sin tenant no se añade nada: así un índice ya
+  // construido por la app de escritorio sigue respondiendo igual.
+  const tenant = currentTenant();
+  const tenantFilter = tenant ? [{ field: "tenant", value: tenant }] : [];
   const queries = types
     ? types.map((t) => ({
         type: t,
-        filters: [{ field: "type", value: t }],
+        filters: [...tenantFilter, { field: "type", value: t }],
       }))
-    : [{ type: undefined, filters: undefined }];
+    : [{ type: undefined, filters: tenantFilter.length ? tenantFilter : undefined }];
 
   const merged = new Map<string, CapabilityHit>();
   for (const q of queries) {
@@ -103,12 +111,15 @@ export async function searchCapabilities(
       boosts: opts.boosts,
     });
     for (const hit of hits) {
-      const parsed = splitId(hit.id);
+      // El id indexado lleva el prefijo del tenant; quien consume esto espera
+      // el id canónico ("tool:web_search"), no la forma física.
+      const id = unqualifyDocId(hit.id);
+      const parsed = splitId(id);
       if (!parsed) continue;
-      const existing = merged.get(hit.id);
+      const existing = merged.get(id);
       if (!existing || hit.score > existing.score) {
-        merged.set(hit.id, {
-          id: hit.id,
+        merged.set(id, {
+          id,
           type: parsed.type,
           rawId: parsed.rawId,
           score: hit.score,
@@ -154,7 +165,15 @@ export async function replaceCapabilityDocs(
   docs: CapabilityDoc[]
 ): Promise<void> {
   const db = await getHiveDb();
-  await db.deleteByFilter({ field: "type", value: type });
+  // `deleteByFilter` acepta UN SOLO filtro, así que en una base compartida
+  // borrar por `type` se llevaría por delante los documentos de todos los
+  // inquilinos. El campo sintético `tenant__type` (ver scopedFilterValue)
+  // mantiene el borrado en un filtro y acotado a este tenant.
+  await db.deleteByFilter(
+    currentTenant()
+      ? { field: "tenant__type", value: scopedFilterValue(type) }
+      : { field: "type", value: type }
+  );
   if (docs.length === 0) return;
   await db.upsertBatch(docs.map(toIndexDoc));
 }
@@ -169,18 +188,38 @@ export async function upsertCapabilityDocs(docs: CapabilityDoc[]): Promise<void>
 /** Delete every MCP doc belonging to a server (hot-reload/disconnect). */
 export async function deleteCapabilitiesByServer(serverId: string): Promise<void> {
   const db = await getHiveDb();
-  await db.deleteByFilter({ field: "server_id", value: serverId });
+  await db.deleteByFilter(
+    currentTenant()
+      ? { field: "tenant__server_id", value: scopedFilterValue(serverId) }
+      : { field: "server_id", value: serverId }
+  );
 }
 
 function toIndexDoc(doc: CapabilityDoc): IndexDoc {
+  const extra = doc.extraFilters ?? [];
+  const tenant = currentTenant();
   return {
-    id: `${doc.type}:${doc.rawId}`,
+    id: qualifyDocId(`${doc.type}:${doc.rawId}`),
     name: doc.name,
     body: doc.body,
     tags: doc.tags,
     filters: [
       { field: "type", value: doc.type },
-      ...(doc.extraFilters ?? []),
+      ...extra,
+      // Con tenant activo, cada filtro lleva además un gemelo `tenant__<campo>`.
+      // Es lo que permite que los borrados masivos —que sólo aceptan un
+      // filtro— sigan acotados a este inquilino. Sin tenant no se emite nada,
+      // así que un índice ya construido conserva exactamente su forma.
+      ...(tenant
+        ? [
+            { field: "tenant", value: tenant },
+            { field: "tenant__type", value: scopedFilterValue(doc.type) },
+            ...extra.map((f) => ({
+              field: `tenant__${f.field}`,
+              value: scopedFilterValue(f.value),
+            })),
+          ]
+        : []),
     ],
   };
 }

package/packages/core/src/agent/context-compiler.ts

@@ -37,8 +37,8 @@ import { resolveUserId } from "../storage/onboarding.ts"
 import { getMCPManager as getSingletonMCPManager } from "../mcp/singleton.ts"
 import { syncMCPToolsToDB, syncMCPToolsToIndex } from "../mcp/tool-sync.ts"
 import { getUserDate, getUserTime } from "../utils/date.ts"
-import { loadConfig } from "../config/loader.ts"
 import { getHiveDb } from "../storage/hivedb.ts"
+import { causalReadsEnabled } from "../storage/causal-events.ts"
 import { listCatalogAgents, renderAgentRoutingCatalog } from "./catalog-selector.ts"
 import { expandToolAllowlist } from "./delegation-runtime.ts"
 import { MINIMAL_TOOLS } from "./minimal-loadout.ts"
@@ -588,7 +588,7 @@ export async function compileContext(opts: {
   // applies this turn (a real DB round-trip, not a per-turn cost) and
   // there's a causal stream to build it from. episodicSimilarity is omitted:
   // it requires embeddings hive doesn't generate anywhere yet.
-  if (summaryApplies && opts.causalStreamId && loadConfig().causalLog?.enabled) {
+  if (summaryApplies && opts.causalStreamId && causalReadsEnabled()) {
     try {
       const causalDb = await getHiveDb()
       const objectiveSource = taskContext || userMessage

package/packages/core/src/agent/conversation-store.ts

@@ -6,7 +6,6 @@
  */
 
 import { col, nextId, bumpRollup } from "../storage/hive.ts"
-import { getHiveDb } from "../storage/hivedb.ts"
 import { logger } from "../utils/logger.ts"
 import type { LLMMessage, ContentPart } from "./llm-client.ts"
 import { estimateTokens } from "../utils/toon.ts"
@@ -478,8 +477,9 @@ function scratchpadNoteId(threadId: string, key: string): string {
 }
 
 async function scratchpadCollection() {
-  const db = await getHiveDb()
-  return db.collection<ScratchpadDoc>("scratchpad")
+  // Vía `col()` y no `db.collection()` a pelo: es lo que aplica el prefijo de
+  // tenant y mantiene las notas de cada enjambre en su propia partición.
+  return col<ScratchpadDoc>("scratchpad")
 }
 
 export async function saveScratchpadNote(

package/packages/core/src/agent/reflector.ts

@@ -14,7 +14,7 @@
 import { logger } from "../utils/logger.ts"
 import { col, nextId } from "../storage/hive.ts"
 import { getHiveDb } from "../storage/hivedb.ts"
-import { loadConfig } from "../config/loader.ts"
+import { causalReadsEnabled } from "../storage/causal-events.ts"
 import type { HiveDB, ToolStats } from "@johpaz/hive-db"
 import type { TraceDoc, ReflectionDoc, CursorDoc } from "../storage/collections.ts"
 import { parseThreadId } from "./thread-id.ts"
@@ -70,7 +70,7 @@ export async function runReflector(): Promise<void> {
     // G9: when enabled, per-tool insights use whole-history stats from HiveDB's
     // event log (toolStats) instead of counters built from just this batch, and
     // causal threads add root-cause/learning-proposal insights on top.
-    const causalDb = loadConfig().causalLog?.enabled ? await getHiveDb() : null
+    const causalDb = causalReadsEnabled() ? await getHiveDb() : null
     const reflectionsCol = await col<ReflectionDoc>("reflections")
     let totalInsights = 0
 

package/packages/core/src/services/models.ts

@@ -16,6 +16,7 @@
  */
 
 import { col, toIndexable, fromIndexable } from "../storage/hive.ts";
+import { qualify } from "../storage/tenant.ts";
 import { getHiveDb } from "../storage/hivedb.ts";
 import type { BatchOp } from "@johpaz/hive-db";
 import type { ModelDoc, AgentDoc } from "../storage/collections.ts";
@@ -161,12 +162,17 @@ export async function renameModel(id: string, nuevoNombre: string): Promise<Mode
   const afectados = await agentesCol.findBy("model_id", toIndexable(id));
 
   const db = await getHiveDb();
+  // `batch()` va contra el handle crudo de la base, así que no pasa por `col()`:
+  // los nombres de colección hay que resolverlos contra el tenant a mano o el
+  // rename escribiría en la partición de otro inquilino.
+  const MODELS = qualify("models");
+  const AGENTS = qualify("agents");
   const ops: BatchOp[] = [
-    { op: "put", collection: "models", id: nuevoId, doc },
-    ...(nuevoId !== id ? [{ op: "delete" as const, collection: "models", id }] : []),
+    { op: "put", collection: MODELS, id: nuevoId, doc },
+    ...(nuevoId !== id ? [{ op: "delete" as const, collection: MODELS, id }] : []),
     ...afectados.map((a) => ({
       op: "put" as const,
-      collection: "agents",
+      collection: AGENTS,
       id: a.id,
       doc: { ...a.doc, model_id: toIndexable(nuevoId), updated_at: Date.now() },
       expectedVersion: a.version,

package/packages/core/src/storage/bootstrap.ts

@@ -13,6 +13,7 @@
 
 import { getHiveDb, getOpenHiveDb } from "./hivedb.ts";
 import { col } from "./hive.ts";
+import { currentTenant } from "./tenant.ts";
 import { seedAllData, type SeedOptions } from "./seed.ts";
 import { ensureSecretsBackend } from "./crypto.ts";
 import { ensureLegacyThread } from "../agent/thread-store.ts";
@@ -136,6 +137,16 @@ async function ensureSeedData(opts?: SeedOptions): Promise<void> {
 // tests or long-running processes open a fresh instance in the same runtime.
 let bootstrappedDb: Awaited<ReturnType<typeof getHiveDb>> | null = null;
 
+// ...y, dentro de esa instancia, a un tenant concreto. Una sola base compartida
+// por muchos enjambres significa que "ya arrancó" no es una propiedad de la
+// base: el enjambre A puede tener sus 72 índices creados y el B ninguno.
+const bootstrappedTenants = new Set<string>();
+
+/** Clave de bootstrap del tenant activo ("_" en modo local/escritorio). */
+function bootstrapScope(): string {
+  return currentTenant() ?? "_";
+}
+
 /**
  * Antes de la separación por canal todos los canales compartían un solo hilo cuyo
  * `thread_id` era el `userId`. Esa conversación se registra —sin mover un solo
@@ -223,6 +234,16 @@ async function ensureLegacyThreads(): Promise<void> {
  */
 export async function ensureHiveDb(opts?: SeedOptions): Promise<void> {
   const db = await getHiveDb();
+  if (db !== bootstrappedDb) bootstrappedTenants.clear();
+  const scope = bootstrapScope();
+
+  // Con varios inquilinos en la misma base, esto se llama una vez por enjambre
+  // y por proceso, no una vez por proceso: repetir los ~72 `createIndex` más el
+  // seed en cada llamada es exactamente el coste que la consolidación viene a
+  // quitar. En modo local (sin tenant) no se cortocircuita nada, para conservar
+  // el "reseed en cada arranque" del que dependen los cambios de catálogo.
+  if (currentTenant() && bootstrappedDb === db && bootstrappedTenants.has(scope)) return;
+
   await ensureIndexes();
   // Mint the master key before anything can save an API key, so a fresh
   // install is durable from the first keystroke rather than after a restart
@@ -239,8 +260,13 @@ export async function ensureHiveDb(opts?: SeedOptions): Promise<void> {
   if (!existing) await meta.put("schemaVersion", { value: 1 }, { expectedVersion: 0 });
 
   bootstrappedDb = db;
+  bootstrappedTenants.add(scope);
 }
 
 export function isBootstrapped(): boolean {
-  return bootstrappedDb !== null && bootstrappedDb === getOpenHiveDb();
+  return (
+    bootstrappedDb !== null &&
+    bootstrappedDb === getOpenHiveDb() &&
+    bootstrappedTenants.has(bootstrapScope())
+  );
 }

package/packages/core/src/storage/causal-events.ts

@@ -7,10 +7,30 @@
  */
 
 import { getHiveDb } from "./hivedb.ts"
+import { currentTenant } from "./tenant.ts"
+import { loadConfig } from "../config/loader.ts"
 import type { Event, EventPattern } from "@johpaz/hive-db"
 
 export type { Event as CausalEvent, EventPattern as CausalEventPattern }
 
+/**
+ * ¿Se pueden hacer lecturas AGREGADAS del log causal en este contexto?
+ *
+ * `causalThread`, `buildAgentContext` y `toolStats` recorren todos los shards
+ * de la base y mezclan sus resultados (`log.rs` — `read_stream_all_agents` y
+ * `project::<P>()` para proyecciones con scope Agent). Sobre una base
+ * compartida eso devolvería hilos y estadísticas de otros inquilinos. Mientras
+ * el motor no exponga las variantes acotadas por agente, con un tenant activo
+ * estas lecturas se apagan: perder una señal de reflexión es aceptable, cruzar
+ * datos entre agencias no.
+ *
+ * La ESCRITURA (`append`) no entra aquí: va al shard del propio agente, y los
+ * agentes de Hive Cloud ya llevan el enjambre en el id.
+ */
+export function causalReadsEnabled(): boolean {
+  return !!loadConfig().causalLog?.enabled && !currentTenant()
+}
+
 /**
  * Live-tail causal events matching `pattern`. Forward-only: only events
  * appended AFTER this call resolves are delivered. hive-db's subscribe()/
@@ -32,6 +52,16 @@ export type { Event as CausalEvent, EventPattern as CausalEventPattern }
 export async function watchCausalEvents(
   pattern: EventPattern
 ): Promise<AsyncIterable<Event> & { close(): void }> {
+  // El log de eventos no tiene colecciones que prefijar: el aislamiento entre
+  // inquilinos lo da el shard por `agentId`. Un patrón sin `agentId` sobre una
+  // base compartida entregaría los eventos de todos los enjambres, así que se
+  // exige explícitamente en vez de filtrar a medias.
+  if (currentTenant() && !pattern.agentId) {
+    throw new Error(
+      "watchCausalEvents: con un tenant activo el patrón debe fijar agentId; " +
+        "un tail sin agente cruzaría eventos de otros inquilinos."
+    )
+  }
   const db = await getHiveDb()
   return db.events(pattern)
 }

package/packages/core/src/storage/hive.ts

@@ -8,6 +8,7 @@
  */
 
 import { getHiveDb } from "./hivedb.ts";
+import { qualify } from "./tenant.ts";
 
 const MAX_RETRIES = 5;
 
@@ -32,9 +33,22 @@ export function fromIndexable(value: string | null | undefined): string | null {
   return value === NO_PARENT || value == null ? null : value;
 }
 
+/**
+ * Handle a una colección, resuelta contra el tenant activo.
+ *
+ * `qualify()` es lo que aísla a los inquilinos entre sí en una base compartida
+ * (ver storage/tenant.ts). Sin tenant en scope devuelve el nombre pelado, así
+ * que el modo local se comporta igual que siempre. Como todo el CRUD del SDK
+ * pasa por aquí —incluidos `nextId`, `updateDoc`, `updateManyByIndex`,
+ * `findByAny` y `bumpRollup`, más abajo— este es el único punto que hay que
+ * mantener honesto.
+ *
+ * El handle se construye en cada llamada a propósito: cachearlo en una variable
+ * de módulo lo dejaría atado al tenant que lo creó primero.
+ */
 export async function col<T>(name: string) {
   const db = await getHiveDb();
-  return db.collection<T>(name);
+  return db.collection<T>(qualify(name));
 }
 
 /**

package/packages/core/src/storage/index.ts

@@ -11,6 +11,22 @@
 export { getHiveDbPath, getHiveDb, closeHiveDb } from "./hivedb.ts";
 export { ensureHiveDb, isBootstrapped } from "./bootstrap.ts";
 
+// ─── Aislamiento multi-inquilino ─────────────────────────────────────────────
+// Varios enjambres dentro de una sola HiveDB, prefijando el nombre de colección.
+// Sin tenant en scope todo se comporta como siempre — ver storage/tenant.ts.
+export {
+  runInTenant,
+  currentTenant,
+  requireTenant,
+  tenantKeyFromId,
+  isTenantKey,
+  qualify,
+  unqualify,
+  qualifyDocId,
+  unqualifyDocId,
+  scopedFilterValue,
+} from "./tenant.ts";
+
 // ─── Acceso a colecciones ────────────────────────────────────────────────────
 export {
   col,

package/packages/core/src/storage/reconcile.ts

@@ -85,13 +85,19 @@ export async function reconcileOnBoot(bootId: string): Promise<ReconcileResult>
     log.warn(`[reconcileOnBoot] Failed to repair meetings: ${(err as Error).message}`);
   }
 
-  // 3. agentRuns: any "running" row is orphaned at boot — HiveDB is
-  // single-process and this process just started, so no run can actually be
-  // executing. Waiting out the lease would leave fast restarts (< lease
-  // duration) unrepaired forever.
+  // 3. agentRuns: a "running" row is orphaned if it belongs to ANOTHER boot.
+  //
+  // Antes bastaba con mirar el estado: una base por enjambre más un proceso por
+  // turno garantizaban que al arrancar no podía haber ninguna corrida viva. Con
+  // la base compartida entre inquilinos esa premisa desaparece —este proceso
+  // atiende varios enjambres a la vez— y barrer por estado abortaría corridas
+  // realmente en vuelo. El `boot_id` de la fila es lo que distingue "muerta en
+  // un proceso anterior" de "viva aquí y ahora".
   try {
     const agentRunsCol = await col<AgentRunDoc>("agentRuns");
-    const runningRuns = await agentRunsCol.findBy("status", "running");
+    const runningRuns = (await agentRunsCol.findBy("status", "running")).filter(
+      (entry) => entry.doc.boot_id !== bootId
+    );
     for (const entry of runningRuns) {
       const run = entry.doc;
 
@@ -124,11 +130,13 @@ export async function reconcileOnBoot(bootId: string): Promise<ReconcileResult>
     log.warn(`[reconcileOnBoot] Failed to repair agentRuns: ${(err as Error).message}`);
   }
 
-  // 4. jobQueue: any "running" row is orphaned at boot (same single-process
-  // argument as above) → reclaim (pending) or interrupt, ignoring the lease.
+  // 4. jobQueue: mismo criterio que arriba — sólo las filas de otro boot están
+  // realmente huérfanas → reclaim (pending) o interrupt, ignorando el lease.
   try {
     const jobsCol = await col<JobDoc>("jobQueue");
-    const runningJobs = await jobsCol.findBy("status", "running");
+    const runningJobs = (await jobsCol.findBy("status", "running")).filter(
+      (entry) => entry.doc.boot_id !== bootId
+    );
     for (const entry of runningJobs) {
       const job = entry.doc;
       const result_doc = await reclaimOrInterrupt(job.id, { force: true });

package/packages/core/src/storage/tenant.ts

@@ -0,0 +1,147 @@
+/**
+ * Contexto de tenant — aislamiento de varios enjambres dentro de UNA sola HiveDB.
+ *
+ * Hive Cloud creaba una base física por enjambre porque `getHiveDb()` es un
+ * singleton de proceso: para aislar dos enjambres había que aislar dos procesos.
+ * Aquí el aislamiento pasa a ser lógico, prefijando el nombre de la colección.
+ *
+ * El prefijo va en el NOMBRE DE COLECCIÓN y no en el id del documento a
+ * propósito. Las colecciones de HiveDB no son tablas separadas: son tres tablas
+ * redb con el nombre de colección como primera componente de una clave
+ * compuesta (`col_docs:(collection,id)`, `col_index_entries:(collection,field,
+ * value,id)`). Prefijar el nombre sale casi gratis y, sobre todo, aísla también
+ * los índices secundarios — que es justo lo que un prefijo en el id NO consigue,
+ * porque `findBy(field, value)` recorre el índice de la colección entera y
+ * devolvería filas de otros tenants.
+ *
+ * Sin tenant en scope `qualify()` es la identidad, así que la app de escritorio
+ * y los tests siguen viendo exactamente los mismos nombres de colección que
+ * antes. `HIVE_TENANT_REQUIRED=1` invierte esa tolerancia para los despliegues
+ * multi-inquilino: una ruta que se olvide de entrar al contexto falla ruidosa en
+ * la primera colección que toque, en vez de escribir en silencio fuera de su
+ * partición.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+interface TenantContext {
+  key: string;
+}
+
+const storage = new AsyncLocalStorage<TenantContext>();
+
+/** Separador entre el tenant y el nombre de colección. */
+const SEP = "__";
+
+/**
+ * `t_` + un uuid sin guiones. Corta a propósito: la clave se repite en cada
+ * entrada de `col_docs` y de `col_index_entries`, así que cada carácter de más
+ * se paga por documento y por entrada de índice.
+ */
+const KEY_PATTERN = /^t_[a-z0-9]{8,48}$/;
+
+/**
+ * Separador de los filtros escalares compuestos del índice BM25. U+001F (unit
+ * separator) porque el motor construye el término como `field<US>value` y ese
+ * byte no aparece nunca en un id ni en un tipo real.
+ */
+const FILTER_SEP = "\u001f";
+
+/** Construye una tenant key válida a partir de un uuid (o cualquier id opaco). */
+export function tenantKeyFromId(id: string): string {
+  const normalized = id.toLowerCase().replace(/[^a-z0-9]/g, "");
+  if (normalized.length < 8) {
+    throw new Error(`tenantKeyFromId: id demasiado corto para ser único: "${id}"`);
+  }
+  return `t_${normalized.slice(0, 48)}`;
+}
+
+/** `true` si la cadena tiene forma de tenant key. */
+export function isTenantKey(value: string): boolean {
+  return KEY_PATTERN.test(value);
+}
+
+/**
+ * Ejecuta `fn` con `key` como tenant activo. Todo lo que `fn` haga por debajo
+ * —incluidos los `await` encadenados— ve ese tenant; dos llamadas concurrentes
+ * no se pisan porque cada una corre en su propio contexto de AsyncLocalStorage.
+ *
+ * Ojo: el contexto NO cruza a un `Worker`. Ningún código que corra dentro de un
+ * worker puede tocar HiveDB esperando estar aislado.
+ */
+export function runInTenant<T>(key: string, fn: () => T): T {
+  if (!isTenantKey(key)) {
+    throw new Error(`runInTenant: tenant key inválida "${key}" (esperado ${KEY_PATTERN})`);
+  }
+  return storage.run({ key }, fn);
+}
+
+/** Tenant activo, o `null` si no hay ninguno (modo local/escritorio). */
+export function currentTenant(): string | null {
+  return storage.getStore()?.key ?? null;
+}
+
+/** Tenant activo; lanza si no hay. Para código que sólo tiene sentido aislado. */
+export function requireTenant(context: string): string {
+  const key = currentTenant();
+  if (!key) {
+    throw new Error(`${context} requiere un tenant activo (envolver en runInTenant)`);
+  }
+  return key;
+}
+
+/**
+ * Nombre físico de una colección para el tenant activo.
+ *
+ * Es el único punto por el que pasa el aislamiento documental: `col()` lo llama
+ * y con eso quedan cubiertos los ~300 sitios que hacen CRUD, más `nextId`,
+ * `updateDoc`, `updateManyByIndex`, `findByAny` y `bumpRollup`.
+ */
+export function qualify(collection: string): string {
+  const key = currentTenant();
+  if (key) return `${key}${SEP}${collection}`;
+  if (process.env.HIVE_TENANT_REQUIRED === "1") {
+    throw new Error(
+      `qualify("${collection}"): HIVE_TENANT_REQUIRED=1 y no hay tenant en scope. ` +
+        `Falta envolver esta ruta en runInTenant().`
+    );
+  }
+  return collection;
+}
+
+/**
+ * Quita el prefijo de tenant de un nombre de colección físico. Devuelve el
+ * nombre tal cual si no lo lleva.
+ */
+export function unqualify(collection: string): string {
+  const match = /^t_[a-z0-9]{8,48}__(.+)$/.exec(collection);
+  return match ? match[1] : collection;
+}
+
+/**
+ * Id de documento para el índice semántico (BM25), que es UNO solo compartido
+ * por todos los tenants: ahí el aislamiento va en el id y en los filtros, no en
+ * un nombre de colección.
+ */
+export function qualifyDocId(id: string): string {
+  const key = currentTenant();
+  return key ? `${key}:${id}` : id;
+}
+
+/** Inversa de {@link qualifyDocId}, para devolver ids limpios en los hits. */
+export function unqualifyDocId(id: string): string {
+  const match = /^t_[a-z0-9]{8,48}:(.+)$/.exec(id);
+  return match ? match[1] : id;
+}
+
+/**
+ * Valor de un filtro escalar compuesto para el índice BM25.
+ *
+ * Hace falta porque `deleteByFilter` acepta UN SOLO filtro: un borrado masivo
+ * por `type` en una base compartida se llevaría por delante los documentos de
+ * todos los tenants. Con un campo sintético (`tenant__type`) el borrado vuelve a
+ * ser de un solo filtro y sigue estando acotado al tenant.
+ */
+export function scopedFilterValue(...parts: string[]): string {
+  return [currentTenant() ?? "_", ...parts].join(FILTER_SEP);
+}