@orkastery/cli 0.4.3 → 0.5.0

package/assets/orkmind_bridge.py

@@ -1,4 +1,4 @@
-"""Transporte de fabrica: OrkMind instalado, stdin JSON, sem provider ou embedder."""
+"""Transporte de fabrica: OrkMind instalado, stdin JSON; embedder so na operacao embed (I-38)."""
 from __future__ import annotations
 import asyncio
 import contextlib
@@ -6,7 +6,9 @@ import hashlib
 import io
 import json
 import logging
+import math
 import os
+import re
 import sys
 
 
@@ -188,6 +190,205 @@ def query_contract(request):
     return {k: list(v) for k, v in tags.items()}, request['collection'], limit
 
 
+# I-38 (D1, D4, D8): a chave de embedding chega so ao ambiente desta operacao, com este nome.
+EMBED_KEY_ENV = 'ORKMIND_EMBEDDING_API_KEY'
+EMBED_TIMEOUT_S = 10.0
+EMBED_MAX_TEXTS = 32
+EMBED_MAX_CHARS = 24000
+LOCAL_MAX_TOKENS = 8192
+MODEL_NAME = re.compile(r'[A-Za-z0-9][A-Za-z0-9._-]*/[A-Za-z0-9][A-Za-z0-9._-]*')
+# Mesmos padroes da policy segredo_em_prompt, mais URL com credencial: recusados antes da rede.
+SECRET_PATTERNS = [re.compile(p) for p in (
+    r'sk-ant-[A-Za-z0-9_-]{16,}', r'sk-or-v1-[A-Za-z0-9]{32,}', r'\bsk-[A-Za-z0-9]{32,}\b',
+    r'\bAKIA[0-9A-Z]{16}\b', r'\bgh[pousr]_[A-Za-z0-9]{20,}\b', r'-----BEGIN (?:[A-Z ]+ )?PRIVATE KEY-----',
+    r'(?i)\b(?:api[_-]?key|secret|token|senha|password)\s*[:=]\s*[\'"][^\'"\s]{16,}[\'"]',
+    r'\b[a-z][a-z0-9+.-]*://[^\s/:@]+:[^\s/@]+@')]
+
+
+def embed_contract(request):
+    valid = isinstance(request, dict) and set(request) == {'op', 'papel', 'alvo', 'modelo', 'dim', 'textos'}
+    textos = request.get('textos') if valid else None
+    dim = request.get('dim') if valid else None
+    if (not valid or request['papel'] not in ('consulta', 'documento')
+            or request['alvo'] not in ('primario', 'fallback')
+            or not isinstance(request['modelo'], str) or MODEL_NAME.fullmatch(request['modelo']) is None
+            or type(dim) is not int or not 32 <= dim <= 4096
+            or not isinstance(textos, list) or not 1 <= len(textos) <= EMBED_MAX_TEXTS
+            or any(not isinstance(t, str) or not t.strip() or len(t) > EMBED_MAX_CHARS for t in textos)):
+        raise QueryError('memory.embed.invalid')
+
+
+def model_prefix(modelo, papel):
+    """Instrucao de uso do proprio modelo; o conteudo da entrada vai inteiro depois dela."""
+    nome = modelo.lower().split('/')[-1]
+    if nome.startswith('qwen3-embedding'):
+        return ('Instruct: Given a search query, retrieve relevant memory entries that answer the query\nQuery:'
+                if papel == 'consulta' else '')
+    if re.search(r'(^|[-_])e5([-_]|$)', nome):
+        return 'query: ' if papel == 'consulta' else 'passage: '
+    return ''
+
+
+async def embed_primary(modelo, dim, textos):
+    if not os.environ.get(EMBED_KEY_ENV, '').strip():
+        raise QueryError('embeddings.chave-ausente')
+    import httpx
+    from orkmind.embeddings.provider import OpenRouterEmbeddingProvider
+    provider = OpenRouterEmbeddingProvider(api_key_env=EMBED_KEY_ENV, model=modelo, embedding_dim=dim,
+                                           timeout_s=EMBED_TIMEOUT_S, request_dimensions=True)
+    try:
+        return await provider.embed_batch(textos)
+    except Exception as error:
+        # Nunca repassar texto do provider: ele pode ecoar a entrada ou o cabecalho.
+        cause = error.__cause__ or error
+        raise QueryError('embeddings.timeout' if isinstance(cause, httpx.TimeoutException)
+                         else 'embeddings.provider-indisponivel') from None
+
+
+def local_model_dir(modelo):
+    """Pasta do modelo no cache local, sem rede. None quando nao foi baixado."""
+    os.environ['HF_HUB_OFFLINE'] = '1'
+    os.environ['TRANSFORMERS_OFFLINE'] = '1'
+    try:
+        from huggingface_hub import snapshot_download
+    except ImportError:
+        raise QueryError('embeddings.dependencia-ausente') from None
+    try:
+        return snapshot_download(modelo, local_files_only=True)
+    except Exception:
+        return None
+
+
+def local_pooling(pasta):
+    from pathlib import Path
+    modules = Path(pasta, 'modules.json')
+    if modules.exists() and any('Dense' in m.get('type', '') for m in json.loads(modules.read_text())):
+        raise QueryError('embeddings.dimensao-divergente')
+    config = Path(pasta, '1_Pooling', 'config.json')
+    modos = json.loads(config.read_text()) if config.exists() else {}
+    return ('lasttoken' if modos.get('pooling_mode_lasttoken') else
+            'cls' if modos.get('pooling_mode_cls_token') else 'mean')
+
+
+class LocalEmbeddingProvider:
+    """Fallback local (D4): mesma interface do EmbeddingProvider da biblioteca, offline, em CPU."""
+
+    def __init__(self, modelo):
+        pasta = local_model_dir(modelo)
+        if pasta is None:
+            raise QueryError('embeddings.local-ausente')
+        try:
+            import torch
+            from transformers import AutoModel, AutoTokenizer
+        except ImportError:
+            raise QueryError('embeddings.dependencia-ausente') from None
+        torch.set_num_threads(min(4, os.cpu_count() or 1))
+        self._torch = torch
+        self._pooling = local_pooling(pasta)
+        self._tokenizer = AutoTokenizer.from_pretrained(
+            pasta, local_files_only=True, padding_side='left' if self._pooling == 'lasttoken' else 'right')
+        self._model = AutoModel.from_pretrained(pasta, local_files_only=True)
+        self._model.eval()
+        self._dim = int(self._model.config.hidden_size)
+        self._max = min(int(getattr(self._tokenizer, 'model_max_length', LOCAL_MAX_TOKENS) or LOCAL_MAX_TOKENS),
+                        LOCAL_MAX_TOKENS)
+        # Texto acima do contexto do modelo local e embedado pelo comeco e DECLARADO (nunca em silencio).
+        self.truncados = []
+
+    @property
+    def dim(self):
+        return self._dim
+
+    async def embed(self, text):
+        return (await self.embed_batch([text]))[0]
+
+    async def embed_batch(self, texts):
+        torch = self._torch
+        self.truncados = [i for i, ids in enumerate(self._tokenizer(texts, truncation=False)['input_ids'])
+                          if len(ids) > self._max]
+        lote = self._tokenizer(texts, padding=True, truncation=True, max_length=self._max, return_tensors='pt')
+        with torch.inference_mode():
+            saida = self._model(**lote).last_hidden_state
+        if self._pooling == 'lasttoken':
+            vetores = saida[:, -1]
+        elif self._pooling == 'cls':
+            vetores = saida[:, 0]
+        else:
+            mascara = lote['attention_mask'].unsqueeze(-1).to(saida.dtype)
+            vetores = (saida * mascara).sum(1) / mascara.sum(1).clamp(min=1e-9)
+        return torch.nn.functional.normalize(vetores, p=2, dim=1).tolist()
+
+
+async def embed(request):
+    """Operacao embed: unica que instancia embedder; nao toca a base nem recebe a DSN."""
+    embed_contract(request)
+    textos = request['textos']
+    if any(p.search(t) for p in SECRET_PATTERNS for t in textos):
+        raise QueryError('embeddings.conteudo-recusado')
+    prefixo = model_prefix(request['modelo'], request['papel'])
+    entrada = [prefixo + t for t in textos]
+    truncados = []
+    if request['alvo'] == 'primario':
+        vetores = await embed_primary(request['modelo'], request['dim'], entrada)
+    else:
+        local = LocalEmbeddingProvider(request['modelo'])
+        vetores = await local.embed_batch(entrada)
+        truncados = list(local.truncados)
+    # A biblioteca nao confere a dimensao devolvida (D8): a ponte confere vetor a vetor.
+    if (not isinstance(vetores, list) or len(vetores) != len(textos)
+            or any(not isinstance(v, list) or len(v) != request['dim']
+                   or not all(isinstance(x, float) and math.isfinite(x) for x in v) for v in vetores)):
+        raise QueryError('embeddings.dimensao-divergente')
+    return {'alvo': request['alvo'], 'modelo': request['modelo'], 'dim': request['dim'], 'truncados': truncados,
+            'vetores': [[round(x, 7) for x in v] for v in vetores]}
+
+
+def health_contract(request):
+    if not isinstance(request, dict) or set(request) != {'op'}:
+        raise QueryError('memory.health.invalid')
+
+
+async def health(store):
+    """Sonda barata (I-38 T4): contagens, versao da biblioteca e dependencias do fallback, sem rede nem torch."""
+    import importlib.metadata
+    import importlib.util
+    # Versao e dependencias sao informacao, nao saude: falha nelas nunca derruba o regime.
+    try:
+        versao = importlib.metadata.version('orkmind')
+    except Exception:
+        versao = None
+    def presente(modulo):
+        try:
+            return importlib.util.find_spec(modulo) is not None
+        except Exception:
+            return False
+    dependencias = all(presente(m) for m in ('torch', 'transformers', 'huggingface_hub'))
+    return {'contagens': {c: await store.count(c) for c in await store.list_collections()},
+            'orkmind': versao, 'fallback': {'dependencias': dependencias}}
+
+
+ORK_COLLECTIONS = ('decision', 'handoff', 'rule', 'learning', 'roadmap')
+
+
+def fts_contract(request):
+    valid = isinstance(request, dict) and set(request) == {'op', 'tenant', 'texto'}
+    def text(value, maximum):
+        return isinstance(value, str) and 0 < len(value.strip()) and len(value) <= maximum and re.search(r'[\x00-\x1f\x7f]', value) is None
+    if not valid or not text(request['tenant'], 128) or not text(request['texto'], 2000):
+        raise QueryError('memory.fts.invalid')
+
+
+async def fts(request, store):
+    """FTS da biblioteca (I-38 D9) com fronteira de tenant obrigatoria: devolve so ids, na ordem do ranking."""
+    # A janela cobre a base inteira: ausencia so conta quando nada ficou de fora do corte.
+    limit = await store.count() + 1
+    entries = await store.search_by_text(request['texto'], limit=limit)
+    if len(entries) >= limit:
+        raise QueryError('memory.query.window-saturated')
+    return {'ids': [e.id for e in entries if e.collection in ORK_COLLECTIONS
+                    and request['tenant'] in (e.tags or {}).get('project', [])]}
+
+
 async def execute(request, store):
     from orkmind.core.models import MemoryEntry
     from orkmind.core.semantic_layer import SemanticLayer
