wendkeep 0.85.1 → 0.87.0

package/schema/commit-message-v1.schema.json

@@ -0,0 +1,75 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://wendkeep.dev/schema/commit-message-v1.schema.json",
+  "title": "WendKeep evidence-based commit input",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "subject", "capability", "authority", "evidence"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "subject": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "summary"],
+      "properties": {
+        "type": { "enum": ["feat", "fix", "refactor", "perf"] },
+        "scope": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._/-]*$" },
+        "summary": { "type": "string", "minLength": 1, "maxLength": 120 }
+      }
+    },
+    "capability": { "type": "string", "minLength": 1, "maxLength": 500 },
+    "authority": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "adr", "ref"],
+          "properties": {
+            "kind": { "const": "adr" },
+            "adr": { "type": "string", "pattern": "^ADR-[0-9]{4,}$" },
+            "ref": { "type": "string", "minLength": 1 },
+            "issue": { "type": "string", "pattern": "^#[0-9]+$" }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind", "issue", "design"],
+          "properties": {
+            "kind": { "const": "native" },
+            "issue": { "type": "string", "pattern": "^#[0-9]+$" },
+            "design": { "type": "string", "pattern": "^(docs/superpowers/specs|plans)/(?!\\.{1,2}(?:/|$))(?!.*//)(?!.*\\/\\.{1,2}(?:\\/|$))[a-zA-Z0-9._/-]+\\.md$" }
+          }
+        }
+      ]
+    },
+    "staged_diff": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["sha256", "files"],
+      "properties": {
+        "sha256": { "type": "string", "pattern": "^[a-fA-F0-9]{64}$" },
+        "files": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } }
+      }
+    },
+    "evidence": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["kind", "ref"],
+        "properties": {
+          "kind": { "enum": ["adr", "design", "evidence", "receipt", "spec", "task", "verdict"] },
+          "ref": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "limits": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+    "identity": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": { "agent": { "type": "string" } }
+    }
+  }
+}

