wendkeep 0.85.1 → 0.86.0

package/CHANGELOG.md

@@ -4,6 +4,32 @@ All notable changes to **wendkeep** are documented here. Format based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project follows
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.86.0] — 2026-08-28
+
+### Added
+
+- **Memory ledger bounded para Vaults longos.** Snapshots determinísticos, replay apenas do tail,
+  segmentos imutáveis com manifest encadeado e rotação/compactação transacional preservam a
+  autoridade append-only, com dry-run, journal, receipt, recovery e benchmarks sintéticos de
+  100 mil eventos.
+- **Recall incremental, paginado e indexado.** Estado por documento/chunk, cursor vinculado ao
+  índice/consulta/filtros/`as_of`, budgets UTF-8 exatos, sidecar lexical bounded e SQLite FTS5
+  opcional evitam scans integrais sem transformar artefatos derivados em autoridade; o MCP expõe
+  a mesma leitura paginada e bounded.
+- **Contrato opcional de embeddings locais.** `wendkeep/vault` exporta manifest versionado,
+  integrity-bound e in-process para reranquear somente um prefixo de candidatos; fica desligado
+  por padrão, proíbe rede/retenção, limita batch/bytes, preserva proveniência e degrada para a
+  ordem lexical sem incluir modelo, provider ou vector database no Core.
+
+### Changed
+
+- **Saúde de escala no `doctor` e Observer.** Snapshots operacionais publicam somente contagens,
+  bytes, atualidade, backend e estados sanitizados de memória/recall, sem rebuild, leitura do
+  corpus ou vazamento de termos e paths.
+- **Fechamento coordenado da issue #82.** A PR agregadora #124 reconcilia os slices #111–#123,
+  mantém documentação PT-BR/EN e tarball em paridade e alinha package/lock/CHANGELOG para a
+  entrega minor única.
+
 ## [0.85.1] — 2026-08-25
 
 ### Fixed

package/README.en.md

@@ -250,6 +250,7 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 | **Portable state** | `portable status/export/import/diff`, authored/runtime boundary, redaction, and the `active-work` snapshot | [Portable state](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/portable.md) |
 | **Local-first sync** | `sync status/push/pull/conflicts/resolve`, revision/CAS, outbox, leases, and explicit conflicts | [Sync protocol](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/sync-protocol.md) |
 | **Native MCP** | semantic tools, effects/capabilities, stdio, schemas, pagination, budgets, audit, and client configuration | [Native MCP](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/mcp.md) |
+| **Evidence recall and embeddings** | cursor/byte budgets, bounded lexical/FTS sidecars, and an optional local plugin contract that is off by default | [Optional embedding plugin](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/evidence-embeddings.md) |
 | **Host capabilities** | versioned lifecycle/effect matrix, degraded mode, human waivers, and evidence/Observer coverage | [Host capabilities](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/capabilities.md) |
 | **Operating profiles** | `profile`, `flow`, always-on Keep Core, and Wend Runtime governance | [Operating profiles](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/operating-profiles.md) |
 | **Changes and verification** | `change`, specs, sensors, TDD, evidence, Task Contracts, and archive | [Changes and verification](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/changes-and-verification.md) |
@@ -665,7 +666,7 @@ The archive **gate** blocks unless: the change scaffold is filled (G0), no task
 ## Notes & roadmap
 
 - **Vault folder names default to Portuguese** (`02-Sessões`, `04-Decisões`, …). Pass `wendkeep init --locale en` for an English vault (`02-Sessions`, `04-Decisions`, English scaffold/skills). The locale is a vault property, locked at init; parsers are bilingual so mixed content never breaks.