@@ -196,6 +397,12 @@ async def execute(request, store):
     op = request['op']
     if op == 'stats':
         return {c: await store.count(c) for c in await store.list_collections()}
+    if op == 'health':
+        health_contract(request)
+        return await health(store)
+    if op == 'fts':
+        fts_contract(request)
+        return await fts(request, store)
     if op == 'query':
         tags, collection, limit = query_contract(request)
         # GovernedStore conserva validade, anti-injection e visibilidade existentes.
@@ -323,8 +530,14 @@ async def main(request):
             return {'schema':'orkmind.company-brain-api/v1','state':'conflict','error':'brain.api.invalid'}
         from orkmind.cli.company_brain import service_request
         return service_request(request['request'])
+    if isinstance(request, dict) and request.get('op') == 'embed':
+        return await embed(request)
     if isinstance(request, dict) and request.get('op') == 'query':
         query_contract(request)
+    if isinstance(request, dict) and request.get('op') == 'health':
+        health_contract(request)
+    if isinstance(request, dict) and request.get('op') == 'fts':
+        fts_contract(request)
     native_schema_fields()
     from orkmind.core.config import OrkMindConfig
     from orkmind.store.factory import create_store

package/dist/adapters/claude-bg.js

@@ -102,8 +102,9 @@ const CONSULTAS_MCP = [
     'mcp__orkastery__ork_artifact_read',
     'mcp__orkastery__ork_claims_list',
 ];
