deepdebug-local-agent 1.0.23 → 1.1.0

package/docs/OBSERVABILITY.md

@@ -0,0 +1,164 @@
+# Client Observability — method & runbook
+
+How the DeepDebug local agent brings **observability to a client that has none**.
+It is the client-side delivery of the same stack we run for ourselves in
+`vh-observability` (Grafana + Loki + Alloy + Alertmanager) — same building
+blocks, different plumbing.
+
+| | `vh-observability` (ours) | This bundle (client) |
+| --- | --- | --- |
+| Runs on | Cloud Run (multi-container) | Client VPS/host (docker-compose) |
+| Log source | Cloud Logging → Pub/Sub (`gcplog`) | **`docker.sock`** (every container) |
+| Loki storage | GCS bucket | **local filesystem volume** |
+| Grafana login | Google Workspace OAuth | local admin (loopback-only) |
+| Alerts → | gateway `/webhooks/alertmanager` (Bearer secret) | **same gateway webhook** |
+
+Everything downstream of Loki is identical: the ruler evaluates a LogQL error
+rule, Alertmanager posts firing alerts to the gateway (tenant resolved from the
+trigger secret, sent as a Bearer header), and Grafana's logs dashboard has an **"Open in DeepDebug
+Workbench"** data link into `/api/v1/webhooks/from-log`.
+
+---
+
+## Architecture
+
+```
+   All containers on the host
+        │  (docker.sock, read-only)
+        ▼
+   Alloy  ──push──▶  Loki (filesystem)  ◀──query──  Grafana (127.0.0.1:3000)
+ (discovery.docker,   (chunks + tsdb in        (provisioned datasource +
+  service = name,      a local volume)          dashboard, loopback only)
+  level parsed)            │ ruler
+                           ▼
+                      Alertmanager  ──webhook──▶  gateway /api/v1/webhooks/alertmanager (Bearer <secret>)
+                                                        │
+                                        incident (tenant from the secret) + Slack notify
+```
+
+Four containers, one compose project (`deepdebug-observability`). Only Grafana
+publishes a port, and only on `127.0.0.1` — reach it over an SSH tunnel, never
+expose it to the internet.
+
+## The error → workbench loop
+
+- **Automatic** — Loki rule `ClientServiceErrors` fires on error rate → Alertmanager
+  → `POST /api/v1/webhooks/alertmanager` (`Authorization: Bearer <secret>`) → incident → Slack.
+- **Manual** — the Logs panel data link → `GET /api/v1/webhooks/from-log?s=<secret>&…`
+  → incident → 302 redirect to `<frontend>/incidents/<id>` (the PG-persisted id).
+
+The tenant is always resolved from the trigger secret, never from the
+caller — the secret IS the auth.
+
+## Logs into the platform (Live logs + services)
+
+Loki stays on the host for Grafana, but the platform cannot reach it (no inbound
+port). Alloy therefore **also pushes** the same Docker stream to the gateway:
+
+```
+loki.process ──▶ otelcol.receiver.loki ──▶ batch ──▶ otelcol.exporter.otlphttp
+   POST <gateway>/api/v1/webhooks/logs/otlp   (JSON, gzip, Authorization: Bearer <secret>)
+        ──▶ Redis list vh.logs.push.<tenant> ──▶ monitor-service (provider SELF_HOSTED)
+        ──▶ log_entries + live tail  ──▶ Live logs (one service per container)
+```
+
+- Outbound HTTPS only; same `vht_` secret as the Alertmanager.
+- The first push creates the tenant's `SELF_HOSTED` row in `tenant_log_configs`.
+- Pushed logs are **not** promoted to incidents by the monitor (the Loki rule above
+  already does that) unless `MONITOR_PUSH_DETECT_ENABLED=true`.
+- The gateway accepts OTLP **JSON** only (protobuf gets 415).
+
+**Existing installs** (provisioned before this change): run
+`scripts/upgrade-observability-push.sh` on the server (`--dry-run` first). It finds the
+bundle, reads the gateway URL and secret from `alertmanager.yml`, probes the push endpoint,
+adds the `otelcol.*` blocks, moves the secret to a Bearer header, validates both configs
+with the stack's own images, restarts only `alloy` + `alertmanager` and rolls back on
+failure. Idempotent.
+
+---
+
+## The zero-observability method
+
+The agent only offers to provision when the host has **nothing** already shipping
+logs/metrics. The decision is deliberately conservative: a false "they have it"
+just means we skip; a false "they have nothing" would deploy on top of a real
+stack. So we skip on ANY match.
+
+**Signals** (matched case-insensitively against container image/name AND process
+command lines): promtail, fluent-bit, fluentd, vector, filebeat, logstash,
+otel-collector, telegraf, loki, elasticsearch, opensearch, victoriametrics,
+prometheus, thanos, mimir, signoz, grafana, kibana, datadog, newrelic, splunk,
+dynatrace, instana, sumologic, … (see `OBSERVABILITY_SIGNALS` in
+`src/observability/detect.js`).
+
+**Our own stack never counts** as the client already having observability: any
+container whose compose project is `deepdebug-observability` is excluded, so
+re-running detection after we provision still reports the client's baseline and
+`up -d` stays idempotent.
+
+### Step-by-step the agent performs (`provisionObservability`)
+
+1. **Probe** the host — `docker ps` + process list → classify (above).
+2. **Guard** — if the client already has observability and `force` is not set,
+   **stop** and report what was found. Do not touch their stack.
+3. **Pre-flight** — verify `docker` and the compose plugin are present
+   (else return an actionable error).
+4. **Render** the bundle for this tenant: inject `gatewayUrl`, the alertmanager
+   `triggerSecret`, and a static `environment` label into every template.
+5. **Write** files to `~/.deepdebug/observability/deepdebug-observability/`
+   plus a `.env` (Grafana admin creds, `DDO_ENVIRONMENT`).
+6. **Start** — `docker compose up -d --remove-orphans`.
+7. **Report** — container status + the loopback Grafana URL and admin password.
+
+---
+
+## Agent API
+
+Called by the gateway (Setup/Onboarding agent) or by an operator directly.
+
+### `GET /observability/status`
+Probe + classify. No side effects.
+```json
+{ "ok": true, "hasObservability": false, "recommendation": "provision",
+  "found": [], "ownStackRunning": false,
+  "docker": { "docker": true, "compose": true }, "containersScanned": 6 }
+```
+
+### `POST /observability/provision`
+```jsonc
+{
+  "gatewayUrl": "https://api.visionhammer.io",   // no trailing slash needed
+  "triggerSecret": "vht_….",                     // tenant alertmanager secret
+  "environment": "production",                    // static label for this client
+  "grafanaUser": "admin",                         // optional
+  "grafanaPassword": "…",                         // optional (else generated + returned)
+  "force": false,                                 // deploy even if a stack exists
+  "start": true                                   // run `docker compose up -d`
+}
+```
+Returns `409 { skipped: true, found: [...] }` when the client already has a stack
+and `force` is not set. On success returns `installDir`, container `status`, and
+`grafana: { url, user, password }`.
+
+### `POST /observability/teardown`
+`{ "purge": false }` → `docker compose down` (`purge:true` also removes volumes).
+
+---
+
+## Access & security
+
+- **Grafana** is bound to `127.0.0.1:3000`. Reach it with
+  `ssh -L 3000:127.0.0.1:3000 <host>` then open `http://localhost:3000`.
+- The **trigger secret** is the only credential in the alertmanager webhook URL
+  and it authorises exactly one tenant. Rotate via the gateway trigger source.
+- Alloy mounts `docker.sock` **read-only** and only tails logs.
+- The generated Grafana admin password is reported once — rotate it, or pass
+  your own `grafanaPassword`.
+
+## Where the bundle lives
+
+The bundle is **embedded** in the agent (`src/observability/bundle-files.js`) so
+it ships inside the `pkg` binary — there are no loose asset files to lose. Editing
+that file changes what the agent deploys. `renderBundle()` is a pure function
+(templated in → final files out) and is covered by
+`test/observability-detect.test.js`.