-- **Search is keyword/frontmatter scoring**, not on‑device embeddings (that's on the roadmap).
+- **Default recall remains local lexical/FTS.** Embeddings require an explicitly supplied trusted local plugin with forbidden network access, budgets, and lexical fallback; Core ships no model or provider.
 - **Transcript formats are agent‑internal** and can change between agent versions; parsing is isolated but may need updates.
 - Installer wires **both agents**: `.claude/settings.json` + `.mcp.json` for Claude Code, `.codex/hooks.json` for Codex. **Eight Codex hooks are compatible**; `change-guard` validates the project lease in `PreToolUse` and denies mutations outside it. The four hooks without an equivalent remain Claude-only: `change-warn`, `plan-capture`, `decision-capture`, and `task-log`.
 - **Codex hooks start untrusted.** They are enumerated but not executed until you approve the “Hooks need review” prompt; `init` cannot pre‑approve them (`--dangerously-bypass-hook-trust` is per‑invocation and stores no trusted hash). Trust is keyed to the hook's identity, so hand‑written wendkeep Codex hooks predating `0.46.0` — which ran at the 600s default because they used `timeout` instead of `timeoutSec` — cost one re‑review after `init` corrects the key. Expected, not a regression. `import --source codex` still backfills past Codex sessions either way.

package/README.md

@@ -250,6 +250,7 @@ The README is the map; the guides provide syntax, options, exit codes, examples,
 | **Portable state** | `portable status/export/import/diff`, authored/runtime boundary, redaction, and the `active-work` snapshot | [Portable state](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/portable.md) |
 | **Local-first sync** | `sync status/push/pull/conflicts/resolve`, revision/CAS, outbox, leases, and explicit conflicts | [Sync protocol](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/sync-protocol.md) |
 | **Native MCP** | semantic tools, effects/capabilities, stdio, schemas, pagination, budgets, audit, and client configuration | [Native MCP](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/mcp.md) |
+| **Evidence recall and embeddings** | cursor/byte budgets, bounded lexical/FTS sidecars, and an optional local plugin contract that is off by default | [Optional embedding plugin](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/evidence-embeddings.md) |
 | **Host capabilities** | versioned lifecycle/effect matrix, degraded mode, human waivers, and evidence/Observer coverage | [Host capabilities](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/capabilities.md) |
 | **Operating profiles** | `profile`, `flow`, always-on Keep Core, and Wend Runtime governance | [Operating profiles](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/operating-profiles.md) |
 | **Changes and verification** | `change`, specs, sensors, TDD, evidence, Task Contracts, and archive | [Changes and verification](https://github.com/rogersialves/wendkeep/blob/main/docs/en/commands/changes-and-verification.md) |
@@ -665,7 +666,7 @@ The archive **gate** blocks unless: the change scaffold is filled (G0), no task
 ## Notes & roadmap
 
 - **Vault folder names default to Portuguese** (`02-Sessões`, `04-Decisões`, …). Pass `wendkeep init --locale en` for an English vault (`02-Sessions`, `04-Decisions`, English scaffold/skills). The locale is a vault property, locked at init; parsers are bilingual so mixed content never breaks.
-- **Search is keyword/frontmatter scoring**, not on‑device embeddings (that's on the roadmap).
+- **Default recall remains local lexical/FTS.** Embeddings require an explicitly supplied trusted local plugin with forbidden network access, budgets, and lexical fallback; Core ships no model or provider.
 - **Transcript formats are agent‑internal** and can change between agent versions; parsing is isolated but may need updates.
 - Installer wires **both agents**: `.claude/settings.json` + `.mcp.json` for Claude Code, `.codex/hooks.json` for Codex. **Eight Codex hooks are compatible**; `change-guard` validates the project lease in `PreToolUse` and denies mutations outside it. The four hooks without an equivalent remain Claude-only: `change-warn`, `plan-capture`, `decision-capture`, and `task-log`.
 - **Codex hooks start untrusted.** They are enumerated but not executed until you approve the “Hooks need review” prompt; `init` cannot pre‑approve them (`--dangerously-bypass-hook-trust` is per‑invocation and stores no trusted hash). Trust is keyed to the hook's identity, so hand‑written wendkeep Codex hooks predating `0.46.0` — which ran at the 600s default because they used `timeout` instead of `timeoutSec` — cost one re‑review after `init` corrects the key. Expected, not a regression. `import --source codex` still backfills past Codex sessions either way.

package/docs/en/commands/evidence-embeddings.md

@@ -0,0 +1,243 @@
+# Optional evidence embedding plugin
+
+[Português](../../pt-BR/commands/evidence-embeddings.md)
+
+## Purpose
+
+Define a programmatic boundary for local semantic reranking without adding a model, ML runtime,
+vector database, HTTP client, or provider dependency to WendKeep Core.
+
+This surface is **not a CLI command**. It is exported by `wendkeep/vault` for local plugins that are
+explicitly supplied by the application's composition root.
+
+## When to use
+
+Use this API when a trusted composition root needs to rerank a small candidate set already filtered
+by lexical/FTS recall while keeping the model and adapter outside Core.
+
+Embeddings are disabled by default.
+
+```js
+const result = await rerankEvidenceCandidatesWithEmbedding(rows, query);
+// result.metrics.status === 'disabled'
+```
+
+Core does not:
+
+- discover plugins in `node_modules`;
+- execute `import()` from Vault configuration;
+- download models;
+- open network connections;
+- persist vectors;
+- hand the full corpus to a plugin.
+
+A plugin receives data only when the caller supplies the plugin object and sets `enabled: true`.
+
+## When not to use
+
+Do not use the plugin as an authoritative index, a scope-expansion mechanism, a code autoloader, or
+a replacement for lexical filters/recall. Do not use a remote provider either: the contract requires
+local in-process execution with no network and no retention.
+
+### Authority contract
+
+Authority remains ordered as follows:
+
+```text
+Vault Markdown/JSONL → incremental index → lexical/FTS candidates → optional reranking
+```
+
+The plugin operates only on a bounded prefix of already-filtered candidates. It cannot:
+
+- make its index or cache authoritative;
+- silently broaden project, session, change, or logical-path scope;
+- hide `authority`, `validity`, or provenance;
+- remove unprocessed candidates—they remain at the end in their original order;
+- mutate the source objects returned by Core.
+
+## Prerequisites
+
+- a reviewed local plugin explicitly loaded by the application;
+- a model/configuration pinned by SHA-256 fingerprint;
+- explicit batch and byte budgets;
+- candidates already filtered by lexical/FTS recall.
+
+### Versioned manifest
+
+Use `buildEvidenceEmbeddingManifest()` to create the manifest and
+`createEvidenceEmbeddingPlugin()` to bind it to the `embed` function.
+
+Required fields:
+
+| Field | Rule |
+|---|---|
+| `schema_version` | `1` |
+| `protocol_version` | `1` |
+| `plugin_id` | stable local identifier |
+| `plugin_version` | adapter version |
+| `model_id` | model identifier |
+| `model_revision` | immutable revision used by the adapter |
+| `model_fingerprint` | `sha256:<64 hex>` for the effective model/configuration |
+| `dimensions` | 1 through 65536 |
+| `locality` | exactly `local` |
+| `transport` | exactly `in-process` |
+| `network` | exactly `forbidden` |
+| `retention` | exactly `none` |
+| `max_batch_size` | 1 through 512 documents |
+| `max_input_bytes` | 1 through 4 MiB |
+| `integrity` | hash of the canonical manifest payload |
+
+The manifest is declarative. Core cannot sandbox arbitrary JavaScript, so install only trusted local
+plugins and review their code. WendKeep prevents automatic loading and validates the contract before
+handing over any evidence, but it does not turn third-party code into trusted code.
+
+## Syntax
+
+```text
+buildEvidenceEmbeddingManifest(options)
+createEvidenceEmbeddingPlugin({ manifest, embed })
+verifyEvidenceEmbeddingPlugin(plugin)
+rerankEvidenceCandidatesWithEmbedding(rows, query, options)
+```
+
+## Examples
+
+```js
+import {
+  buildEvidenceEmbeddingManifest,
+  createEvidenceEmbeddingPlugin,
+  rerankEvidenceCandidatesWithEmbedding,
+} from 'wendkeep/vault';
+
+const manifest = buildEvidenceEmbeddingManifest({
+  plugin_id: 'local.my-embedding',
+  plugin_version: '1.0.0',
+  model_id: 'local.my-model',
+  model_revision: '2026.08.27',
+  model_fingerprint: 'sha256:<model-and-configuration-hash>',
+  dimensions: 384,
+  max_batch_size: 64,
+  max_input_bytes: 262144,
+});
+
+const plugin = createEvidenceEmbeddingPlugin({
+  manifest,
+  async embed(request, { signal }) {
+    // Local adapter: no network access and no text retention.
+    // Return exactly one query vector and one vector for every document.id.
+    return {
+      schema_version: 1,
+      model_fingerprint: manifest.model_fingerprint,
+      query_vector: await localModel.embed(request.query.text, { signal }),
+      document_vectors: await Promise.all(request.documents.map(async (document) => ({
+        id: document.id,
+        vector: await localModel.embed(document.text, { signal }),
+      }))),
+    };
+  },
+});
+
+const reranked = await rerankEvidenceCandidatesWithEmbedding(rows, query, {
+  enabled: true,
+  plugin,
+  maxCandidates: 64,
+  maxInputBytes: 262144,
+});
+```
+
+The request contains only:
+
+```json
+{
+  "schema_version": 1,
+  "model_fingerprint": "sha256:...",
+  "query": { "text": "..." },
+  "documents": [
+    { "id": "<chunk_id>", "text": "<title + heading + content>" }
+  ]
+}
+```
+
+`logical_path` is not sent to the plugin. Full provenance remains on the source objects and returns
+with the reranked order.
+
+## Expected result
+
+The response is fail-closed and may contain only:
+
+```json
+{
+  "schema_version": 1,
+  "model_fingerprint": "sha256:...",
+  "query_vector": [0.1, 0.2],
+  "document_vectors": [
+    { "id": "<chunk_id>", "vector": [0.3, 0.4] }
+  ]
+}
+```
+
+Core rejects:
+
+- dimensions that differ from the manifest;
+- `NaN`, infinity, or zero-norm vectors;
+- a divergent model fingerprint;
+- missing, duplicate, or unknown documents;
+- extra envelope fields;
+- a vector count that differs from the document count.
+
+The canonical adapter uses cosine similarity. Ties preserve the original order.
+
+## Options and exit codes
+
+The effective limit is always the lower value between caller and plugin manifest.
+
+- `maxCandidates`: default 128; maximum 512;
+- `maxInputBytes`: default 256 KiB; maximum 4 MiB;
+- documents that do not fit remain after the reranked prefix;
+- Core never sends a partial document;
+- a query or first document that cannot fit produces
+  `EVIDENCE_EMBEDDING_BUDGET_EXCEEDED`.
+
+With `required: false`—the default—a contract, budget, response, or execution failure returns the
+original lexical order and `metrics.status: "fallback"`. With `required: true`, the typed error is
+propagated.
+
+Main codes:
+
+- `EVIDENCE_EMBEDDING_PLUGIN_INVALID`;
+- `EVIDENCE_EMBEDDING_BUDGET_EXCEEDED`;
+- `EVIDENCE_EMBEDDING_RESPONSE_INVALID`;
+- `EVIDENCE_EMBEDDING_EXECUTION_FAILED`.
+
+## Safe operation
+
+1. Keep `enabled: false` until the plugin and model hash are verified.
+2. Run `verifyEvidenceEmbeddingPlugin(plugin)` before registering the adapter.
+3. Pin `plugin_version`, `model_revision`, and `model_fingerprint`; do not use mutable aliases such
+   as `latest`.
+4. Start with small budgets and compare the result against lexical/FTS recall.
+5. Record metrics only—IDs, counts, bytes, and timings—never query, text, or vectors.
+6. Treat a fingerprint change as a new generation of any plugin-owned cache.
+
+## Common errors and diagnosis
+
+When `metrics.status` is `fallback`:
+
+1. disable the plugin; lexical/FTS recall remains the safe route;
+2. validate the manifest and inspect `metrics.reason`;
+3. confirm dimensions, fingerprint, and vector count;
+4. discard only plugin-owned caches and rebuild them from `EVIDENCE_INDEX.jsonl` authority;
+5. never delete or edit `EVIDENCE_INDEX.jsonl`, Markdown, or Core sidecars to repair an embedding
+   provider;
+6. re-enable with `required: false` and promote to `required: true` only in an environment that
+   genuinely requires the provider.
+
+## Next steps
+
+This contract does not install a model or automatically add embeddings to MCP, doctor, or Observer.
+It defines the safe, testable boundary for a future sibling adapter. Core remains complete and
+functional without any plugin.
+
+Use the [Native MCP](mcp.md) guide for the existing paged/lexical surface and the
+[maintenance and diagnostics](maintenance-and-diagnostics.md) guide to inspect derived-artifact
+health without rebuilding it.

package/docs/en/commands/mcp.md

@@ -63,20 +63,71 @@ wendkeep mcp config --client cursor --vault <vault>
 ```
 
 Reads: `wendkeep_project_status`, `wendkeep_context_status`, `wendkeep_memory_recall`,
-`wendkeep_memory_conflicts`, `wendkeep_change_list`, `wendkeep_change_show`,
-`wendkeep_change_status`, `wendkeep_spec_effective`, `wendkeep_task_show`,
-`wendkeep_task_evaluate`, `wendkeep_handoff_current`, `wendkeep_evidence_latest`, and
-`wendkeep_observer_query`.
+`wendkeep_evidence_recall`, `wendkeep_memory_conflicts`, `wendkeep_change_list`,
+`wendkeep_change_show`, `wendkeep_change_status`, `wendkeep_spec_effective`,
+`wendkeep_task_show`, `wendkeep_task_evaluate`, `wendkeep_handoff_current`,
+`wendkeep_evidence_latest`, and `wendkeep_observer_query`.
 
 Writes: `wendkeep_memory_assert`, `wendkeep_checkpoint_create`, `wendkeep_context_select`,
 `wendkeep_task_claim`, `wendkeep_task_complete`, and `wendkeep_handoff_publish`.
 
+## Paged indexed evidence recall
+
+`wendkeep_evidence_recall` is the bounded surface for retrieving Vault evidence. It selects
+candidates through the persistent lexical sidecar or optional SQLite/FTS5, reranks them with the
+canonical scorer, and returns a compact page. `wendkeep_memory_recall` remains available as the
+legacy API and does not silently inherit the new contract.
+
+Main input:
+
+- `project_root` and `query` are required;
+- `limit` accepts 1 through 100 results per page;
+- `cursor` is opaque and is valid only for the same query, filters, and logical index;
+- `max_bytes` accepts 2 through 524288 and exactly bounds the serialized JSON in `results`; the
+  default is 64 KiB;
+- `candidate_limit` accepts 1 through 4096 candidates;
+- `posting_budget` accepts 1 through 1048576 visited postings;
+- `backend` accepts `auto`, `sqlite`, or `lexical`;
+- `filters` supports exact matches for `authority`, `validity`, `entity_type`, `project_id`,
+  `change_slug`, `session_id`, `work_session_id`, and `logical_path`, plus
+  `logical_path_prefix`. Each filter may be a string or a string list.
+
+Example call:
+
+```json
+{
+  "name": "wendkeep_evidence_recall",
+  "arguments": {
+    "project_root": "<project>",
+    "query": "authentication contract",
+    "limit": 5,
+    "max_bytes": 65536,
+    "candidate_limit": 512,
+    "posting_budget": 65536,
+    "backend": "auto",
+    "filters": {
+      "authority": "verified",
+      "validity": "active",
+      "logical_path_prefix": "04-Decisions/"
+    }
+  }
+}
+```
+
+The response contains `results`, `next_cursor`, `has_more`, `as_of`, and page counts/bytes. Each
+result omits `content`, reports `content_bytes`, retains a bounded `excerpt`, and replaces
+`logical_path` with `logical_ref`, a Vault-relative reference—never an absolute path. The
+`candidates` block exposes backend, count, postings, rebuild, and fallback metadata. When the
+candidate budget did not cover every possible match, `complete_candidate_set` is `false`; this
+prevents a consumer from treating a truncated selection as exhaustive.
+
 ## Expected result
 
 The handshake and `tools/list` return valid JSON-RPC. Every tool declares a versioned
 effect/capability and schemas. Known reads skip the mutation gate while retaining explicit
-project/worktree binding, cursor pagination, a 1 MiB default budget, redaction, timeout, and
-cancellation. Observer is declared unavailable below Node 22.13 without blocking Core on Node 18.
+project/worktree binding, cursor pagination, budgets, redaction, timeout, and cancellation.
+Observer is declared unavailable below Node 22.13 without blocking Core on Node 18. Indexed recall
+also works on Node 18 through the lexical fallback; SQLite/FTS5 remains optional.
 
 Writes require `project_root`, `session_id`, `active_context_id`, `actor`, `reason`, the exact
 capability, and `lease.id`/`lease.expires_at`; the executor revalidates causal authorization and CLI
@@ -89,8 +140,17 @@ outcome, code, and duration—never arguments or payloads.
 - `MCP_CAPABILITY_REQUIRED` / `MCP_SCOPE_AUTH_REQUIRED`: capability missing or unauthorized.
 - `MCP_LEASE_EXPIRED`: obtain a new authorization/lease; do not hand-edit its timestamp.
 - `MCP_PROJECT_SCOPE_MISMATCH`: `project_root` and `worktree_root` use different bindings.
-- `MCP_REQUEST_TOO_LARGE` / `MCP_RESPONSE_TOO_LARGE`: use `limit` and the returned cursor.
+- `MCP_REQUEST_TOO_LARGE` / `MCP_RESPONSE_TOO_LARGE`: reduce budgets and continue with the cursor.
 - `MCP_RUNTIME_UNSUPPORTED`: use Node 22.13+ for Observer; Core remains available.
+- `MCP_EVIDENCE_QUERY_REQUIRED`: provide a non-empty query.
+- `MCP_EVIDENCE_CURSOR_INVALID`: the cursor was altered, became stale, or was reused with a
+  different query/filter set.
+- `MCP_EVIDENCE_BUDGET_TOO_SMALL`: even the next result's minimum metadata cannot fit
+  `max_bytes`.
+- `MCP_EVIDENCE_BACKEND_UNAVAILABLE`: SQLite was required but FTS5 is unavailable; use `auto` or
+  `lexical`.
+- `MCP_EVIDENCE_ARTIFACT_UNSAFE`: a derived artifact violated the Vault's physical boundary.
+- `MCP_EVIDENCE_RECALL_INVALID`: a filter, backend, or limit is outside the contract.
 
 ## Next steps
 

package/docs/pt-BR/commands/evidence-embeddings.md

@@ -0,0 +1,244 @@
+# Plugin opcional de embeddings de evidências
+
+[English](../../en/commands/evidence-embeddings.md)
+
+## Objetivo
+
+Definir uma fronteira programática para reranqueamento semântico local sem adicionar modelo,
+runtime de ML, vector database, cliente HTTP ou dependência de provider ao Core do WendKeep.
+
+Esta superfície **não é um comando CLI**. Ela é exportada por `wendkeep/vault` para plugins locais
+carregados explicitamente pelo composition root da aplicação.
+
+## Quando usar
+
+Use esta API quando um composition root confiável precisar reranquear um conjunto pequeno de
+candidatos que o recall lexical/FTS já filtrou, mantendo o modelo e o adapter fora do Core.
+
+Embeddings ficam desligados por padrão.
+
+```js
+const result = await rerankEvidenceCandidatesWithEmbedding(rows, query);
+// result.metrics.status === 'disabled'
+```
+
+O Core:
+
+- não procura plugins em `node_modules`;
+- não executa `import()` a partir de configuração do Vault;
+- não baixa modelos;
+- não abre conexão de rede;
+- não persiste vetores;
+- não entrega o corpus inteiro ao plugin.
+
+Um plugin só recebe dados quando o chamador fornece o objeto do plugin e define `enabled: true`.
+
+## Quando não usar
+
+Não use o plugin como índice autoritativo, mecanismo de ampliação de escopo, autoload de código ou
+substituto para filtros/recall lexical. Também não use provider remoto: o contrato exige execução
+local, in-process, sem rede e sem retenção.
+
+### Contrato de autoridade
+
+A ordem de autoridade permanece:
+
+```text
+Markdown/JSONL do Vault → índice incremental → candidatos lexical/FTS → reranqueamento opcional
+```
+
+O plugin atua somente sobre um prefixo bounded de candidatos já filtrados. Ele não pode:
+
+- tornar seu índice ou cache a autoridade;
+- ampliar silenciosamente o escopo de projeto, sessão, change ou logical path;
+- ocultar `authority`, `validity` ou proveniência;
+- remover candidatos não processados — eles permanecem no final, na ordem original;
+- alterar os objetos-fonte retornados pelo Core.
+
+## Pré-requisitos
+
+- plugin local revisado e carregado explicitamente pela aplicação;
+- modelo/configuração fixados por fingerprint SHA-256;
+- budgets de batch e bytes definidos;
+- candidatos já filtrados pelo recall lexical/FTS.
+
+### Manifest versionado
+
+Use `buildEvidenceEmbeddingManifest()` para criar o manifest e
+`createEvidenceEmbeddingPlugin()` para vinculá-lo à função `embed`.
+
+Campos obrigatórios:
+
+| Campo | Regra |
+|---|---|
+| `schema_version` | `1` |
+| `protocol_version` | `1` |
+| `plugin_id` | identificador estável e local |
+| `plugin_version` | versão do adapter |
+| `model_id` | identificador do modelo |
+| `model_revision` | revisão imutável usada pelo adapter |
+| `model_fingerprint` | `sha256:<64 hex>` do modelo/configuração efetiva |
+| `dimensions` | 1 a 65536 |
+| `locality` | exatamente `local` |
+| `transport` | exatamente `in-process` |
+| `network` | exatamente `forbidden` |
+| `retention` | exatamente `none` |
+| `max_batch_size` | 1 a 512 documentos |
+| `max_input_bytes` | 1 a 4 MiB |
+| `integrity` | hash do payload canônico do manifest |
+
+O manifest é declarativo. JavaScript arbitrário não pode ser sandboxado pelo Core; portanto, instale
+somente plugins locais confiáveis e revise seu código. O WendKeep impede carregamento automático e
+valida o contrato antes de entregar qualquer evidência, mas não transforma código de terceiros em
+código confiável.
+
+## Sintaxe
+
+```text
+buildEvidenceEmbeddingManifest(options)
+createEvidenceEmbeddingPlugin({ manifest, embed })
+verifyEvidenceEmbeddingPlugin(plugin)
+rerankEvidenceCandidatesWithEmbedding(rows, query, options)
+```
+
+## Exemplos
+
+```js
+import {
+  buildEvidenceEmbeddingManifest,
+  createEvidenceEmbeddingPlugin,
+  rerankEvidenceCandidatesWithEmbedding,
+} from 'wendkeep/vault';
+
+const manifest = buildEvidenceEmbeddingManifest({
+  plugin_id: 'local.minha-embedding',
+  plugin_version: '1.0.0',
+  model_id: 'local.meu-modelo',
+  model_revision: '2026.08.27',
+  model_fingerprint: 'sha256:<hash-do-modelo-e-configuracao>',
+  dimensions: 384,
+  max_batch_size: 64,
+  max_input_bytes: 262144,
+});
+
+const plugin = createEvidenceEmbeddingPlugin({
+  manifest,
+  async embed(request, { signal }) {
+    // Adapter local: nenhum acesso de rede e nenhuma retenção de texto.
+    // Deve devolver exatamente uma query vector e um vector para cada document.id.
+    return {
+      schema_version: 1,
+      model_fingerprint: manifest.model_fingerprint,
+      query_vector: await localModel.embed(request.query.text, { signal }),
+      document_vectors: await Promise.all(request.documents.map(async (document) => ({
+        id: document.id,
+        vector: await localModel.embed(document.text, { signal }),
+      }))),
+    };
+  },
+});
+
+const reranked = await rerankEvidenceCandidatesWithEmbedding(rows, query, {
+  enabled: true,
+  plugin,
+  maxCandidates: 64,
+  maxInputBytes: 262144,
+});
+```
+
+O request contém somente:
+
+```json
+{
+  "schema_version": 1,
+  "model_fingerprint": "sha256:...",
+  "query": { "text": "..." },
+  "documents": [
+    { "id": "<chunk_id>", "text": "<title + heading + content>" }
+  ]
+}
+```
+
+`logical_path` não é enviado ao plugin. A proveniência completa permanece nos objetos-fonte e volta
+com a ordem reranqueada.
+
+## Resultado esperado
+
+A resposta é fail-closed e deve conter apenas:
+
+```json
+{
+  "schema_version": 1,
+  "model_fingerprint": "sha256:...",
+  "query_vector": [0.1, 0.2],
+  "document_vectors": [
+    { "id": "<chunk_id>", "vector": [0.3, 0.4] }
+  ]
+}
+```
+
+O Core rejeita:
+
+- dimensão diferente do manifest;
+- `NaN`, infinito ou vetor de norma zero;
+- fingerprint de modelo divergente;
+- documento ausente, duplicado ou desconhecido;
+- campos adicionais no envelope;
+- quantidade de vetores diferente da quantidade de documentos.
+
+A similaridade usada pelo adapter canônico é cosseno. Empates preservam a ordem original.
+
+## Opções e códigos de saída
+
+O limite efetivo é sempre o menor entre o chamador e o manifest do plugin.
+
+- `maxCandidates`: padrão 128; máximo 512;
+- `maxInputBytes`: padrão 256 KiB; máximo 4 MiB;
+- documentos que não couberem permanecem depois do prefixo reranqueado;
+- o Core nunca envia parcialmente um documento;
+- query ou primeiro documento que não cabem produzem
+  `EVIDENCE_EMBEDDING_BUDGET_EXCEEDED`.
+
+Com `required: false` — padrão — erro de contrato, budget, resposta ou execução devolve a ordem
+lexical original e `metrics.status: "fallback"`. Com `required: true`, o erro tipado é propagado.
+
+Códigos principais:
+
+- `EVIDENCE_EMBEDDING_PLUGIN_INVALID`;
+- `EVIDENCE_EMBEDDING_BUDGET_EXCEEDED`;
+- `EVIDENCE_EMBEDDING_RESPONSE_INVALID`;
+- `EVIDENCE_EMBEDDING_EXECUTION_FAILED`.
+
+## Operação segura
+
+1. Mantenha `enabled: false` até validar o plugin e o hash do modelo.
+2. Execute `verifyEvidenceEmbeddingPlugin(plugin)` antes de registrar o adapter.
+3. Fixe `plugin_version`, `model_revision` e `model_fingerprint`; não use alias mutável como
+   `latest`.
+4. Comece com budgets pequenos e compare a ordem com o recall lexical/FTS.
+5. Registre apenas métricas — IDs, contagens, bytes e tempos — nunca query, texto ou vetores.
+6. Trate mudança de fingerprint como uma geração nova de qualquer cache pertencente ao plugin.
+
+## Erros comuns e diagnóstico
+
+Quando `metrics.status` for `fallback`:
+
+1. desative o plugin; o recall lexical/FTS continua sendo a rota segura;
+2. valide o manifest e confira `metrics.reason`;
+3. confirme dimensão, fingerprint e quantidade dos vetores;
+4. descarte somente caches pertencentes ao plugin e reconstrua-os pela autoridade
+   `EVIDENCE_INDEX.jsonl`;
+5. nunca apague ou edite `EVIDENCE_INDEX.jsonl`, Markdown ou sidecars do Core para reparar um
+   provider de embeddings;
+6. reative com `required: false` e promova para `required: true` apenas em um ambiente que realmente
+   exige o provider.
+
+## Próximos passos
+
+Este contrato não instala um modelo nem integra embeddings automaticamente ao MCP, doctor ou
+Observer. Ele define a fronteira segura e testável para um adapter irmão futuro. O Core continua
+completo e funcional sem qualquer plugin.
+
+Use o guia de [MCP nativo](mcp.md) para a superfície paginada/lexical já exposta e o guia de
+[manutenção e diagnóstico](maintenance-and-diagnostics.md) para inspecionar a saúde dos artefatos
+derivados sem reconstruí-los.