+// RM-037 (defeito 1): a decisao autonoma pelo MCP tem o mesmo grant nos dois runtimes.
 const MUTACOES_WORKTREE = [
-    'mcp__orkastery__ork_artifact_write', 'mcp__orkastery__ork_claim_add',
+    'mcp__orkastery__ork_artifact_write', 'mcp__orkastery__ork_claim_add', 'mcp__orkastery__ork_decision_record',
     'mcp__orkastery__ork_git_commit', 'mcp__orkastery__ork_verify', 'mcp__orkastery__ork_ship',
 ];
 /** Regras nativas de arquivo, nao sandbox de processos. Edit tambem cobre Write. */
@@ -154,8 +155,10 @@ function montarComando(pedido) {
         // Somente o servidor gerado: nao mesclar MCP de outros escopos nesta sessao filha.
         const permissoes = contexto.permissoesFilho === 'worktree'
             ? permissoesDaWorktree(pedido.cwd, contexto.permiteEditarProduto && !plano) : null;
-        // PLAN não implementa: nem commit, nem claim, nem verify, nem ship, em nenhum perfil.
-        const allow = plano ? [...CONSULTAS_MCP, 'mcp__orkastery__ork_artifact_write'] : permissoes?.allow ?? [...CONSULTAS_MCP];
+        // PLAN não implementa: nem commit, nem claim, nem verify, nem ship, em nenhum perfil. Decidir não é
+        // implementar, e o PLAN é onde as decisões nascem (RM-037, achado S7 do CHECK): a decisão autônoma fica.
+        const allow = plano ? [...CONSULTAS_MCP, 'mcp__orkastery__ork_artifact_write', 'mcp__orkastery__ork_decision_record']
+            : permissoes?.allow ?? [...CONSULTAS_MCP];
         const deny = [...(plano ? ESCRITA_DE_ARQUIVO : []), ...(permissoes?.deny ?? [])];
         args.push('--plugin-dir', contexto.instalacao, '--strict-mcp-config', '--mcp-config', JSON.stringify({ mcpServers: { orkastery: contexto.servidor } }), '--allowedTools', allow.join(','));
         if (deny.length)

package/dist/board.js

@@ -50,6 +50,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.perfisDetectados = perfisDetectados;
 exports.threadsDeTodosOsPerfis = threadsDeTodosOsPerfis;
 exports.estadosDeSessao = estadosDeSessao;
+exports.vagaDoDespacho = vagaDoDespacho;
+exports.esperarVaga = esperarVaga;
 exports.planejar = planejar;
 exports.devolverVagas = devolverVagas;
 exports.textoDoReap = textoDoReap;
@@ -123,6 +125,78 @@ function estadosDeSessao() {
         .filter((s) => !!s.sessionId)
         .map((s) => [s.sessionId, (0, hitl_1.estadoBruto)(s)]));
 }