package/docs/byoc-agent-image.md

@@ -0,0 +1,70 @@
+# BYOC agent image (`local-agent-full`)
+
+Customer-cloud agents (BYOC GCP Cloud Run and BYOC Azure Container Instances)
+run the public image built from `Dockerfile.full`:
+
+```
+europe-west1-docker.pkg.dev/visionhammer/visionhammer-docker-public-eu/local-agent-full:<semver>
+europe-west1-docker.pkg.dev/visionhammer/visionhammer-docker-public-eu/local-agent-full:<git-sha>
+```
+
+The managed per-tenant Cloud Run agent (gateway `AgentProvisioningService`) is
+built separately per tenant and does not use this image.
+
+## Publishing a version
+
+1. Actions → **Build BYOC Agent Image** → *Run workflow* on `main` (version
+   defaults to `package.json`; or push a `v*` tag / publish a release on a
+   commit that is on `main`).
+2. The workflow builds `Dockerfile.full`, smoke-tests it (`/health` public,
+   API returns 401 without `X-Agent-Token` when `LOCAL_AGENT_TOKEN` is set),
+   then pushes `:<semver>` and `:<git-sha>`. It refuses to overwrite an
+   existing `:<semver>` built from a different commit, and never moves an
+   existing `:<git-sha>` (a commit rebuilt under a new semver keeps its first
+   image under `:<git-sha>`; always pin `:<semver>@sha256:`). There is no floating tag.
+3. Copy the pinned reference from the run summary
+   (`...local-agent-full:<semver>@sha256:<digest>`).
+
+4. Optional supply chain (flag, off by default): tick `supply_chain` on the
+   dispatch (or set the repository variable `BYOC_SUPPLY_CHAIN=true` for tag and
+   release runs). The `supply-chain` job signs `:<semver>@sha256:<digest>` with
+   cosign keyless (GitHub OIDC), attaches an SPDX SBOM (syft) and a SLSA v1
+   provenance attestation, and verifies all three. Consumers verify with:
+
+   ```
+   cosign verify \
+     --certificate-identity-regexp '^https://github.com/VISIONHAMMER/deepdebug-local-agent/' \
+     --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+     <image>@sha256:<digest>
+   ```
+
+   Use `cosign verify-attestation --type spdxjson` (or `slsaprovenance1`) for
+   the SBOM and the provenance. The provenance is generated inside this
+   workflow and signed with the workflow identity; it is not a
+   slsa-github-generator (isolated builder) attestation.
+
+Fallback without GitHub Actions: `cloudbuild-full.yaml` (see header).
+
+## Rolling it out (gateway)
+
+Set `deepdebug.byoc.agent-image` in vh-api-gateway (env `BYOC_AGENT_IMAGE`) to
+the pinned reference, or bump its default in `application.yml` via PR. Only
+newly provisioned agents pick it up; existing ones keep their image until
+re-provisioned from the platform (Cloud Engineer → provision again). Azure
+container groups created before the TLS/token spec are recreated on re-provision.
+
+## Runtime knobs relevant to BYOC
+
+| Env | Meaning |
+| --- | --- |
+| `LOCAL_AGENT_TOKEN` | Enforce `X-Agent-Token` on every non-public route (gateway sets it = the per-workspace shared secret on ACI). |
+| `AGENT_SHARED_SECRET` | Same secret; used for the agent's own in-process calls. |
+| `LOCAL_AGENT_BIND_HOST` | Listen address. Default: `0.0.0.0` when a token (`LOCAL_AGENT_TOKEN`/`AGENT_SHARED_SECRET`) or Cloud Run is present, otherwise `127.0.0.1`. ACI sets `127.0.0.1`: only the Caddy TLS sidecar in the same container group can reach it. |
+
+## One-time operator setup
+
+- `github-deployer@visionhammer.iam.gserviceaccount.com` needs
+  `roles/artifactregistry.writer` on the `visionhammer-docker-public-eu` repository (europe-west1; today granted at project level)
+  (and `artifactregistry.reader` for the overwrite guard).
+- The repository must stay public-read (`allUsers` → `artifactregistry.reader`) so
+  customer projects / ACI pull without credentials.

package/docs/graphify-packaging-plan.md