package/scripts/validate-commit-range.mjs

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+import { createHash } from 'node:crypto';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+import {
+  messageEvidence, messageScope, messageTasks, messageTests, nativeDesignReference, validateCommitMessage,
+} from '../packages/commit/src/index.mjs';
+import {
+  collectCommitSensorProof,
+  commitTaskSensorIds,
+  parseSignedEvidenceRef,
+  validateCommitProofSet,
+} from '../packages/commit/src/proof-validation.mjs';
+
+function option(argv, name) {
+  const index = argv.indexOf(name);
+  if (index >= 0) return argv[index + 1] || '';
+  return argv.find((item) => item.startsWith(`${name}=`))?.slice(name.length + 1) || '';
+}
+
+function git(args, { binary = false, allowFailure = false } = {}) {
+  const result = spawnSync('git', args, {
+    encoding: binary ? null : 'utf8', windowsHide: true, maxBuffer: 64 * 1024 * 1024,
+  });
+  if (!allowFailure && result.status !== 0) {
+    process.stderr.write((binary ? result.stderr?.toString('utf8') : result.stderr) || `git ${args.join(' ')} failed\n`);
+    process.exit(2);
+  }
+  return result;
+}
+const text = (args, options) => String(git(args, options).stdout || '');
+const objectExists = (specifier) => git(['cat-file', '-e', specifier], { allowFailure: true }).status === 0;
+const parents = (sha) => text(['show', '-s', '--format=%P', sha]).trim().split(/\s+/).filter(Boolean);
+
+function commitDiff(sha) {
+  const parent = parents(sha)[0];
+  const args = parent
+    ? ['diff', '--binary', '--no-ext-diff', '--no-color', parent, sha]
+    : ['show', '--format=', '--binary', '--no-ext-diff', '--no-color', sha];
+  return git(args, { binary: true }).stdout;
+}
+
+function changedFiles(sha) {
+  const parent = parents(sha)[0];
+  const args = parent
+    ? ['diff', '--name-only', '-z', '--no-renames', parent, sha]
+    : ['diff-tree', '--root', '--no-commit-id', '--name-only', '-z', '-r', sha];
+  return text(args).split('\0').filter(Boolean).map((path) => path.replaceAll('\\', '/'))
+    .sort((left, right) => left.localeCompare(right, 'en'));
+}
+
+function scopeFor(sha) {
+  return { sha256: createHash('sha256').update(commitDiff(sha)).digest('hex'), files: changedFiles(sha) };
+}
+
+const docsPath = (path) => /^(?:docs\/|README(?:\.en)?\.md$|[^/]+\.md$)/.test(path);
+const testPath = (path) => /^(?:tests?\/|fixtures?\/)/.test(path) || /(?:^|\/)__tests__\//.test(path);
+function trivialCommit(subject, files) {
+  if (!files.length) return false;
+  if (/^docs(?:\([^)]*\))?:/.test(subject)) return files.every(docsPath);
+  if (/^test(?:\([^)]*\))?:/.test(subject)) return files.every(testPath);
+  if (/^chore(?:\([^)]*\))?:/.test(subject)) return files.every((path) => docsPath(path) || testPath(path));
+  return false;
+}
+
+function mergeErrors(sha, message) {
+  const commitParents = parents(sha);
+  if (commitParents.length < 2 || !/^Merge\b/.test(message.split(/\r?\n/, 1)[0])) {
+    return ['merge commit must have multiple parents and a canonical Merge subject'];
+  }
+  const errors = [];
+  for (const path of changedFiles(sha)) {
+    const mergeObject = text(['rev-parse', `${sha}:${path}`], { allowFailure: true }).trim();
+    if (!mergeObject) continue;
+    const inherited = commitParents.some((parent) => (
+      text(['rev-parse', `${parent}:${path}`], { allowFailure: true }).trim() === mergeObject
+    ));
+    if (!inherited) errors.push(`WENDKEEP_COMMIT_MERGE_RESOLUTION_UNGOVERNED: ${path}`);
+  }
+  return errors;
+}
+
+function commitJson(sha, path) {
+  try { return JSON.parse(text(['show', `${sha}:${path}`])); } catch { return null; }
+}
+
+function collectSensorsAtCommit(sha, entries) {
+  const ids = commitTaskSensorIds(entries);
+  if (!ids.length) return null;
+  const config = commitJson(sha, 'wendkeep.sensors.json');
+  if (!config || !Array.isArray(config.sensors)) {
+    throw Object.assign(new Error('versioned wendkeep.sensors.json is required'), {
+      code: 'WENDKEEP_COMMIT_SENSOR_CONFIG_MISSING',
+    });
+  }
+  const parent = mkdtempSync(join(tmpdir(), 'wendkeep-commit-range-'));
+  const checkout = join(parent, 'checkout');
+  const added = git(['worktree', 'add', '--detach', '--force', checkout, sha], { allowFailure: true });
+  if (added.status !== 0) {
+    rmSync(parent, { recursive: true, force: true });
+    throw Object.assign(new Error(String(added.stderr || 'temporary commit checkout failed').trim()), {
+      code: 'WENDKEEP_COMMIT_CHECKOUT_FAILED',
+    });
+  }
+  try {
+    return collectCommitSensorProof({ sensors: config.sensors, ids, cwd: checkout });
+  } finally {
+    git(['worktree', 'remove', '--force', checkout], { allowFailure: true });
+    const bounded = resolve(parent);
+    if (bounded.startsWith(resolve(tmpdir()))) rmSync(bounded, { recursive: true, force: true });
+  }
+}
+
+function evidenceErrors(sha, message, scope) {
+  const errors = [];
+  const evidence = messageEvidence(message);
+  const entries = [];
+  for (const item of evidence) {
+    if (item.status !== 'verified' || ['evidence', 'receipt', 'verdict'].includes(item.kind)) {
+      errors.push('WENDKEEP_COMMIT_REMOTE_PROOF_UNAVAILABLE');
+      continue;
+    }
+    let signed;
+    try { signed = parseSignedEvidenceRef(item.ref); }
+    catch (error) { errors.push(error.code || error.message); continue; }
+    if (!objectExists(`${sha}:${signed.path}`)) {
+      errors.push(`WENDKEEP_COMMIT_EVIDENCE_UNVERSIONED: ${signed.path}`);
+      continue;
+    }
+    entries.push({ kind: item.kind, path: signed.path, sha256: signed.sha256, content: text(['show', `${sha}:${signed.path}`]) });
+    if (item.status !== 'verified') errors.push(`WENDKEEP_COMMIT_EVIDENCE_STATUS_INVALID: ${signed.path}`);
+  }
+  const adr = message.match(/^ADR:\s*(ADR-\d{4,})$/m)?.[1] || '';
+  const design = nativeDesignReference(message);
+  const authority = adr
+    ? { kind: 'adr', adr, ref: entries.find((entry) => entry.kind === 'adr')?.path || '', issue: message.match(/^Refs:\s*(#\d+)$/m)?.[1] || '' }
+    : { kind: 'native', issue: message.match(/^Issue:\s*(#\d+)$/m)?.[1] || '', design };
+  try {
+    const config = commitJson(sha, '.wendkeep.json') || {};
+    const executionProof = collectSensorsAtCommit(sha, entries);
+    const snapshot = {
+      head_sha: parents(sha)[0] || sha,
+      index_tree_sha: text(['show', '-s', '--format=%T', sha]).trim(),
+    };
+    const resolved = validateCommitProofSet({
+      entries, authority, stagedHash: scope.sha256,
+      context: {
+        projectId: config.projectId || '',
+        changeSlug: adr ? adr.toLowerCase() : `issue-${authority.issue.slice(1)}`,
+        baseSha: snapshot.base_sha,
+        headSha: snapshot.head_sha,
+        indexTreeSha: snapshot.index_tree_sha,
+        worktreeDigest: snapshot.worktree_digest,
+        dirty: snapshot.dirty,
+        sensorConfigSha256: executionProof?.configSha256,
+        executionProof,
+        profile: String(config?.harness?.profile || 'OFF').toUpperCase(),
+      },
+    });
+    if (JSON.stringify(messageTasks(message)) !== JSON.stringify(resolved.tasks)) errors.push('WENDKEEP_COMMIT_TASKS_MISMATCH');
+    if (JSON.stringify(messageTests(message)) !== JSON.stringify(resolved.tests)) errors.push('WENDKEEP_COMMIT_TESTS_MISMATCH');
+  } catch (error) {
+    errors.push(`${error.code || 'WENDKEEP_COMMIT_EVIDENCE_UNVERIFIED'}: ${error.message}`);
+  }
+  return errors;
+}
+
+function authorityErrors(sha, message) {
+  const errors = [];
+  const design = nativeDesignReference(message);
+  if (!design) return errors;
+  if (!objectExists(`${sha}:${design}`)) return [`WENDKEEP_COMMIT_DESIGN_UNVERSIONED: ${design}`];
+  const issue = message.match(/^Issue:\s*(#\d+)$/m)?.[1] || '';
+  const content = text(['show', `${sha}:${design}`]);
+  if (!content.includes(issue)) errors.push('WENDKEEP_COMMIT_NATIVE_ISSUE_UNVERIFIED');
+  const config = commitJson(sha, '.wendkeep.json');
+  if (String(config?.harness?.profile || '').toUpperCase() !== 'OFF') errors.push('WENDKEEP_COMMIT_NATIVE_PROFILE_REQUIRED');
+  const adrPaths = text(['ls-tree', '-r', '--name-only', sha]).split(/\r?\n/)
+    .filter((path) => /ADR-\d+.*\.md$/i.test(path));
+  if (adrPaths.some((path) => {
+    const adr = text(['show', `${sha}:${path}`]);
+    return adr.includes(issue) && adr.includes(design.split('/').at(-1));
+  })) errors.push('WENDKEEP_COMMIT_CAUSAL_AUTHORITY_EXISTS');
+  return errors;
+}
+
+function configuredPrivacyErrors(sha, message) {
+  const config = commitJson(sha, '.wendkeep.json');
+  const vault = typeof config?.vault === 'string' ? config.vault.replaceAll('\\', '/').trim() : '';
+  if (!vault) return [];
+  const name = vault.split('/').filter(Boolean).at(-1) || '';
+  const lower = message.toLowerCase();
+  return [vault, name].some((marker) => marker.length >= 3 && lower.includes(marker.toLowerCase()))
+    ? ['WENDKEEP_COMMIT_PRIVATE_PATH: message references the configured project Vault'] : [];
+}
+
+const base = option(process.argv.slice(2), '--base') || process.env.WENDKEEP_COMMIT_BASE || '';
+const head = option(process.argv.slice(2), '--head') || process.env.WENDKEEP_COMMIT_HEAD || 'HEAD';
+if (!base) {
+  process.stderr.write('WENDKEEP_COMMIT_ARGUMENT: --base is required\n');
+  process.exit(2);
+}
+
+const commits = text(['rev-list', '--reverse', `${base}..${head}`]).trim().split(/\r?\n/).filter(Boolean);
+const failures = [];
+for (const sha of commits) {
+  const message = text(['show', '-s', '--format=%B', sha]);
+  const subject = message.split(/\r?\n/, 1)[0];
+  const commitParents = parents(sha);
+  const errors = [...configuredPrivacyErrors(sha, message)];
+  if (commitParents.length > 1) {
+    errors.push(...mergeErrors(sha, message));
+  } else {
+    const result = validateCommitMessage(message);
+    errors.push(...result.errors);
+    if (messageEvidence(message).some((item) => (
+      item.status !== 'verified' || ['evidence', 'receipt', 'verdict'].includes(item.kind)
+    ))) errors.push('WENDKEEP_COMMIT_REMOTE_PROOF_UNAVAILABLE');
+    const files = changedFiles(sha);
+    if (!result.governed && !trivialCommit(subject, files)) errors.push('WENDKEEP_COMMIT_PRODUCT_CHANGE_UNGOVERNED');
+    if (result.governed && result.ok) {
+      const expected = scopeFor(sha);
+      const observed = messageScope(message);
+      if (expected.sha256 !== observed.sha256 || JSON.stringify(expected.files) !== JSON.stringify(observed.files)) {
+        errors.push('WENDKEEP_COMMIT_SCOPE_MISMATCH');
+      }
+      errors.push(...evidenceErrors(sha, message, expected), ...authorityErrors(sha, message));
+    }
+  }
+  if (errors.length) failures.push({ sha, subject, errors: [...new Set(errors)] });
+}
+
+if (failures.length) {
+  process.stderr.write(`WENDKEEP_COMMIT_RANGE_INVALID: ${failures.length} invalid commit(s)\n`);
+  for (const failure of failures) {
+    process.stderr.write(`${failure.sha.slice(0, 12)} ${failure.subject}\n`);
+    for (const error of failure.errors) process.stderr.write(`  - ${error}\n`);
+  }
+  process.exit(1);
+}
+process.stdout.write(`${commits.length} commit(s) valid\n`);

package/src/doctor.mjs

@@ -4,6 +4,11 @@ import { resolve } from 'node:path';
 import { checkHarness, checkVaultLinks, checkSessionActivity, checkStackedFrontmatter, renderStackedFrontmatterLines, checkUnpricedModels, renderUnpricedModelLines, checkStaleDerivedSections, renderStaleDerivedSectionLines, checkSessionObservability, renderSessionObservabilityLines } from '../hooks/harness-doctor.mjs';
 import { diagnoseManagedWorktrees } from './worktree.mjs';
 import { runVaultHealth } from '../hooks/vault-health.mjs';
+import {
+  inspectEvidenceSearchHealth,
+  renderEvidenceSearchHealthLines,
+} from './evidence-search-health.mjs';
+import { augmentVaultHealthWithMemoryScale } from './memory-scale-health.mjs';
 import { checkSyncDefs } from './sync-defs.mjs';
 import { resolveProjectVault } from './project-vault.mjs';
 import { inspectObserverSqlOutbox } from './observer-sql-publish.mjs';
@@ -14,11 +19,18 @@ import {
 import { inspectPortableState } from './portable.mjs';
 import { inspectSyncOutbox, readLocalSyncState } from './sync-outbox.mjs';
 import { readProjectForValidation } from '../packages/vault/src/validate-memory.mjs';
+import { inspectGitCommitHooks } from './git-commit-hooks.mjs';
 
 const healthStatusLabel = (status) => ({
   healthy: 'saudável', warning: 'atenção', degraded: 'degradada', blocked: 'bloqueada', legacy: 'legado',
 }[status] || status || 'desconhecido');
 
+const artifactStatusLabel = (status) => ({
+  ok: 'saudável', healthy: 'saudável', warning: 'atenção', degraded: 'degradado',
+  missing: 'ausente', empty: 'vazio', invalid: 'inválido', corrupt: 'corrompido',
+  blocked: 'bloqueado', unknown: 'desconhecido',
+}[status] || status || 'desconhecido');
+
 const metricValue = (value) => value === null || value === undefined || value === '' ? 'n/a' : value;
 
 export function renderVaultHealthLines(result) {
@@ -49,6 +61,19 @@ export function renderVaultHealthLines(result) {
   );
   const repairableHandoffs = Number(memory.repairableHandoffs || 0);
   lines.push(`  ledger: ${metricValue(memory.ledgerEvents)} evento(s) · outbox: ${metricValue(memory.pendingOutbox)} · candidates: ${metricValue(memory.candidates)} · conflitos: ${metricValue(memory.activeConflicts)}${repairableHandoffs ? ` · handoffs reparáveis: ${repairableHandoffs}` : ''}`);
+  if (memory.scaleSchemaVersion === 1) {
+    lines.push(
+      `  replay: snapshot ${artifactStatusLabel(memory.snapshotStatus)} · cobertos: ${metricValue(memory.snapshotEvents)} evento(s) · tail: ${metricValue(memory.snapshotTailEvents)} evento(s)/${metricValue(memory.snapshotTailBytes)} bytes · ledger no snapshot: ${metricValue(memory.snapshotLedgerBytes)} bytes`,
+    );
+    if (memory.snapshotReason) lines.push(`    ↳ snapshot: ${memory.snapshotReason}`);
+    lines.push(
+      `  segmentos: ${artifactStatusLabel(memory.segmentStatus)} · ${metricValue(memory.segmentCount)} segmento(s) · cobertos: ${metricValue(memory.segmentCoveredEvents)} evento(s)/${metricValue(memory.segmentCoveredBytes)} bytes · pendentes: ${metricValue(memory.segmentPendingEvents)}`,
+    );
+    lines.push(
+      `  rotação: geração ${artifactStatusLabel(memory.generationStatus)} #${metricValue(memory.generation)} · origem: ${metricValue(memory.generationSourceEvents)} · tail ativo: ${metricValue(memory.generationActiveTailEvents)} · journal: ${artifactStatusLabel(memory.rotationJournal)} · receipts: ${metricValue(memory.rotationReceipts)} (${artifactStatusLabel(memory.rotationReceiptCheckpoint)})`,
+    );
+    if (memory.scaleErrorCode) lines.push(`    ↳ escala: ${memory.scaleErrorCode}`);
+  }
   const semanticKeys = memory.semanticActiveKeys || [];
   const semanticProjected = memory.semanticProjectedKeys || [];
   const semanticMissing = memory.semanticMissingKeys || [];
@@ -105,7 +130,10 @@ export function runDoctor(argv) {
   // 1. Session/vault integrity. The standalone hook remains JSON; doctor renders it for humans.
   let health;
   try {
-    health = runVaultHealth({ vaultBase, session });
+    health = augmentVaultHealthWithMemoryScale(
+      runVaultHealth({ vaultBase, session }),
+      vaultBase,
+    );
   } catch (error) {
     health = {
       ok: false,
@@ -116,16 +144,24 @@ export function runDoctor(argv) {
       memoryStatus: 'blocked',
     };
   }
-  if (scope !== 'runtime') process.stdout.write(`${renderVaultHealthLines(health).join('\n')}\n`);
+  const recall = scope === 'runtime'
+    ? { status: 'skipped' }
+    : inspectEvidenceSearchHealth(vaultBase);
+  if (scope !== 'runtime') {
+    process.stdout.write(`${renderVaultHealthLines(health).join('\n')}\n`);
+    process.stdout.write(`${renderEvidenceSearchHealthLines(recall).join('\n')}\n`);
+  }
   const healthStatus = health.ok ? 0 : 1;
+  const recallStatus = recall.status === 'blocked' ? 1 : 0;
 
   if (scope === 'core') {
     const strictDebt = strict && (
       (health.warnings || []).length > 0
       || !['healthy'].includes(health.memoryStatus)
+      || !['healthy', 'missing'].includes(recall.status)
     );
-    process.stdout.write(`\n[core] ${healthStatus ? 'erro estrutural' : health.memoryStatus === 'degraded' ? 'saudável com memória degradada' : 'saudável'}\n`);
-    return healthStatus || strictDebt ? 1 : 0;
+    process.stdout.write(`\n[core] ${healthStatus || recallStatus ? 'erro estrutural' : health.memoryStatus === 'degraded' ? 'saudável com memória degradada' : 'saudável'}\n`);
+    return healthStatus || recallStatus || strictDebt ? 1 : 0;
   }
 
   // 2. Harness integrity (Wave B).
@@ -147,6 +183,11 @@ export function runDoctor(argv) {
     process.stdout.write(`  → ${issue.slug}: ${issue.errorCode} — ${issue.repair}\n`);
   }
 
+  const commitHooks = inspectGitCommitHooks({ projectRoot });
+  process.stdout.write(`\n[commit-hooks] ${commitHooks.status}\n`);
+  for (const issue of commitHooks.issues) process.stdout.write(`  ! ${issue}\n`);
+  if (commitHooks.repair) process.stdout.write(`  → ${commitHooks.repair}\n`);
+
   const activeContexts = inspectActiveContextHealth({ vaultBase, projectRoot });
   process.stdout.write(`\n${renderActiveContextHealthLines(activeContexts).join('\n')}\n`);
 
@@ -217,10 +258,12 @@ export function runDoctor(argv) {
   const strictDebt = strict && (
     (scope !== 'runtime' && (health.warnings || []).length)
     || (scope !== 'runtime' && health.memoryStatus !== 'healthy')
+    || (scope !== 'runtime' && !['healthy', 'missing'].includes(recall.status))
     || attention.length
     || repairable.length
     || warnings.length
     || worktrees.issues.length
+    || (commitHooks.configured && commitHooks.status !== 'healthy')
     || activeContexts.issues.length
     || ['diverged', 'invalid'].includes(portable.status)
     || sync.status === 'corrupt'
@@ -233,5 +276,5 @@ export function runDoctor(argv) {
     || (staleDerived.notes || staleDerived.items || []).length
     || !observability.ok
   );
-  return (scope !== 'runtime' && healthStatus !== 0) || errors.length || strictDebt ? 1 : 0;
+  return (scope !== 'runtime' && (healthStatus !== 0 || recallStatus !== 0)) || errors.length || strictDebt ? 1 : 0;
 }

package/src/evidence-search-health.mjs

@@ -0,0 +1,221 @@
+import { statSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  EVIDENCE_INDEX_FILE,
+} from '../packages/vault/src/evidence-recall.mjs';
+import {
+  EVIDENCE_INDEX_STATE_FILE,
+  loadEvidenceIndexState,
+} from '../packages/vault/src/evidence-index-store.mjs';
+import {
+  EVIDENCE_SEARCH_STATE_FILE,
+  evidenceSearchSqliteAvailable,
+  loadEvidenceSearchState,
+} from '../packages/vault/src/evidence-search-index.mjs';
+import { assertVaultPathSafe } from '../packages/vault/src/vault-path-safety.mjs';
+
+export const EVIDENCE_SEARCH_HEALTH_SCHEMA_VERSION = 1;
+
+function brainDir(vaultBase) {
+  return join(vaultBase, '.brain');
+}
+
+function nsText(value, fallbackMs = 0) {
+  if (typeof value === 'bigint') return value.toString();
+  return BigInt(Math.max(0, Math.trunc(Number(fallbackMs || 0) * 1_000_000))).toString();
+}
+
+function fileInfo(vaultBase, path, label) {
+  let checked = assertVaultPathSafe(vaultBase, path, {
+    expectedType: 'file',
+    label,
+  });
+  if (!checked.exists) return { exists: false, bytes: 0, fingerprint: null };
+  checked = assertVaultPathSafe(vaultBase, checked.target, {
+    allowMissing: false,
+    expectedType: 'file',
+    label,
+  });
+  const stat = statSync(checked.target, { bigint: true });
+  return {
+    exists: true,
+    bytes: Number(stat.size),
+    fingerprint: {
+      size: stat.size.toString(),
+      mtime_ns: nsText(stat.mtimeNs, stat.mtimeMs),
+      ctime_ns: nsText(stat.ctimeNs, stat.ctimeMs),
+    },
+  };
+}
+
+function sameFingerprint(left, right) {
+  if (left === null || right === null) return left === right;
+  return Boolean(left && right)
+    && String(left.size) === String(right.size)
+    && String(left.mtime_ns) === String(right.mtime_ns)
+    && String(left.ctime_ns) === String(right.ctime_ns);
+}
+
+function safeCode(value, fallback = '') {
+  const text = String(value || fallback).trim();
+  return text
+    ? text.replace(/[^A-Za-z0-9._:-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 120)
+    : null;
+}
+
+function artifactInfo(vaultBase, artifact, kind) {
+  if (!artifact) {
+    return { status: 'not-built', bytes: 0, current: false };
+  }
+  const path = join(brainDir(vaultBase), ...String(artifact.path || '').split('/'));
+  const file = fileInfo(vaultBase, path, `artefato ${kind} da busca de evidências`);
+  if (!file.exists) return { status: 'missing', bytes: 0, current: false };
+  const current = sameFingerprint(artifact.fingerprint, file.fingerprint);
+  return {
+    status: current ? 'current' : 'stale',
+    bytes: file.bytes,
+    current,
+  };
+}
+
+export function emptyEvidenceSearchHealth() {
+  return {
+    schemaVersion: EVIDENCE_SEARCH_HEALTH_SCHEMA_VERSION,
+    status: 'unknown',
+    errorCode: null,
+    authorityStatus: 'unknown',
+    authorityBytes: 0,
+    incrementalStateStatus: 'unknown',
+    incrementalStateBytes: 0,
+    documentCount: 0,
+    searchStateStatus: 'unknown',
+    searchStateBytes: 0,
+    rowCount: 0,
+    sourceIndexCurrent: false,
+    sourceStateCurrent: false,
+    lexicalStatus: 'unknown',
+    lexicalBytes: 0,
+    sqliteStatus: 'unknown',
+    sqliteBytes: 0,
+    sqliteCapability: false,
+    backend: 'unavailable',
+  };
+}
+
+function deriveStatus(metrics) {
+  if (metrics.authorityStatus === 'missing') return 'missing';
+  if (metrics.incrementalStateStatus === 'invalid'
+      || metrics.searchStateStatus === 'invalid') return 'degraded';
+  if (metrics.searchStateStatus !== 'current') return 'warning';
+  if (metrics.lexicalStatus !== 'current') return 'degraded';
+  return 'healthy';
+}
+
+export function inspectEvidenceSearchHealth(vaultBase) {
+  const metrics = emptyEvidenceSearchHealth();
+  try {
+    const brain = brainDir(vaultBase);
+    const authority = fileInfo(
+      vaultBase,
+      join(brain, EVIDENCE_INDEX_FILE),
+      'autoridade EVIDENCE_INDEX.jsonl',
+    );
+    const incrementalFile = fileInfo(
+      vaultBase,
+      join(brain, EVIDENCE_INDEX_STATE_FILE),
+      'estado incremental EVIDENCE_INDEX_STATE.json',
+    );
+    const searchFile = fileInfo(
+      vaultBase,
+      join(brain, EVIDENCE_SEARCH_STATE_FILE),
+      'estado derivado EVIDENCE_SEARCH_STATE.json',
+    );
+
+    metrics.authorityStatus = authority.exists ? 'present' : 'missing';
+    metrics.authorityBytes = authority.bytes;
+    metrics.incrementalStateBytes = incrementalFile.bytes;
+    metrics.searchStateBytes = searchFile.bytes;
+    metrics.sqliteCapability = evidenceSearchSqliteAvailable();
+
+    const incremental = incrementalFile.exists ? loadEvidenceIndexState(vaultBase) : null;
+    metrics.incrementalStateStatus = incrementalFile.exists
+      ? (incremental ? 'ok' : 'invalid')
+      : 'missing';
+    metrics.documentCount = incremental
+      ? Object.keys(incremental.documents || {}).length
+      : 0;
+
+    const state = searchFile.exists ? loadEvidenceSearchState(vaultBase) : null;
+    if (!searchFile.exists) {
+      metrics.searchStateStatus = 'missing';
+      metrics.lexicalStatus = 'not-built';
+      metrics.sqliteStatus = 'not-built';
+      metrics.backend = authority.exists ? 'lexical-ephemeral' : 'unavailable';
+      metrics.status = deriveStatus(metrics);
+      return metrics;
+    }
+    if (!state) {
+      metrics.searchStateStatus = 'invalid';
+      metrics.lexicalStatus = 'unknown';
+      metrics.sqliteStatus = 'unknown';
+      metrics.backend = authority.exists ? 'lexical-ephemeral' : 'unavailable';
+      metrics.status = deriveStatus(metrics);
+      return metrics;
+    }
+
+    metrics.rowCount = Number(state.row_count || 0);
+    metrics.sourceIndexCurrent = sameFingerprint(state.source?.index, authority.fingerprint);
+    metrics.sourceStateCurrent = sameFingerprint(
+      state.source?.state ?? null,
+      incrementalFile.fingerprint,
+    );
+    const lexical = artifactInfo(vaultBase, state.lexical, 'lexical');
+    const sqlite = artifactInfo(vaultBase, state.sqlite, 'SQLite FTS');
+    metrics.lexicalStatus = lexical.status;
+    metrics.lexicalBytes = lexical.bytes;
+    metrics.sqliteStatus = sqlite.status;
+    metrics.sqliteBytes = sqlite.bytes;
+
+    const sourceCurrent = metrics.sourceIndexCurrent && metrics.sourceStateCurrent;
+    const artifactsCurrent = lexical.current && (!state.sqlite || sqlite.current);
+    metrics.searchStateStatus = sourceCurrent && artifactsCurrent ? 'current' : 'stale';
+    metrics.backend = metrics.searchStateStatus === 'current'
+      && sqlite.current
+      && metrics.sqliteCapability
+      ? 'sqlite-fts5'
+      : metrics.searchStateStatus === 'current' && lexical.current
+        ? 'lexical-sidecar'
+        : authority.exists
+          ? 'lexical-ephemeral'
+          : 'unavailable';
+    metrics.status = deriveStatus(metrics);
+    return metrics;
+  } catch (error) {
+    return {
+      ...metrics,
+      status: 'blocked',
+      errorCode: safeCode(error?.code, 'EVIDENCE_SEARCH_HEALTH_UNSAFE'),
+    };
+  }
+}
+
+const statusLabel = (status) => ({
+  healthy: 'saudável', warning: 'atenção', degraded: 'degradado', blocked: 'bloqueado',
+  missing: 'ausente', current: 'atual', stale: 'stale', present: 'presente', ok: 'saudável',
+  invalid: 'inválido', 'not-built': 'não construído', unknown: 'desconhecido',
+}[status] || status || 'desconhecido');
+
+export function renderEvidenceSearchHealthLines(metrics) {
+  const lines = [
+    `[recall] ${statusLabel(metrics.status)} — backend: ${metrics.backend} · SQLite/FTS5: ${metrics.sqliteCapability ? 'disponível' : 'indisponível'}`,
+    `  autoridade: ${statusLabel(metrics.authorityStatus)} · ${metrics.authorityBytes} bytes · documentos: ${metrics.documentCount} · chunks: ${metrics.rowCount}`,
+    `  incremental: ${statusLabel(metrics.incrementalStateStatus)} · ${metrics.incrementalStateBytes} bytes · busca: ${statusLabel(metrics.searchStateStatus)} · ${metrics.searchStateBytes} bytes`,
+    `  lexical: ${statusLabel(metrics.lexicalStatus)} · ${metrics.lexicalBytes} bytes · SQLite: ${statusLabel(metrics.sqliteStatus)} · ${metrics.sqliteBytes} bytes`,
+  ];
+  if (metrics.searchStateStatus === 'stale' || metrics.searchStateStatus === 'missing') {
+    lines.push('  ! o próximo recall pode reconstruir o índice derivado a partir da autoridade JSONL');
+  }
+  if (metrics.errorCode) lines.push(`  ✗ ${metrics.errorCode}`);
+  return lines;
+}