+/**
+ * RM-037 (rm037defeito, defeito 3): o portao de vaga do `ork phase run`. Com `max_parallel_threads: 5`,
+ * um sexto despacho saiu as 09h03 de 29/09/2026 com cinco sessoes vivas: o `phase run` nao consultava
+ * vaga nenhuma, e o escalonador so via as sessoes `claude agents` de uma conta.
+ *
+ * Ocupa vaga a outra thread cuja conducao `exec:<thread>` e de uma sessao viva (a prova que vale para
+ * claude-bg de qualquer conta e para codex, liberada por `phase_result`, `sessao_morta` ou
+ * `session_superseded`), salvo a sessao parada ou escalada para o humano (`sessaoLivreDaVaga`; achados A1 e
+ * N1 do CHECK: a pausa prevista e o verify reprovado nao param a sessao, e ela segue contando). Ocupa tambem o
+ * despacho em curso de outra thread (conducao de processo do `phase.run` ou do `retry.run`), senao dois
+ * pedidos simultaneos passariam juntos. A conducao da propria thread tem portao proprio. Somente leitura.
+ */
+function vagaDoDespacho(carregado, threadId, quando = (0, util_1.agora)(), 
+/** S-5 do CHECK 3: o `desde` da tomada deste despacho; despacho em curso de outra thread so conta se veio antes. */
+desdeProprio) {
+    const { raiz, manifesto } = carregado;
+    const limite = Math.max(1, manifesto.concurrency.max_parallel_threads);
+    const staleMin = manifesto.concurrency.stale_after_min;
+    const ocupam = [];
+    for (const id of (0, thread_1.listarIds)(raiz)) {
+        if (id === threadId)
+            continue;
+        let atual = null;
+        try {
+            atual = (0, conducao_1.conducaoDaThread)(raiz, id);
+        }
+        catch {
+            continue;
+        }
+        if (!atual)
+            continue;
+        const despachando = atual.dono.tipo === 'processo' && (atual.operacao === 'phase.run' || atual.operacao === 'retry.run');
+        if (atual.dono.tipo !== 'sessao' && !despachando)
+            continue;
+        // Dois despachos disputando a ultima vaga nao se recusam um ao outro: quem tomou antes fica com ela.
+        if (despachando && desdeProprio && (atual.desde > desdeProprio || (atual.desde === desdeProprio && id > threadId)))
+            continue;
+        if (atual.dono.tipo === 'sessao') {
+            try {
+                if ((0, ocupacao_1.sessaoLivreDaVaga)((0, ledger_1.lerLedger)((0, thread_1.dirThread)(raiz, id)), atual.desde, quando, staleMin, atual.dono.sessionId))
+                    continue;
+            }
+            catch { /* ledger ilegivel: a conducao viva continua contando */ }
+        }
+        ocupam.push({ thread: id, fase: atual.fase, desde: atual.desde,
+            sessao: atual.dono.tipo === 'sessao' ? atual.dono.sessionId : null,
+            runtime: atual.dono.tipo === 'sessao' ? atual.dono.runtime : null });
+    }
+    if (ocupam.length < limite)
+        return null;
+    ocupam.sort((a, b) => a.desde.localeCompare(b.desde));
+    return {
+        limite,
+        ocupam,
+        detalhe: `concurrency.limite: o projeto ja tem ${ocupam.length} sessao(oes) viva(s) em outras threads e o limite e ${limite} ` +
+            `(concurrency.max_parallel_threads): ${ocupam.map((o) => `${o.thread} ${o.fase ?? '-'} ` +
+                (o.sessao ? `${o.runtime} ${o.sessao.slice(0, 8)}` : 'despacho em curso')).join('; ')}`,
+        correcao: 'espere uma sessao terminar e repita com --esperar <min>; sessao que morreu sem evento sai com ' +
+            'ork conducao status <thread>; ou suba concurrency.max_parallel_threads no orkastery.yaml',
+    };
+}
+/** `--esperar`: espera a vaga do projeto ate o prazo. Devolve true quando ha vaga. */
+function esperarVaga(carregado, threadId, esperarMs) {
+    const prazo = Date.now() + esperarMs;
+    for (;;) {
+        if (!vagaDoDespacho(carregado, threadId))
+            return true;
+        if (Date.now() >= prazo)
+            return false;
+        (0, conducao_1.dormir)(Math.min(2000, prazo - Date.now()));
+    }
+}
 /**
  * Escalonador por maquina: decide quem avanca agora e quem espera, com motivo tipado.
  *

package/dist/branch-de-estado.js

@@ -79,8 +79,8 @@ function pontaLocal(raiz, remoto, branch) {
  * Traz a ponta da branch. `ponta: null` quando ela ainda nao existe no remoto; sem rede, a ultima
  * copia local com `atualizado: false`.
  */