@@ -0,0 +1,133 @@
+# Graphify no `local-agent-full`: plano de empacotamento e checklist de licenças
+
+Estado: **proposta** (tarefa T4-06 do plano GA do Local Agent, decisões D8, D11, D12, D14 e D18 do ADR-0017). Nada neste
+documento está aplicado: nenhum Dockerfile, workflow ou `package.json` foi alterado. A implementação é a tarefa T4-07
+(PR separado). Marcação: **[V]** verificado nesta sessão (comando e saída em `docs/graphify-validation-run-2026-10-28.md`),
+**[N]** não verificado.
+
+## 1. Decisões que este plano executa
+
+| Decisão | Consequência técnica |
+|---|---|
+| D8: Graphify via PyPI, versão fixada, com hash | dependência `graphifyy==X.Y.Z`, sem fork; instalação só com `--require-hashes` |
+| D11: GA 1.1.0 | a imagem `local-agent-full:1.1.0` é a primeira com o runtime; o `Dockerfile.full` e o Helm deixam de apontar para `1.0.0` e `:latest` (tarefa T4-07) |
+| D12: cosign e SBOM obrigatórios | a imagem e o SBOM saem assinados na mesma release (secção 6) |
+| D14: fallback ripgrep | a imagem inclui `ripgrep`; se o índice do grafo faltar ou estiver velho, o contexto vem de `rg` |
+| D18: runtime pack multi-runtime | o runtime Graphify é um pack como os outros (Java, Swift): instalável e removível sem tocar no agente Node |
+
+## 2. O que vai fixado, e como
+
+### 2.1 Ficheiros de lock (já no harness)
+
+`tools/graphify-validation/requirements.in` tem **uma** linha, `graphifyy[sql,terraform]==0.9.93`. Dois locks com hashes SHA-256
+de todos os artefactos de cada versão:
+
+- `requirements.lock`, Python 3.12 (venv do harness) [V];
+- `requirements-py311.lock`, Python 3.11, a versão do Debian bookworm que o `Dockerfile.full` já instala (`python3`, `libpython3.11`) [V no ficheiro].
+
+**Os locks não são intermutáveis [V]:** em 3.11 o resolvedor escolhe `networkx 3.6.1` e `numpy 2.4.6`; em 3.12, `networkx 3.7` e
+`numpy 2.5.4`. A imagem usa o lock do Python que tiver. Para a mesma versão de Python, o conjunto de pacotes resolvido é o mesmo em
+Linux x86_64, Linux aarch64 e macOS arm64 (`uv pip compile --python-platform ...`, comparado) [V]. O lock 3.11 foi instalado com
+`--require-hashes --no-deps --only-binary=:all:` num venv Python 3.11 em macOS arm64 e deu o mesmo grafo (52 nós, 84 arestas) na fixture Spring [V];
+a instalação em Linux (glibc, musl) **não foi corrida** [N] (sem Docker local).
+
+Extras: só `sql` (`tree-sitter-sql`) e `terraform` (`tree-sitter-hcl`). **Não** entram `mcp`, `leiden` (puxa `graspologic`), nem extras de LLM
+(`anthropic`, `openai`, `gemini`, `bedrock`, `ollama`...). Sem `leiden`, a deteção de comunidades usa o fallback do próprio Graphify;
+as comunidades não são identificadores estáveis de qualquer modo (nota do piloto). O pacote instala o script `graphify-mcp`
+mesmo sem o extra `mcp` [V, `entry_points.txt`]: **apagar `bin/graphify-mcp`** na imagem.
+
+### 2.2 Instalação
+
+```dockerfile
+# proposta para Dockerfile.full (T4-07); não aplicada
+ARG GRAPHIFY_LOCK=requirements-py311.lock
+COPY tools/graphify-validation/${GRAPHIFY_LOCK} /tmp/graphify.lock
+RUN python3 -m venv /opt/vh-graphify \
+ && /opt/vh-graphify/bin/pip install --no-cache-dir --disable-pip-version-check \
+      --require-hashes --no-deps --only-binary=:all: -r /tmp/graphify.lock \
+ && /opt/vh-graphify/bin/python -m compileall -q /opt/vh-graphify/lib \
+ && rm -f /opt/vh-graphify/bin/graphify-mcp /tmp/graphify.lock
+```
+
+Porquê cada flag: `--require-hashes` recusa qualquer ficheiro cujo hash não esteja no lock; `--no-deps` impede que o pip resolva
+dependências por fora do lock; `--only-binary=:all:` proíbe sdists, logo **nenhum `setup.py` de terceiros corre no build** (a nota do piloto já
+tinha visto que o `pyproject` do Graphify é setuptools puro [C]); `compileall` deixa o bytecode feito para o sistema de ficheiros só de leitura
+(o Python não escreve `.pyc` com `PYTHONDONTWRITEBYTECODE=1`).
+
+Tamanho medido do `site-packages`: 154 MB (Python 3.12, macOS arm64, com `pip`) e 124 MB (3.11, sem `pip`) [V]. Em Linux pode diferir [N]; o
+limite proposto de delta de imagem é 400 MB (G9).
+
+### 2.3 Política de subida
+
+1. Só versões com mais de 7 dias no PyPI (cooldown contra pacote comprometido). A fixada, 0.9.93, tinha 8 dias a 2026-10-28 [V, data de upload no PyPI]; o
+   upstream já ia na 0.9.97 (publicada a 2026-10-27, **não escolhida de propósito**).
+2. PR de subida: editar `requirements.in`, regenerar os dois locks (comandos no README do harness), **rever o diff do código Python do Graphify entre versões**
+   (o PyPI mostra 13 versões em 17 dias, de 0.9.84 a 0.9.97 [V]), repetir o harness (G1, G2, G7, G8) e anexar o `REPORT.md`.
+3. Nunca `pip install graphifyy` sem lock, nem `--upgrade`, nem `latest`, em Dockerfile, instalador, Helm ou CI.
+4. Mesma regra para o `pip-audit` (`requirements-tools.in/.lock`).
+
+## 3. `pip-audit` e cadeia de fornecimento
+
+- Local: `run.sh --pip-audit` corre `pip-audit --require-hashes --disable-pip --no-deps -r requirements.lock`. Resultado de 2026-10-28: **0 vulnerabilidades conhecidas em
+  32 pacotes** (base PyPI/OSV nessa data) [V]. O mesmo audit tem de correr para `requirements-py311.lock` [N: só o lock 3.12 foi auditado].
+- CI (T4-07): job no PR que toca nos locks e job semanal agendado; falha com qualquer vulnerabilidade com versão corrigida disponível. Exceções só com ID, motivo e data de expiração
+  num ficheiro `pip-audit-ignore.txt` revisto no PR. Nota: o audit só vê vulnerabilidades **publicadas**; não substitui a revisão de diff da secção 2.3.
+- Proveniência: confirmar se o `graphifyy` publica atestações PyPI (Trusted Publishing) [N]. Se publicar, verificar no job de subida; se não, registar o risco no ADR.
+- A imagem corre **sem rede para o Graphify**: o `entrypoint` do pack não define proxies nem chaves, e o contentor de teste usa `--network none` (G9) [N].
+
+## 4. Superfície permitida em runtime
+
+O Local Agent chama o Graphify por **um wrapper** (`vh-graphify`, a escrever em T4-07), nunca diretamente:
+
+| Permitido | Proibido (o wrapper recusa com exit 64) |
+|---|---|
+| `update <path>`, `query`, `affected`, `explain`, `path`, `god-nodes` | `label`, `cluster-only` sem `--no-label`, `add`, `clone`, `prs`, `watch`, `install`, `global`, `merge-graphs`, `graphify-mcp` |
+
+- Ambiente do processo filho: `HOME` num diretório do volume de dados, `PATH`, `LANG`, `PYTHONHASHSEED=0`, `PYTHONDONTWRITEBYTECODE=1`. **Sem** chaves LLM, tokens nem proxies
+  (a CLI auto-deteta chaves e envia nomes de comunidade ao LLM, nota do piloto). O harness corre assim e o relatório regista as chaves passadas [V].
+- Rede: o harness provou 0 eventos `socket.*` com a rede bloqueada nos três repos VH, a rede estava de facto bloqueada (sonda TCP falhou) e os únicos `subprocess.Popen` foram `git rev-parse HEAD` [V].
+  O wrapper deve manter o `git` no `PATH`.
+- Um índice de cada vez (fila), limite de memória 1,5 GB e timeout por job. Medido: o `update` incremental chega a 1,13-1,17 GB no maior processo filho nos repos de ~1 700 ficheiros [V]; num VPS de 4 GB cabe, num de 2 GB não.
+  Em 2 vCPU 4 GB **não medido** [N].
+- `graphify-out/` fica no volume de dados do cliente, fora do git, e entra na lista de limpeza/erasure. `git ls-files graphify-out` tem de dar 0; hoje o `visionhammer-agents@release/qa` tem 57 ficheiros versionados [V] (remoção = PR próprio no agents, `git rm -r --cached graphify-out`).
+- Utilizador não-root, FS só de leitura exceto o volume de dados e `/tmp`.
+
+## 5. Checklist de licenças
+
+Inventário da instalação do harness (32 distribuições, `lib/licenses.py`) [V]: **32 permissivas, nenhuma copyleft, nenhuma desconhecida**.
+
+| Componente | Licença (metadados) | Ficheiro de licença no wheel | Ação |
+|---|---|---|---|
+| graphifyy 0.9.93 | Apache-2.0 (+ `LICENSE-MIT`, `NOTICE`) | sim (`LICENSE`, `LICENSE-MIT`, `NOTICE`) | copiar os três para `/usr/share/doc/vh-graphify/`; incluir o `NOTICE` no `THIRD_PARTY_NOTICES` do release |
+| networkx 3.7 / 3.6.1 | BSD-3-Clause | sim | notice |
+| numpy 2.5.4 / 2.4.6 | `BSD-3-Clause AND 0BSD AND MIT AND Zlib AND CC0-1.0` (libs incluídas) | sim | notice com a lista das licenças incluídas |
+| RapidFuzz 3.14.6, tree-sitter 0.25.2 (core) | MIT | sim | notice |
+| 27 gramáticas `tree-sitter-*` instaladas | MIT (2 em Apache-2.0: `tree-sitter-elixir`, `tree-sitter-hcl`) | sim, **exceto `tree-sitter-groovy`** | `tree-sitter-groovy` é MIT nos metadados mas **o wheel não traz ficheiro de licença**: obter o texto do repositório upstream e anexar [N] |
+| ripgrep (Debian) | Unlicense/MIT | pacote Debian | notice (D14) |
+| Python 3.11 (Debian) | PSF | pacote Debian | notice |
+
+Checklist antes de publicar:
+
+- [ ] Gerar o SBOM CycloneDX da imagem final (inclui hashes e licenças de cada wheel) e anexar à release; é a fonte do `THIRD_PARTY_NOTICES`.
+- [ ] Reter `LICENSE`, `LICENSE-MIT` e `NOTICE` do Graphify, sem os alterar (exigência do Apache-2.0 para redistribuição; o `package.json` do agente diz `Proprietary`, o que não impede redistribuir um componente Apache-2.0 com notice).
+- [ ] Obter o texto de licença de `tree-sitter-groovy` e conferir que a gramática distribuída corresponde ao MIT declarado.
+- [ ] Não incluir os extras `leiden` (graspologic), `neo4j`, `falkordb`, `postgres`, `google`, `video`, `office`, `pdf` sem nova revisão: não foram inventariados [N].
+- [ ] Marca: o upstream promove o "Graphify Cloud" no README; a imagem e a documentação VH não usam o nome nem o logótipo comerciais, só o nome do pacote.
+- [ ] Confirmar com quem decide (jurídico) que a redistribuição dentro de uma imagem proprietária cumpre os contratos de cliente. Isto é uma checklist técnica, **não parecer jurídico**.
+- [ ] Repetir o inventário (`lib/licenses.py`) a cada subida de versão; qualquer licença nova fora de MIT/BSD/Apache/PSF/ISC bloqueia o PR.
+- [ ] Decisão pendente do Edu: abandonar o fork `VISIONHAMMER/visionhammer-graphify` (recomendado no plano GA); se se mantiver, manter os cabeçalhos de licença e o `NOTICE` do upstream.
+
+## 6. Assinatura e SBOM (D12)
+
+- `syft <imagem> -o cyclonedx-json` no workflow de build; o SBOM vai como asset da release e é anexado à imagem com `cosign attach sbom` ou atestação `cosign attest --type cyclonedx`.
+- `cosign sign` da imagem por digest (keyless via OIDC do GitHub Actions, ou chave no KMS; escolha por decidir [N]). O workflow `build-byoc-image.yml` hoje não assina [N, não verificado nesta tarefa].
+- Verificação no instalador/Helm: `cosign verify` do digest antes de arrancar; o Helm deixa de usar `:latest` e passa a referenciar o digest.
+- O hash do lock e o hash do SBOM do pack Graphify ficam no `metadata` do heartbeat para o gateway poder detetar versões não aprovadas (desenho em T4-07/T4-08) [N].
+
+## 7. O que falta provar (antes de declarar G9)
+
+1. `docker build -f Dockerfile.full` com o bloco da secção 2.2 e medir o delta de imagem (limite 400 MB).
+2. `docker run --read-only --network none --user 10001 ... vh-graphify update /workspace` com sucesso, mesmo grafo que o harness (comparar `signature`).
+3. Lock 3.11 em Linux x86_64 e aarch64; `pip-audit` sobre `requirements-py311.lock`.
+4. `tree-sitter-groovy`: licença anexada.
+5. Wrapper `vh-graphify` com teste de que cada comando proibido sai com 64 e que nenhuma chave LLM é herdada.

package/docs/graphify-validation-run-2026-10-28.md

@@ -0,0 +1,243 @@
+# Graphify: corrida do harness de validação, 2026-10-28
+
+Corrida real de `tools/graphify-validation/run.sh --pip-audit` (T4-06, D8) contra `vh-api-gateway@release/qa`, `visionhammer-agents@release/qa` e
+`deepdebug-local-agent@main` (SHAs na secção 0 do relatório). Máquina de desenvolvimento (macOS arm64, 10 CPUs, 16 GB), **não** um VPS de 2 vCPU / 4 GB.
+Graphify `graphifyy==0.9.93` do PyPI, instalado com `--require-hashes`. Sem LLM, sem rede para o Graphify, sem acesso ao pgvector de PROD nem de QA.
+
+**Conclusão curta: o Graphify continua "go com condições", e "Graphify validado" (D5) ainda não pode ser declarado.** Dos limiares propostos, nesta corrida
+falham G1 (só no repo do Local Agent), G3, G4 (memória no incremental), G5 e G8 (versionamento no agents); passam os testes de rede e determinismo; G6, G9 e G10 não foram medidos.
+
+## Leitura dos resultados (com as ressalvas que alteram a conclusão)
+
+- **G1, extração.** gateway 99,81 % (3 ficheiros sem símbolos), agents 100 %, Local Agent 93,33 % (8 de 120: 7 são testes `node:test` só com código de topo, mais `src/workspace/git-client.js`, **causa não investigada**). Falha o limiar de 95 % só no Local Agent, num repo pequeno onde um ficheiro pesa 0,8 %.
+- **G2, arestas.** INFERRED: gateway 12,22 %, agents 14,05 % (a 1 ponto do limiar de 15 %; a nota do piloto tinha 11,4 % e 13,6 % com a 0.9.86), Local Agent 1,68 %. A precisão da amostra vem de um **oráculo automático** (tipo declarado do recetor), não de revisão humana: gateway 94,6 % nas 56 decididas de 60, agents 100 % nas 53 decididas de 60, Local Agent 100 % em 7 (só 7 arestas INFERRED `calls` fora de testes). O oráculo reproduziu o falso positivo que o piloto cita (`webClientBuilder.build()` apontado para `RootAuditEvent.Builder`, 3 ocorrências na amostra do gateway), o que mostra que não aprova tudo. Fica `PARCIAL`: falta a revisão por 2 pessoas e as linhas `unknown` (construtores, chamadas encadeadas, `var`) estão por julgar nos CSV.
+- **G3, Spring/DI (fixture sintética, 19 verificações).** Falha: interface→implementação 62,5 % (5/8). O grafo liga `StripeGateway implements PaymentGateway` e as chamadas à interface, mas **não liga quem chama a interface às implementações** (3 verificações "chega à implementação" falham). Injeção por Lombok/construtor por tipo: 4/4. `@Bean`: 2/4 (o método `@Bean` aparece como método comum; quem consome o bean não chega ao método). `@Qualifier`: 0/3 (ignorado). Confirma a condição do piloto "sem nós de bean". Consequência para o loop: o contexto de "quem é afetado por mudar `PaymentGateway.charge`" tem de juntar `implements` a mão (ou o fallback `rg`).
+- **G4, desempenho.** A frio: gateway 19,5 s, agents 15,3 s, Local Agent 2,8 s, todos abaixo de 60 s; maior processo filho 440-445 MB (estimativa da soma da árvore: ~795 MB, que conta páginas partilhadas). **Incremental (1 ficheiro): 21,6 s e 18,7 s, maior filho 1,17 e 1,13 GB, acima do limiar de 1 GB** (o piloto tinha 1,06 GB). Confirma que o `update` incremental reconstrói tudo. Em 2 vCPU/4 GB **não medido**; o tempo deve subir, a memória do maior processo não deve descer.
+- **G5, recall.**
+  - "Quem é afetado" (`affected`, profundidade 1, só fontes main, `rg -w` como referência): recall agregado 54,8 % no gateway, 76,8 % no agents, 87,5 % no Local Agent; o limiar é 90 %. A precisão contra `rg` ficou em 100 % no gateway e no Local Agent e 79,6 % no agents. Os piores casos são classes cujo uso é por métodos (`PolicyGate`: 10 % a profundidade 1, 15 % a profundidade 2): o nó da classe não recebe as chamadas aos seus métodos. Ou seja, a primitiva certa é `affected` **por método**, não por classe, e isso não foi medido aqui.
+  - recall@8 com 22 perguntas escritas à mão (`config/questions.json`; 8 gateway, 8 agents, 6 Local Agent): o grafo fica em 43,8 % (gateway), 62,5 % (agents) e 66,7 % (Local Agent). O baseline lexical **justo** (palavras tiradas só do texto da pergunta, `rg` insensível a maiúsculas) dá 87,5 %, 75,0 % e 91,7 %. As perguntas conceptuais sem nome de símbolo são o ponto fraco do grafo (gateway 25 %, agents 57,1 %), exatamente a lacuna que o piloto não tinha testado e que o D14 (fallback ripgrep) cobre. As perguntas que nomeiam o símbolo: grafo 100 %.
+  - A coluna `lexical_curated` (100 % nos três) usa palavras escolhidas por quem já sabia a resposta; **não é comparável** e está no relatório só como teto.
+  - **pgvector não medido**: sem o dataset do `RagEvalController` e sem BD, a comparação "grafo ≥ pgvector − 5 pp" do G5 não pode ser feita. O harness aceita `--vector-results` para quando houver.
+  - O conjunto de 22 perguntas é pequeno e a verdade (ficheiros) foi verificada à mão por um só agente; serve para comparar backends, não para um número absoluto.
+- **G7, segurança.** Com a rede negada (`sandbox-exec`, verificado por uma sonda TCP que falhou), os 3 repos terminaram com exit 0, **0 eventos `socket.*`** no hook de auditoria e só 2 `subprocess.Popen` (`git rev-parse HEAD`). `pip-audit`: 0 vulnerabilidades conhecidas nos 32 pacotes do lock 3.12 (não foi corrido no lock 3.11). Licenças: 32 permissivas, `tree-sitter-groovy` sem ficheiro de licença no wheel. `PARCIAL`: a lista de comandos desativados é requisito do wrapper, não foi testada.
+- **G8, higiene.** Determinismo: duas corridas a frio dão a mesma impressão de nós/arestas nos 3 repos. `visionhammer-agents@release/qa` **tem 57 ficheiros `graphify-out/` versionados** (gateway e Local Agent: 0). O limiar exige 0, logo falha até haver o PR de remoção.
+- **Versão.** O piloto mediu o fork 0.9.86; esta corrida mede o PyPI 0.9.93. Números próximos (tempos, INFERRED, grafos de ~17 000 nós), sem sinal de que o fork acrescente valor, o que sustenta D8.
+
+## Não medido (e porquê)
+
+| Item | Motivo |
+|---|---|
+| recall@8 contra pgvector (G5) | sem BD de QA nem dataset do `RagEvalController` |
+| G6, incidentes ponta a ponta sem Voyage | exige agent2/LA com LLM |
+| G9, imagem `local-agent-full` | sem Docker local; plano em `docs/graphify-packaging-plan.md` |
+| G10, Python, SQL, Go, Terraform reais e repo do piloto | fora dos 3 repos pedidos; o piloto anterior só tinha fixtures sintéticas para Go e Terraform |
+| 2 vCPU / 4 GB e hardware do piloto | só há esta máquina |
+| Revisão manual de 2 pessoas das INFERRED | passo humano; CSV pronto |
+| `pip-audit` do lock Python 3.11, instalação do lock em Linux | só macOS arm64 e lock 3.12 auditados |
+
+---
+
+## Relatório gerado (REPORT.md, sem edição manual)
+
+Gerado por `tools/graphify-validation/run.sh`. Marcacao: PASSA/FALHA contra o limiar proposto; PARCIAL = medido mas falta um passo humano ou de ambiente; NAO MEDIDO = nao deu para medir aqui.
+
+## 0. Ambiente e versoes
+
+| Item | Valor |
+|---|---|
+| Data (UTC) | 2026-10-28T03:57:56Z |
+| Graphify | graphifyy==0.9.93 (fixado por hash) |
+| Python | Python 3.12.10 |
+| SO / CPU / RAM | Darwin 25.3.0 arm64 / 10 CPUs / 16.0 GB |
+| ripgrep | ripgrep 14.1.1 (rev 0ae49f8b6e) |
+| Bloqueio de rede | sandbox-exec (deny network*); eficaz: True |
+| Ambiente do processo | so HOME, LANG, NO_COLOR, PATH, PYTHONHASHSEED (sem chaves LLM nem credenciais) |
+
+| Repo | Ref | SHA | Ficheiros de codigo |
+|---|---|---|---|
+| deepdebug-local-agent | origin/main | 854fa34cb8 | 120 |
+| vh-api-gateway | origin/release/qa | ef42fba928 | 1552 |
+| visionhammer-agents | origin/release/qa | 33a705cc9a | 1056 |
+
+## 1. Resumo por criterio
+
+| ID | Veredito | Medido |
+|---|---|---|
+| G1 | FALHA | deepdebug-local-agent 93.33% (8 sem simbolos); vh-api-gateway 99.81% (3 sem simbolos); visionhammer-agents 100.0% (0 sem simbolos) |
+| G2 | PARCIAL | deepdebug-local-agent INFERRED 1.68%, precisao oraculo 100.0% (n=7, decididas 7); vh-api-gateway INFERRED 12.22%, precisao oraculo 94.6% (n=60, decididas 56); visionhammer-agents INFERRED 14.05%, precisao oraculo 100.0% (n=60, decididas 53); falta revisao manual por 2 pessoas |
+| G3 | FALHA | interface->impl 62.5% (limiar 90%) |
+| G4 | FALHA | deepdebug-local-agent frio 2.83s, arvore 635.4 MB, maior filho 94.6 MB; incremental 2.8s, arvore 635.7 MB, maior filho 121.0 MB; vh-api-gateway frio 19.47s, arvore 795.9 MB, maior filho 444.2 MB; incremental 21.64s, arvore 1093.5 MB, maior filho 1174.2 MB; visionhammer-agents frio 15.27s, arvore 793.7 MB, maior filho 439.7 MB; incremental 18.68s, arvore 1123.9 MB, maior filho 1134.7 MB; maquina de desenvolvimento (nao 2 vCPU/4 GB); soma de RSS da arvore acima de 1 GB em pelo menos uma corrida (pode contar paginas partilhadas) |
+| G5 | FALHA | deepdebug-local-agent affected recall vs rg 87.5% (precisao 100.0%); deepdebug-local-agent recall@8 grafo 66.7% vs lexical (palavras da pergunta) 91.7%; vh-api-gateway affected recall vs rg 54.8% (precisao 100.0%); vh-api-gateway recall@8 grafo 43.8% vs lexical (palavras da pergunta) 87.5%; visionhammer-agents affected recall vs rg 76.8% (precisao 79.6%); visionhammer-agents recall@8 grafo 62.5% vs lexical (palavras da pergunta) 75.0%; pgvector NAO medido (sem BD de QA) |
+| G6 | NAO MEDIDO | exige agent2/LA com LLM e incidentes reais; fora do harness |
+| G7 | PARCIAL | deepdebug-local-agent: 0 eventos socket, exit 0; vh-api-gateway: 0 eventos socket, exit 0; visionhammer-agents: 0 eventos socket, exit 0; pip-audit: 0 vulnerabilidades conhecidas em 32 pacotes (exit 0); comandos de rede desativados = requisito de empacotamento, nao testado aqui |
+| G8 | FALHA | determinismo igual em 3/3 repos; deepdebug-local-agent: 0 ficheiros graphify-out versionados; vh-api-gateway: 0 ficheiros graphify-out versionados; visionhammer-agents: 57 ficheiros graphify-out versionados |
+| G9 | NAO MEDIDO | sem Docker local; ver docs/graphify-packaging-plan.md |
+| G10 | NAO MEDIDO | Java e JS cobertos por repos VH; Python/SQL/Go/Terraform e repo do piloto fora deste conjunto |
+
+## 2. Detalhe por repo
+
+### deepdebug-local-agent
+
+- Corrida a frio: 2.83s, pico de RSS da arvore 635.4 MB (estimativa; maior filho 94.6 MB), nos 1642, arestas 3283, graphify-out 3.2 MB.
+- G1: 112/120 ficheiros de codigo com simbolos (93.33%); 8 sem simbolos, dos quais 7 em testes. Lista: src/workspace/git-client.js, test/bind-host.test.js, test/child-env.test.js, test/file-count.test.js, test/observability-detect.test.js, test/sandbox.test.js, test/search-outcome.test.js, test/adapters/registry.test.js
+- G2: INFERRED 1.68% (1.69% so em fontes main); INFERRED por relacao {'calls': 7, 'indirect_call': 38, 'references': 10}.
+- G8 determinismo: assinatura aab33c2415660429 vs aab33c2415660429, igual: True.
+- Incremental (1 ficheiro alterado: bin/install.js): 2.8s, 635.7 MB; simbolo novo no grafo: True; sem alteracoes: 2.38s.
+- G7 rede bloqueada (sandbox-exec (deny network*)): exit 0, 0 eventos socket, 2 subprocess.Popen (('git', ['git', 'rev-parse', 'HEAD'], '/private/tmp/claude-501/-Users-).
+- G2 amostra (seed 20261028, n=7): oraculo ok/wrong/unknown {'ok': 7}; precisao nas decididas 100.0%; estrato ambiguo {'n': 0, 'ok': 0, 'precision_pct': None, 'unknown': 0, 'wrong': 0}; estrato outros {'n': 7, 'ok': 7, 'precision_pct': 100.0, 'unknown': 0, 'wrong': 0}. Revisao manual: 0 linhas.
+
+`affected` (profundidade 1) contra `rg -w`, so fontes main:
+
+| Simbolo | grafo | rg | ambos | so grafo | so rg | recall vs rg | precisao vs rg |
+|---|---|---|---|---|---|---|---|
+| confineToRoot (ok) | 2 | 3 | 2 | 0 | 1 | 66.7% | 100.0% |
+| sanitizedChildEnv (ok) | 2 | 2 | 2 | 0 | 0 | 100.0% | 100.0% |
+| verifySignature (ok) | 0 | 0 | 0 | 0 | 0 | n/d | n/d |
+| evaluateCommand (ok) | 0 | 0 | 0 | 0 | 0 | n/d | n/d |
+| resolveBindHost (ok) | 1 | 1 | 1 | 0 | 0 | 100.0% | 100.0% |
+| validateHeaderRoot (ok) | 1 | 1 | 1 | 0 | 0 | 100.0% | 100.0% |
+| BurstSuppressor (ok) | 1 | 1 | 1 | 0 | 0 | 100.0% | 100.0% |
+| isSecretEnvName (ok) | 0 | 0 | 0 | 0 | 0 | n/d | n/d |
+
+Agregado (profundidade 1): recall 87.5%, precisao 100.0% (5 simbolos); profundidade 2: recall 87.5%.
+
+recall@8 no conjunto de referencia (6 perguntas):
+
+| Backend | Tipo | n | recall@8 | acerto@8 |
+|---|---|---|---|---|
+| graph | all | 6 | 66.7% | 66.7% |
+| graph | conceptual | 6 | 66.7% | 66.7% |
+| graph_call_only | all | 6 | 66.7% | 66.7% |
+| graph_call_only | conceptual | 6 | 66.7% | 66.7% |
+| lexical_auto | all | 6 | 91.7% | 100.0% |
+| lexical_auto | conceptual | 6 | 91.7% | 100.0% |
+| lexical_curated | all | 6 | 100.0% | 100.0% |
+| lexical_curated | conceptual | 6 | 100.0% | 100.0% |
+
+`lexical_auto` usa so o texto da pergunta (baseline justo para o fallback ripgrep); `lexical_curated` usa palavras escolhidas por quem conhecia a resposta (teto otimista, nao comparar).
+| vector (pgvector) | - | - | NAO MEDIDO | NAO MEDIDO |
+
+### vh-api-gateway
+
+- Corrida a frio: 19.47s, pico de RSS da arvore 795.9 MB (estimativa; maior filho 444.2 MB), nos 17654, arestas 71062, graphify-out 133.0 MB.
+- G1: 1549/1552 ficheiros de codigo com simbolos (99.81%); 3 sem simbolos, dos quais 0 em testes. Lista: src/main/java/io/visionhammer/gateway/filter/RequestLoggingFilter.java, src/main/java/io/visionhammer/gateway/logs/api/LogsController.java, src/main/java/io/visionhammer/gateway/security/bo/package-info.java
+- G2: INFERRED 12.22% (8.86% so em fontes main); INFERRED por relacao {'calls': 8263, 'references': 423}.
+- G8 determinismo: assinatura 0bbbea2d3be0dc3d vs 0bbbea2d3be0dc3d, igual: True.
+- Incremental (1 ficheiro alterado: src/main/java/io/visionhammer/gateway/admin/api/AdminInsightsController.java): 21.64s, 1093.5 MB; simbolo novo no grafo: True; sem alteracoes: 12.98s.
+- G7 rede bloqueada (sandbox-exec (deny network*)): exit 0, 0 eventos socket, 2 subprocess.Popen (('git', ['git', 'rev-parse', 'HEAD'], '/private/tmp/claude-501/-Users-).
+- G2 amostra (seed 20261028, n=60): oraculo ok/wrong/unknown {'ok': 53, 'unknown': 4, 'wrong': 3}; precisao nas decididas 94.6%; estrato ambiguo {'n': 20, 'ok': 16, 'precision_pct': 84.2, 'unknown': 1, 'wrong': 3}; estrato outros {'n': 40, 'ok': 37, 'precision_pct': 100.0, 'unknown': 3, 'wrong': 0}. Revisao manual: 0 linhas.
+
+`affected` (profundidade 1) contra `rg -w`, so fontes main:
+
+| Simbolo | grafo | rg | ambos | so grafo | so rg | recall vs rg | precisao vs rg |
+|---|---|---|---|---|---|---|---|
+| TenantAccessGuard (ok) | 21 | 21 | 21 | 0 | 0 | 100.0% | 100.0% |
+| PolicyGate (ok) | 4 | 40 | 4 | 0 | 36 | 10.0% | 100.0% |
+| EgressUrlGuard (ok) | 11 | 13 | 11 | 0 | 2 | 84.6% | 100.0% |
+| SlackRequestVerifier (ok) | 2 | 6 | 2 | 0 | 4 | 33.3% | 100.0% |
+| JwtTokenProvider (ok) | 8 | 8 | 8 | 0 | 0 | 100.0% | 100.0% |
+| AuthRateLimiter (ok) | 4 | 5 | 4 | 0 | 1 | 80.0% | 100.0% |
+| DataErasureService (ok) | 0 | 2 | 0 | 0 | 2 | 0.0% | n/d |
+| EmailService (ok) | 7 | 9 | 7 | 0 | 2 | 77.8% | 100.0% |
+
+Agregado (profundidade 1): recall 54.8%, precisao 100.0% (8 simbolos); profundidade 2: recall 57.7%.
+
+recall@8 no conjunto de referencia (8 perguntas):
+
+| Backend | Tipo | n | recall@8 | acerto@8 |
+|---|---|---|---|---|
+| graph | all | 8 | 43.8% | 50.0% |
+| graph | conceptual | 6 | 25.0% | 33.3% |
+| graph | symbolic | 2 | 100.0% | 100.0% |
+| graph_call_only | all | 8 | 43.8% | 50.0% |
+| graph_call_only | conceptual | 6 | 25.0% | 33.3% |
+| graph_call_only | symbolic | 2 | 100.0% | 100.0% |
+| lexical_auto | all | 8 | 87.5% | 87.5% |
+| lexical_auto | conceptual | 6 | 100.0% | 100.0% |
+| lexical_auto | symbolic | 2 | 50.0% | 50.0% |
+| lexical_curated | all | 8 | 100.0% | 100.0% |
+| lexical_curated | conceptual | 6 | 100.0% | 100.0% |
+| lexical_curated | symbolic | 2 | 100.0% | 100.0% |
+
+`lexical_auto` usa so o texto da pergunta (baseline justo para o fallback ripgrep); `lexical_curated` usa palavras escolhidas por quem conhecia a resposta (teto otimista, nao comparar).
+| vector (pgvector) | - | - | NAO MEDIDO | NAO MEDIDO |
+
+### visionhammer-agents
+
+- Corrida a frio: 15.27s, pico de RSS da arvore 793.7 MB (estimativa; maior filho 439.7 MB), nos 16776, arestas 60583, graphify-out 121.6 MB.
+- G1: 1056/1056 ficheiros de codigo com simbolos (100.0%); 0 sem simbolos, dos quais 0 em testes. Lista: nenhum
+- G2: INFERRED 14.05% (12.87% so em fontes main); INFERRED por relacao {'calls': 5980, 'references': 2534}.
+- G8 determinismo: assinatura 703f4318fc6b20a3 vs 703f4318fc6b20a3, igual: True.
+- Incremental (1 ficheiro alterado: agents/cloud-engineer/src/main/java/io/visionhammer/agents/agent1/controller/Agent1Controller.java): 18.68s, 1123.9 MB; simbolo novo no grafo: True; sem alteracoes: 11.32s.
+- G7 rede bloqueada (sandbox-exec (deny network*)): exit 0, 0 eventos socket, 2 subprocess.Popen (('git', ['git', 'rev-parse', 'HEAD'], '/private/tmp/claude-501/-Users-).
+- G2 amostra (seed 20261028, n=60): oraculo ok/wrong/unknown {'ok': 53, 'unknown': 7}; precisao nas decididas 100.0%; estrato ambiguo {'n': 20, 'ok': 18, 'precision_pct': 100.0, 'unknown': 2, 'wrong': 0}; estrato outros {'n': 40, 'ok': 35, 'precision_pct': 100.0, 'unknown': 5, 'wrong': 0}. Revisao manual: 0 linhas.
+
+`affected` (profundidade 1) contra `rg -w`, so fontes main:
+
+| Simbolo | grafo | rg | ambos | so grafo | so rg | recall vs rg | precisao vs rg |
+|---|---|---|---|---|---|---|---|
+| ContextAssembler (ok) | 7 | 15 | 7 | 0 | 8 | 46.7% | 100.0% |
+| VoyageEmbeddingClient (ok) | 7 | 9 | 7 | 0 | 2 | 77.8% | 100.0% |
+| PiiEgressMasker (ok) | 21 | 21 | 21 | 0 | 0 | 100.0% | 100.0% |
+| SecretMasker (ok) | 1 | 1 | 1 | 0 | 0 | 100.0% | 100.0% |
+| CorrelationIdDetector (ok) | 2 | 2 | 2 | 0 | 0 | 100.0% | 100.0% |
+| LiteLlmChatAdapter (ok) | 11 | 1 | 0 | 11 | 1 | 0.0% | 0.0% |
+| PolicyGateGuard (ok) | 4 | 4 | 4 | 0 | 0 | 100.0% | 100.0% |
+| ChunkRemaskService (ok) | 1 | 3 | 1 | 0 | 2 | 33.3% | 100.0% |
+
+Agregado (profundidade 1): recall 76.8%, precisao 79.6% (8 simbolos); profundidade 2: recall 76.8%.
+
+recall@8 no conjunto de referencia (8 perguntas):
+
+| Backend | Tipo | n | recall@8 | acerto@8 |
+|---|---|---|---|---|
+| graph | all | 8 | 62.5% | 62.5% |
+| graph | conceptual | 7 | 57.1% | 57.1% |
+| graph | symbolic | 1 | 100.0% | 100.0% |
+| graph_call_only | all | 8 | 62.5% | 62.5% |
+| graph_call_only | conceptual | 7 | 57.1% | 57.1% |
+| graph_call_only | symbolic | 1 | 100.0% | 100.0% |
+| lexical_auto | all | 8 | 75.0% | 75.0% |
+| lexical_auto | conceptual | 7 | 71.4% | 71.4% |
+| lexical_auto | symbolic | 1 | 100.0% | 100.0% |
+| lexical_curated | all | 8 | 100.0% | 100.0% |
+| lexical_curated | conceptual | 7 | 100.0% | 100.0% |
+| lexical_curated | symbolic | 1 | 100.0% | 100.0% |
+
+`lexical_auto` usa so o texto da pergunta (baseline justo para o fallback ripgrep); `lexical_curated` usa palavras escolhidas por quem conhecia a resposta (teto otimista, nao comparar).
+| vector (pgvector) | - | - | NAO MEDIDO | NAO MEDIDO |
+
+## 3. Spring/DI (fixture sintetica)
+
+| Grupo | Encontrado | Esperado | % |
+|---|---|---|---|
+| bean_methods | 2 | 4 | 50.0% |
+| interface_impl | 5 | 8 | 62.5% |
+| lombok_injection | 4 | 4 | 100.0% |
+| qualifier | 0 | 3 | 0.0% |
+
+Itens em falta:
+
+- bean_methods / bean-clock-consumed-by-audit-bean: not reachable within 2 hops
+- bean_methods / bean-consumer-checkout-audit: not reachable within 2 hops
+- interface_impl / checkout-reaches-stripe-impl: not reachable within 2 hops
+- interface_impl / refund-reaches-paypal-impl: not reachable within 2 hops
+- interface_impl / refund-reaches-stripe-impl: not reachable within 2 hops
+- qualifier / qualifier-stripe-selected: not reachable within 2 hops
+- qualifier / qualifier-stripe-not-paypal: vacuous: companion check qualifier-stripe-selected failed, so absence proves nothing
+- qualifier / qualifier-fastcache-bean: not reachable within 2 hops
+
+## 4. Licencas das dependencias instaladas
+
+32 distribuicoes; permissivas 32; a rever nenhuma; desconhecidas nenhuma; sem ficheiro de licenca ['tree-sitter-groovy'].
+
+## 5. pip-audit
+
+0 vulnerabilidades conhecidas em 32 pacotes (exit 0)
+
+## 6. O que este relatorio nao mediu
+
+- recall@8 contra pgvector: precisa do dataset do RagEvalController e da BD de QA (passar `--vector-results`).
+- G6 (incidentes ponta a ponta sem Voyage), G9 (imagem local-agent-full) e G10 (repo do piloto, Python/SQL/Go/Terraform reais).
+- Revisao manual por 2 pessoas das arestas INFERRED (o CSV em `review/` esta pronto para isso).
+- Desempenho em 2 vCPU/4 GB e no hardware do piloto.