-function buscarBranch(raiz, remoto, branch, prefixo, timeoutMs) {
-    const r = git(raiz, ['fetch', '--quiet', '--no-tags', remoto, `+refs/heads/${branch}:${(0, exports.refRemota)(remoto, branch)}`], { timeoutMs });
+function buscarBranch(raiz, remoto, branch, prefixo, timeoutMs, env) {
+    const r = git(raiz, ['fetch', '--quiet', '--no-tags', remoto, `+refs/heads/${branch}:${(0, exports.refRemota)(remoto, branch)}`], { timeoutMs, env });
     if (r.ok)
         return { ponta: exigirGit(raiz, ['rev-parse', '--verify', (0, exports.refRemota)(remoto, branch)], prefixo).trim(), atualizado: true };
     if (/couldn't find remote ref|could not find remote ref/i.test(r.stderr)) {
@@ -102,7 +102,7 @@ function jsonsDaPonta(raiz, ponta, dir, prefixo) {
  * Grava uma versao nova da branch em cima de `ponta`, sem tocar arvore de trabalho nem indice:
  * indice temporario, blobs, `write-tree` e `commit-tree`. Push sem forca; recusa volta `false`.
  */
-function gravarNaBranch(raiz, remoto, branch, ponta, mudancas, mensagem, prefixo) {
+function gravarNaBranch(raiz, remoto, branch, ponta, mudancas, mensagem, prefixo, rede = {}) {
     const indice = path.join(fs.mkdtempSync(path.join(os.tmpdir(), 'ork-branch-estado-')), 'index');
     const env = { GIT_INDEX_FILE: indice };
     try {
@@ -121,7 +121,8 @@ function gravarNaBranch(raiz, remoto, branch, ponta, mudancas, mensagem, prefixo
         }
         const arvore = exigirGit(raiz, ['write-tree'], prefixo, { env }).trim();
         const commit = exigirGit(raiz, ['commit-tree', arvore, ...(ponta ? ['-p', ponta] : []), '-m', mensagem], prefixo).trim();
-        const push = git(raiz, ['push', '--quiet', remoto, `${commit}:refs/heads/${branch}`]);
+        // `rede`: prazo e ambiente so do que vai a rede (RM-037, achado A3: o fechamento nao espera 60 s).
+        const push = git(raiz, ['push', '--quiet', remoto, `${commit}:refs/heads/${branch}`], rede);
         if (push.ok) {
             git(raiz, ['update-ref', (0, exports.refRemota)(remoto, branch), commit]);
             return commit;

package/dist/busca-semantica.js

@@ -0,0 +1,161 @@
+"use strict";
+/**
+ * I-38 (T5, D7, D9): busca por significado na memoria do tenant.
+ *
+ * E ACRESCIMO, nunca troca (P2 do GOAL): o recall e a injecao de prompt continuam so por tag,
+ * deterministicos. Esta busca e superficie separada e todo resultado sai com
+ * `deterministico: false`.
+ *
+ * O universo e o export governado do tenant (filtro de injecao e visibilidade da biblioteca):
+ *  - vetor: cosseno da consulta contra o indice local do MESMO modelo e dimensao, so para
+ *    entradas com sha256 coerente; nunca compara vetores de espacos diferentes;
+ *  - FTS: `search_by_text` da biblioteca, filtrado por tenant na ponte e intersectado aqui;
+ *  - fusao: RRF com k = 60.
+ * A cadeia do vetor e primario, fallback local, nenhum; sem vetor, cai para FTS com motivo tipado.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CANDIDATOS_DO_VETOR = exports.LIMITE_MAXIMO_DA_BUSCA = exports.LIMITE_PADRAO_DA_BUSCA = exports.RRF_K = exports.MODOS_DE_BUSCA = void 0;
+exports.cosseno = cosseno;
+exports.fundirRrf = fundirRrf;
+exports.buscarPorSignificado = buscarPorSignificado;
+const indice_vetorial_1 = require("./indice-vetorial");
+exports.MODOS_DE_BUSCA = ['hibrido', 'vetor', 'fts'];
+/** D9: constante da fusao RRF. */
+exports.RRF_K = 60;
+exports.LIMITE_PADRAO_DA_BUSCA = 10;
+exports.LIMITE_MAXIMO_DA_BUSCA = 100;
+/** Candidatos do lado vetorial que entram na fusao. */
+exports.CANDIDATOS_DO_VETOR = 50;
+function cosseno(a, b) {
+    let ab = 0, aa = 0, bb = 0;
+    for (let i = 0; i < a.length; i++) {
+        ab += a[i] * b[i];
+        aa += a[i] * a[i];
+        bb += b[i] * b[i];
+    }
+    return aa === 0 || bb === 0 ? 0 : ab / Math.sqrt(aa * bb);
+}
+/** RRF: soma de 1 / (k + posicao) em cada lista em que o id aparece (posicao comeca em 1). */
+function fundirRrf(listas, k = exports.RRF_K) {
+    const scores = new Map();
+    for (const lista of listas)
+        lista.forEach((id, i) => scores.set(id, (scores.get(id) ?? 0) + 1 / (k + i + 1)));
+    return scores;
+}
+const resumo = (conteudo) => conteudo.split('\n')[0].slice(0, 100);
+/** Lado vetorial: o primeiro caminho da cadeia que tem indice, responde e fala o mesmo espaco. */
+function ladoVetorial(o) {
+    const detalhes = [];
+    let motivo = null;
+    const falhar = (alvo, m, d) => {
+        if (!motivo)
+            motivo = m;
+        detalhes.push(`${alvo}: ${m} (${d})`);
+    };
+    if (o.config.provider === 'none') {
+        return { alvo: null, modelo: null, ranking: [], motivo: 'embeddings.nao-configurado', detalhes: ['memory.embedding.provider none'] };
+    }
+    const base = (0, indice_vetorial_1.impressaoDaBase)(o.dsn);
+    for (const alvo of ['primario', 'fallback']) {
+        if (alvo === 'primario' && !o.chavePresente) {
+            falhar(alvo, 'embeddings.chave-ausente', 'variavel declarada fora do ambiente');
+            continue;
+        }
+        if (alvo === 'fallback' && !o.config.fallback_model) {
+            falhar(alvo, 'embeddings.nao-configurado', 'fallback_model vazio');
+            continue;
+        }
+        const espaco = (0, indice_vetorial_1.espacoDoAlvo)(o.config, alvo, o.env);
+        if ('motivo' in espaco) {
+            falhar(alvo, espaco.motivo, espaco.detalhe);
+            continue;
+        }
+        if (alvo === 'fallback' && !o.fallbackUsavel) {
+            falhar(alvo, 'embeddings.dependencia-ausente', 'torch/transformers ausentes na ponte');
+            continue;
+        }
+        const lido = (0, indice_vetorial_1.lerIndice)((0, indice_vetorial_1.arquivoDoIndice)(o.raiz, o.tenant, espaco.modelo, espaco.dim), { tenant: o.tenant, base, modelo: espaco.modelo, dim: espaco.dim });
+        if (lido.outroEspaco) {
+            falhar(alvo, 'embeddings.espaco-vetorial-divergente', 'arquivo de indice de outro modelo, dimensao ou base');
+            continue;
+        }
+        if (!lido.existia) {
+            falhar(alvo, 'embeddings.indice-ausente', `rode ork memory index --modelo ${alvo}`);
+            continue;
+        }
+        if (!o.embeddar) {
+            falhar(alvo, 'embeddings.provider-indisponivel', 'transporte de embedding ausente');
+            continue;
+        }
+        let resposta;
+        try {
+            resposta = o.embeddar({ papel: 'consulta', alvo, modelo: espaco.modelo, dim: espaco.dim, textos: [o.texto] }, { timeoutMs: o.timeoutMs });
+        }
+        catch (erro) {
+            falhar(alvo, (0, indice_vetorial_1.codigoDeEmbedding)(erro), 'a consulta nao foi embedada');
+            continue;
+        }
+        const vetor = resposta?.vetores?.[0];
+        // Nunca comparar espacos diferentes: modelo e dimensao da consulta precisam ser os do indice.
+        if (resposta?.modelo !== lido.indice.modelo || resposta?.dim !== lido.indice.dim || !Array.isArray(vetor) || vetor.length !== lido.indice.dim) {
+            falhar(alvo, 'embeddings.espaco-vetorial-divergente', 'consulta e indice de modelos ou dimensoes diferentes');
+            continue;
+        }
+        if (resposta.truncados?.length)
+            detalhes.push(`${alvo}: consulta acima do contexto do modelo, embedada pelo comeco`);
+        const ranking = [...(0, indice_vetorial_1.vetoresCoerentes)(lido.indice, o.universo)]
+            .map(([id, v]) => ({ id, sim: cosseno(vetor, v) }))
+            .sort((a, b) => b.sim - a.sim || a.id.localeCompare(b.id));
+        return { alvo, modelo: espaco.modelo, ranking, motivo, detalhes };
+    }
+    return { alvo: null, modelo: null, ranking: [], motivo, detalhes };
+}
+/** `ork memory search --texto`: ranking hibrido, nunca deterministico, sempre dentro do tenant. */
+function buscarPorSignificado(o) {
+    const universo = o.universo.filter(e => (e.tags.project ?? []).includes(o.tenant));
+    const porId = new Map(universo.map(e => [e.id, e]));
+    const saida = { texto: o.texto, modo: o.modo, origem: 'nenhum', modeloUsado: null,
+        deterministico: false, motivo: null, detalhe: '', resultados: [], listas: { vetor: [], fts: [] } };
+    const detalhes = [];
+    let similaridade = new Map();
+    if (o.modo !== 'fts') {
+        const v = ladoVetorial({ ...o, universo });
+        detalhes.push(...v.detalhes);
+        saida.motivo = v.motivo;
+        if (v.alvo) {
+            saida.origem = v.alvo;
+            saida.modeloUsado = v.modelo;
+            const candidatos = v.ranking.slice(0, exports.CANDIDATOS_DO_VETOR);
+            saida.listas.vetor = candidatos.map(c => c.id);
+            similaridade = new Map(candidatos.map(c => [c.id, c.sim]));
+        }
+    }
+    if (o.modo !== 'vetor') {
+        try {
+            if (!o.buscarTexto)
+                throw new Error('memory.transport.fts');
+            // A ponte ja filtra o tenant; a intersecao com o universo governado vale de novo aqui.
+            saida.listas.fts = [...new Set(o.buscarTexto(o.tenant, o.texto))].filter(id => porId.has(id));
+        }
+        catch (erro) {
+            const codigo = /^[a-z]+(?:\.[a-z-]+)+/.exec(erro instanceof Error ? erro.message : '')?.[0] ?? 'memory.transport.fts';
+            detalhes.push(`fts: ${codigo}`);
+            if (o.modo === 'fts' || saida.origem === 'nenhum')
+                saida.motivo = saida.motivo ?? codigo;
+        }
+        if (saida.origem === 'nenhum' && !detalhes.some(d => d.startsWith('fts:')))
+            saida.origem = 'fts';
+    }
+    const scores = fundirRrf([saida.listas.vetor, saida.listas.fts]);
+    saida.resultados = [...scores]
+        .sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
+        .slice(0, o.limite)
+        .map(([id, score]) => ({
+        id, collection: porId.get(id).collection, score: Math.round(score * 1e6) / 1e6,
+        fontes: [...(saida.listas.vetor.includes(id) ? ['vetor'] : []), ...(saida.listas.fts.includes(id) ? ['fts'] : [])],
+        similaridade: similaridade.has(id) ? Math.round(similaridade.get(id) * 1e4) / 1e4 : null,
+        resumo: resumo(porId.get(id).content),
+    }));
+    saida.detalhe = detalhes.join('; ');
+    return saida;
+}