scene-capability-engine 3.3.22 → 3.3.24

package/lib/commands/errorbook.js

@@ -1,4 +1,6 @@
 const crypto = require('crypto');
+const http = require('http');
+const https = require('https');
 const path = require('path');
 const fs = require('fs-extra');
 const chalk = require('chalk');
@@ -6,8 +8,14 @@ const Table = require('cli-table3');
 
 const ERRORBOOK_INDEX_API_VERSION = 'sce.errorbook.index/v0.1';
 const ERRORBOOK_ENTRY_API_VERSION = 'sce.errorbook.entry/v0.1';
+const ERRORBOOK_REGISTRY_API_VERSION = 'sce.errorbook.registry/v0.1';
+const ERRORBOOK_REGISTRY_CACHE_API_VERSION = 'sce.errorbook.registry-cache/v0.1';
+const ERRORBOOK_REGISTRY_INDEX_API_VERSION = 'sce.errorbook.registry-index/v0.1';
 const ERRORBOOK_STATUSES = Object.freeze(['candidate', 'verified', 'promoted', 'deprecated']);
 const TEMPORARY_MITIGATION_TAG = 'temporary-mitigation';
+const DEFAULT_ERRORBOOK_REGISTRY_CONFIG = '.sce/config/errorbook-registry.json';
+const DEFAULT_ERRORBOOK_REGISTRY_CACHE = '.sce/errorbook/registry-cache.json';
+const DEFAULT_ERRORBOOK_REGISTRY_EXPORT = '.sce/errorbook/exports/errorbook-registry-export.json';
 const STATUS_RANK = Object.freeze({
   deprecated: 0,
   candidate: 1,
@@ -39,6 +47,11 @@ const ONTOLOGY_TAG_ALIASES = Object.freeze({
 });
 const DEFAULT_PROMOTE_MIN_QUALITY = 75;
 const ERRORBOOK_RISK_LEVELS = Object.freeze(['low', 'medium', 'high']);
+const DEBUG_EVIDENCE_TAGS = Object.freeze([
+  'debug-evidence',
+  'diagnostic-evidence',
+  'debug-log'
+]);
 const HIGH_RISK_SIGNAL_TAGS = Object.freeze([
   'release-blocker',
   'security',
@@ -60,6 +73,28 @@ function resolveErrorbookPaths(projectPath = process.cwd()) {
   };
 }
 
+function resolveProjectPath(projectPath, maybeRelativePath, fallbackRelativePath) {
+  const normalized = normalizeText(maybeRelativePath || fallbackRelativePath || '');
+  if (!normalized) {
+    return path.resolve(projectPath, fallbackRelativePath || '');
+  }
+  return path.isAbsolute(normalized)
+    ? normalized
+    : path.resolve(projectPath, normalized);
+}
+
+function resolveErrorbookRegistryPaths(projectPath = process.cwd(), overrides = {}) {
+  const configFile = resolveProjectPath(projectPath, overrides.configPath, DEFAULT_ERRORBOOK_REGISTRY_CONFIG);
+  const cacheFile = resolveProjectPath(projectPath, overrides.cachePath, DEFAULT_ERRORBOOK_REGISTRY_CACHE);
+  const exportFile = resolveProjectPath(projectPath, overrides.exportPath, DEFAULT_ERRORBOOK_REGISTRY_EXPORT);
+  return {
+    projectPath,
+    configFile,
+    cacheFile,
+    exportFile
+  };
+}
+
 function nowIso() {
   return new Date().toISOString();
 }
@@ -451,6 +486,44 @@ function validateRecordPayload(payload) {
   }
 }
 
+function hasDebugEvidenceSignals(entry = {}) {
+  const tags = normalizeStringList(entry.tags).map((item) => item.toLowerCase());
+  if (tags.some((tag) => DEBUG_EVIDENCE_TAGS.includes(tag))) {
+    return true;
+  }
+
+  const verificationEvidence = normalizeStringList(entry.verification_evidence);
+  if (verificationEvidence.some((item) => /^debug:/i.test(item))) {
+    return true;
+  }
+
+  const sourceFiles = normalizeStringList(entry?.source?.files);
+  if (sourceFiles.some((item) => /(^|[\\/._-])(debug|trace|diagnostic|observability|telemetry|stack)/i.test(item))) {
+    return true;
+  }
+
+  const notes = normalizeText(entry.notes).toLowerCase();
+  if (notes && /(debug|trace|diagnostic|observability|telemetry|stack|日志|埋点|观测)/i.test(notes)) {
+    return true;
+  }
+
+  return false;
+}
+
+function enforceDebugEvidenceAfterRepeatedFailures(entry = {}, options = {}) {
+  const attemptCount = Number(options.attemptCount || 0);
+  if (!Number.isFinite(attemptCount) || attemptCount < 3) {
+    return;
+  }
+  if (hasDebugEvidenceSignals(entry)) {
+    return;
+  }
+  throw new Error(
+    'two failed fix rounds detected (attempt #3+): debug evidence is required. '
+    + 'Provide --verification "debug: ...", add tag debug-evidence, or include debug trace/log file references.'
+  );
+}
+
 function normalizeRecordPayload(options = {}, fromFilePayload = {}) {
   const temporaryMitigation = normalizeTemporaryMitigation(options, fromFilePayload);
   const payload = {
@@ -589,6 +662,382 @@ async function loadRecordPayloadFromFile(projectPath, sourcePath, fileSystem = f
   }
 }
 
+function normalizeStatusList(values = [], fallback = ['promoted']) {
+  const raw = Array.isArray(values) ? values : normalizeStringList(values);
+  const list = raw.length > 0 ? raw : fallback;
+  const normalized = list
+    .map((item) => normalizeText(item).toLowerCase())
+    .filter(Boolean);
+  const unique = Array.from(new Set(normalized));
+  for (const status of unique) {
+    if (!ERRORBOOK_STATUSES.includes(status)) {
+      throw new Error(`invalid status in list: ${status}`);
+    }
+  }
+  return unique;
+}
+
+function normalizeRegistrySource(input = {}) {
+  const candidate = input || {};
+  const name = normalizeText(candidate.name) || 'default';
+  const url = normalizeText(candidate.url || candidate.source);
+  const file = normalizeText(candidate.file || candidate.path);
+  const source = url || file;
+  const indexUrl = normalizeText(candidate.index_url || candidate.indexUrl || candidate.registry_index || candidate.registryIndex);
+  return {
+    name,
+    source,
+    index_url: indexUrl,
+    enabled: candidate.enabled !== false
+  };
+}
+
+function normalizeRegistryMode(value, fallback = 'cache') {
+  const normalized = normalizeText(`${value || ''}`).toLowerCase();
+  if (!normalized) {
+    return fallback;
+  }
+  if (['cache', 'remote', 'hybrid'].includes(normalized)) {
+    return normalized;
+  }
+  throw new Error('registry mode must be one of: cache, remote, hybrid');
+}
+
+async function readErrorbookRegistryConfig(paths, fileSystem = fs) {
+  const fallback = {
+    enabled: false,
+    search_mode: 'cache',
+    cache_file: DEFAULT_ERRORBOOK_REGISTRY_CACHE,
+    sources: []
+  };
+  if (!await fileSystem.pathExists(paths.configFile)) {
+    return fallback;
+  }
+  const payload = await fileSystem.readJson(paths.configFile).catch(() => null);
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return fallback;
+  }
+  const sources = Array.isArray(payload.sources)
+    ? payload.sources.map((item) => normalizeRegistrySource(item)).filter((item) => item.enabled && item.source)
+    : [];
+  return {
+    enabled: normalizeBoolean(payload.enabled, true),
+    search_mode: normalizeRegistryMode(payload.search_mode || payload.searchMode, 'cache'),
+    cache_file: normalizeText(payload.cache_file || payload.cacheFile || DEFAULT_ERRORBOOK_REGISTRY_CACHE),
+    sources
+  };
+}
+
+function isHttpSource(source = '') {
+  return /^https?:\/\//i.test(normalizeText(source));
+}
+
+function fetchJsonFromHttp(source, timeoutMs = 15000) {
+  const normalized = normalizeText(source);
+  if (!normalized) {
+    return Promise.reject(new Error('registry source is required'));
+  }
+  const client = normalized.startsWith('https://') ? https : http;
+  return new Promise((resolve, reject) => {
+    const request = client.get(normalized, {
+      timeout: timeoutMs,
+      headers: {
+        Accept: 'application/json'
+      }
+    }, (response) => {
+      const chunks = [];
+      response.on('data', (chunk) => chunks.push(chunk));
+      response.on('end', () => {
+        const body = Buffer.concat(chunks).toString('utf8');
+        if (response.statusCode < 200 || response.statusCode >= 300) {
+          reject(new Error(`registry source responded ${response.statusCode}`));
+          return;
+        }
+        try {
+          resolve(JSON.parse(body));
+        } catch (error) {
+          reject(new Error(`registry source returned invalid JSON: ${error.message}`));
+        }
+      });
+    });
+    request.on('timeout', () => {
+      request.destroy(new Error('registry source request timed out'));
+    });
+    request.on('error', reject);
+  });
+}
+
+async function loadRegistryPayload(projectPath, source, fileSystem = fs) {
+  const normalized = normalizeText(source);
+  if (!normalized) {
+    throw new Error('registry source is required');
+  }
+  if (isHttpSource(normalized)) {
+    return fetchJsonFromHttp(normalized);
+  }
+  const absolutePath = path.isAbsolute(normalized)
+    ? normalized
+    : path.resolve(projectPath, normalized);
+  if (!await fileSystem.pathExists(absolutePath)) {
+    throw new Error(`registry source file not found: ${source}`);
+  }
+  return fileSystem.readJson(absolutePath);
+}
+
+function normalizeRegistryEntry(entry = {}, sourceName = 'registry') {
+  const title = normalizeText(entry.title || entry.name);
+  const symptom = normalizeText(entry.symptom);
+  const rootCause = normalizeText(entry.root_cause || entry.rootCause);
+  const fingerprint = createFingerprint({
+    fingerprint: normalizeText(entry.fingerprint),
+    title,
+    symptom,
+    root_cause: rootCause
+  });
+  const statusRaw = normalizeText(entry.status || 'candidate').toLowerCase();
+  const status = ERRORBOOK_STATUSES.includes(statusRaw) ? statusRaw : 'candidate';
+  const mitigation = normalizeExistingTemporaryMitigation(entry.temporary_mitigation);
+
+  return {
+    id: normalizeText(entry.id) || `registry-${fingerprint}`,
+    fingerprint,
+    title,
+    symptom,
+    root_cause: rootCause,
+    fix_actions: normalizeStringList(entry.fix_actions, entry.fixActions),
+    verification_evidence: normalizeStringList(entry.verification_evidence, entry.verificationEvidence),
+    tags: normalizeStringList(entry.tags, mitigation.enabled ? TEMPORARY_MITIGATION_TAG : []),
+    ontology_tags: normalizeOntologyTags(entry.ontology_tags),
+    status,
+    quality_score: Number.isFinite(Number(entry.quality_score)) ? Number(entry.quality_score) : scoreQuality(entry),
+    updated_at: normalizeIsoTimestamp(entry.updated_at || entry.updatedAt, 'registry.updated_at') || nowIso(),
+    source: {
+      ...entry.source,
+      registry: sourceName
+    },
+    temporary_mitigation: mitigation,
+    entry_source: 'registry'
+  };
+}
+
+function extractRegistryEntries(payload = {}, sourceName = 'registry') {
+  const rawEntries = Array.isArray(payload)
+    ? payload
+    : Array.isArray(payload.entries)
+      ? payload.entries
+      : [];
+  const normalized = [];
+  for (const item of rawEntries) {
+    if (!item || typeof item !== 'object') {
+      continue;
+    }
+    const entry = normalizeRegistryEntry(item, sourceName);
+    if (!entry.title || !entry.fingerprint) {
+      continue;
+    }
+    normalized.push(entry);
+  }
+  const deduped = new Map();
+  for (const entry of normalized) {
+    const key = entry.fingerprint;
+    const existing = deduped.get(key);
+    if (!existing) {
+      deduped.set(key, entry);
+      continue;
+    }
+    if ((Number(entry.quality_score) || 0) >= (Number(existing.quality_score) || 0)) {
+      deduped.set(key, entry);
+    }
+  }
+  return Array.from(deduped.values());
+}
+
+async function loadRegistryCache(projectPath, cachePathInput = '', fileSystem = fs) {
+  const cachePath = resolveProjectPath(projectPath, cachePathInput, DEFAULT_ERRORBOOK_REGISTRY_CACHE);
+  if (!await fileSystem.pathExists(cachePath)) {
+    return {
+      cache_path: cachePath,
+      entries: []
+    };
+  }
+  const payload = await fileSystem.readJson(cachePath).catch(() => null);
+  const entries = extractRegistryEntries(payload || {}, 'registry-cache');
+  return {
+    cache_path: cachePath,
+    entries
+  };
+}
+
+function tokenizeQueryText(query = '') {
+  return normalizeText(query)
+    .toLowerCase()
+    .split(/[^a-z0-9_]+/i)
+    .map((item) => item.trim())
+    .filter((item) => item.length >= 2);
+}
+
+function normalizeRegistryIndex(payload = {}, sourceName = '') {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return null;
+  }
+  return {
+    api_version: normalizeText(payload.api_version || payload.version || ERRORBOOK_REGISTRY_INDEX_API_VERSION),
+    source_name: sourceName || normalizeText(payload.source_name || payload.sourceName),
+    min_token_length: Number.isFinite(Number(payload.min_token_length))
+      ? Number(payload.min_token_length)
+      : 2,
+    token_to_source: payload.token_to_source && typeof payload.token_to_source === 'object'
+      ? payload.token_to_source
+      : {},
+    token_to_bucket: payload.token_to_bucket && typeof payload.token_to_bucket === 'object'
+      ? payload.token_to_bucket
+      : {},
+    buckets: payload.buckets && typeof payload.buckets === 'object'
+      ? payload.buckets
+      : {},
+    default_source: normalizeText(payload.default_source || payload.fallback_source || '')
+  };
+}
+
+function collectRegistryShardSources(indexPayload, queryTokens = [], maxShards = 8) {
+  const index = normalizeRegistryIndex(indexPayload);
+  if (!index) {
+    return [];
+  }
+  const sources = [];
+  const minTokenLength = Number.isFinite(index.min_token_length) ? index.min_token_length : 2;
+  for (const token of queryTokens) {
+    const normalizedToken = normalizeText(token).toLowerCase();
+    if (!normalizedToken || normalizedToken.length < minTokenLength) {
+      continue;
+    }
+    const direct = index.token_to_source[normalizedToken];
+    if (direct) {
+      const items = Array.isArray(direct) ? direct : [direct];
+      for (const item of items) {
+        sources.push(normalizeText(item));
+      }
+      continue;
+    }
+    const bucket = normalizeText(index.token_to_bucket[normalizedToken]);
+    if (!bucket) {
+      continue;
+    }
+    const bucketSource = normalizeText(index.buckets[bucket] || index.buckets[normalizedToken]);
+    if (bucketSource) {
+      sources.push(bucketSource);
+    }
+  }
+
+  const deduped = Array.from(new Set(sources.filter(Boolean)));
+  if (deduped.length > 0) {
+    return Number.isFinite(Number(maxShards)) && Number(maxShards) > 0
+      ? deduped.slice(0, Number(maxShards))
+      : deduped;
+  }
+  if (index.default_source) {
+    return [index.default_source];
+  }
+  return [];
+}
+
+async function searchRegistryRemote(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const source = normalizeRegistrySource(options.source || {});
+  const query = normalizeText(options.query);
+  const queryTokens = Array.isArray(options.queryTokens) ? options.queryTokens : tokenizeQueryText(query);
+  const requestedStatus = options.requestedStatus || null;
+  const maxShards = Number.isFinite(Number(options.maxShards)) ? Number(options.maxShards) : 8;
+  const allowRemoteFullscan = options.allowRemoteFullscan === true;
+
+  if (!source.source) {
+    return {
+      source_name: source.name || 'registry',
+      shard_sources: [],
+      matched_count: 0,
+      candidates: [],
+      warnings: ['registry source is empty']
+    };
+  }
+
+  const warnings = [];
+  let shardSources = [];
+  if (source.index_url) {
+    try {
+      const indexPayload = await loadRegistryPayload(projectPath, source.index_url, fileSystem);
+      shardSources = collectRegistryShardSources(indexPayload, queryTokens, maxShards);
+    } catch (error) {
+      warnings.push(`failed to load registry index (${source.index_url}): ${error.message}`);
+    }
+  }
+
+  if (shardSources.length === 0) {
+    if (allowRemoteFullscan) {
+      shardSources = [source.source];
+      warnings.push('remote index unavailable; fallback to full-source scan');
+    } else {
+      warnings.push('remote index unavailable and full-source scan disabled');
+      return {
+        source_name: source.name || 'registry',
+        shard_sources: [],
+        matched_count: 0,
+        candidates: [],
+        warnings
+      };
+    }
+  }
+
+  const candidates = [];
+  for (const shardSource of shardSources) {
+    try {
+      const payload = await loadRegistryPayload(projectPath, shardSource, fileSystem);
+      const entries = extractRegistryEntries(payload, source.name || 'registry');
+      for (const entry of entries) {
+        if (requestedStatus && normalizeStatus(entry.status, 'candidate') !== requestedStatus) {
+          continue;
+        }
+        const matchScore = scoreSearchMatch(entry, queryTokens);
+        if (matchScore <= 0) {
+          continue;
+        }
+        candidates.push({
+          id: entry.id,
+          entry_source: 'registry-remote',
+          registry_source: source.name || 'registry',
+          status: entry.status,
+          quality_score: entry.quality_score,
+          title: entry.title,
+          fingerprint: entry.fingerprint,
+          tags: normalizeStringList(entry.tags),
+          ontology_tags: normalizeOntologyTags(entry.ontology_tags),
+          match_score: matchScore,
+          updated_at: entry.updated_at
+        });
+      }
+    } catch (error) {
+      warnings.push(`failed to load registry shard (${shardSource}): ${error.message}`);
+    }
+  }
+
+  const deduped = new Map();
+  for (const item of candidates) {
+    const key = normalizeText(item.fingerprint || item.id);
+    const existing = deduped.get(key);
+    if (!existing || Number(item.match_score || 0) >= Number(existing.match_score || 0)) {
+      deduped.set(key, item);
+    }
+  }
+
+  return {
+    source_name: source.name || 'registry',
+    shard_sources: shardSources,
+    matched_count: deduped.size,
+    candidates: Array.from(deduped.values()),
+    warnings
+  };
+}
+
 function printRecordSummary(result) {
   const action = result.created ? 'Recorded new entry' : 'Updated duplicate fingerprint';
   console.log(chalk.green(`✓ ${action}`));
@@ -881,6 +1330,9 @@ async function runErrorbookRecordCommand(options = {}, dependencies = {}) {
       throw new Error(`errorbook index references missing entry: ${existingSummary.id}`);
     }
     entry = mergeEntry(existingEntry, normalized);
+    enforceDebugEvidenceAfterRepeatedFailures(entry, {
+      attemptCount: Number(entry.occurrences || 0)
+    });
     deduplicated = true;
   } else {
     const temporaryMitigation = normalizeExistingTemporaryMitigation(normalized.temporary_mitigation);
@@ -945,6 +1397,344 @@ async function runErrorbookRecordCommand(options = {}, dependencies = {}) {
   return result;
 }
 
+async function runErrorbookExportCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const paths = resolveErrorbookPaths(projectPath);
+  const registryPaths = resolveErrorbookRegistryPaths(projectPath, {
+    exportPath: options.out
+  });
+  const index = await readErrorbookIndex(paths, fileSystem);
+
+  const statuses = normalizeStatusList(options.statuses || options.status || 'promoted', ['promoted']);
+  const minQuality = Number.isFinite(Number(options.minQuality))
+    ? Number(options.minQuality)
+    : 75;
+  const limit = Number.isFinite(Number(options.limit)) && Number(options.limit) > 0
+    ? Number(options.limit)
+    : 0;
+
+  const selected = [];
+  for (const summary of index.entries) {
+    const entry = await readErrorbookEntry(paths, summary.id, fileSystem);
+    if (!entry) {
+      continue;
+    }
+    const status = normalizeStatus(entry.status, 'candidate');
+    if (!statuses.includes(status)) {
+      continue;
+    }
+    if (Number(entry.quality_score || 0) < minQuality) {
+      continue;
+    }
+    selected.push({
+      id: entry.id,
+      fingerprint: entry.fingerprint,
+      title: entry.title,
+      symptom: entry.symptom,
+      root_cause: entry.root_cause,
+      fix_actions: normalizeStringList(entry.fix_actions),
+      verification_evidence: normalizeStringList(entry.verification_evidence),
+      tags: normalizeStringList(entry.tags),
+      ontology_tags: normalizeOntologyTags(entry.ontology_tags),
+      status,
+      quality_score: Number(entry.quality_score || 0),
+      updated_at: entry.updated_at,
+      source: entry.source || {},
+      temporary_mitigation: normalizeExistingTemporaryMitigation(entry.temporary_mitigation)
+    });
+  }
+
+  selected.sort((left, right) => {
+    const qualityDiff = Number(right.quality_score || 0) - Number(left.quality_score || 0);
+    if (qualityDiff !== 0) {
+      return qualityDiff;
+    }
+    return `${right.updated_at || ''}`.localeCompare(`${left.updated_at || ''}`);
+  });
+
+  const entries = limit > 0 ? selected.slice(0, limit) : selected;
+  const payload = {
+    api_version: ERRORBOOK_REGISTRY_API_VERSION,
+    generated_at: nowIso(),
+    source: {
+      project: path.basename(projectPath),
+      statuses,
+      min_quality: minQuality
+    },
+    total_entries: entries.length,
+    entries
+  };
+
+  await fileSystem.ensureDir(path.dirname(registryPaths.exportFile));
+  await fileSystem.writeJson(registryPaths.exportFile, payload, { spaces: 2 });
+
+  const result = {
+    mode: 'errorbook-export',
+    out_file: registryPaths.exportFile,
+    statuses,
+    min_quality: minQuality,
+    total_entries: entries.length
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (!options.silent) {
+    console.log(chalk.green('✓ Exported curated errorbook entries'));
+    console.log(chalk.gray(`  out: ${registryPaths.exportFile}`));
+    console.log(chalk.gray(`  total: ${entries.length}`));
+    console.log(chalk.gray(`  statuses: ${statuses.join(', ')}`));
+  }
+
+  return result;
+}
+
+async function runErrorbookSyncRegistryCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const registryPaths = resolveErrorbookRegistryPaths(projectPath, {
+    configPath: options.config,
+    cachePath: options.cache
+  });
+
+  const config = await readErrorbookRegistryConfig(registryPaths, fileSystem);
+  const sourceOption = normalizeText(options.source);
+  const configuredSource = config.sources.find((item) => item.enabled && item.source);
+  const source = sourceOption || (configuredSource ? configuredSource.source : '');
+  if (!source) {
+    throw new Error('registry source is required (use --source or configure .sce/config/errorbook-registry.json)');
+  }
+  const sourceName = normalizeText(options.sourceName)
+    || (configuredSource ? configuredSource.name : '')
+    || 'registry';
+
+  const payload = await loadRegistryPayload(projectPath, source, fileSystem);
+  const entries = extractRegistryEntries(payload, sourceName);
+  const cachePath = resolveProjectPath(projectPath, options.cache, config.cache_file || DEFAULT_ERRORBOOK_REGISTRY_CACHE);
+  const cachePayload = {
+    api_version: ERRORBOOK_REGISTRY_CACHE_API_VERSION,
+    synced_at: nowIso(),
+    source: {
+      name: sourceName,
+      uri: source
+    },
+    total_entries: entries.length,
+    entries
+  };
+
+  await fileSystem.ensureDir(path.dirname(cachePath));
+  await fileSystem.writeJson(cachePath, cachePayload, { spaces: 2 });
+
+  const result = {
+    mode: 'errorbook-sync-registry',
+    source,
+    source_name: sourceName,
+    cache_file: cachePath,
+    total_entries: entries.length
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (!options.silent) {
+    console.log(chalk.green('✓ Synced external errorbook registry'));
+    console.log(chalk.gray(`  source: ${source}`));
+    console.log(chalk.gray(`  cache: ${cachePath}`));
+    console.log(chalk.gray(`  entries: ${entries.length}`));
+  }
+
+  return result;
+}
+
+async function runErrorbookRegistryHealthCommand(options = {}, dependencies = {}) {
+  const projectPath = dependencies.projectPath || process.cwd();
+  const fileSystem = dependencies.fileSystem || fs;
+  const registryPaths = resolveErrorbookRegistryPaths(projectPath, {
+    configPath: options.config,
+    cachePath: options.cache
+  });
+
+  const warnings = [];
+  const errors = [];
+  const overrideSource = normalizeText(options.source);
+  const overrideIndex = normalizeText(options.index || options.registryIndex);
+  const overrideSourceName = normalizeText(options.sourceName || options.registrySourceName) || 'override';
+
+  const configExists = await fileSystem.pathExists(registryPaths.configFile);
+  if (configExists) {
+    try {
+      const rawConfig = await fileSystem.readJson(registryPaths.configFile);
+      if (!rawConfig || typeof rawConfig !== 'object' || Array.isArray(rawConfig)) {
+        errors.push(`registry config must be a JSON object: ${registryPaths.configFile}`);
+      }
+    } catch (error) {
+      errors.push(`failed to parse registry config (${registryPaths.configFile}): ${error.message}`);
+    }
+  } else if (!overrideSource) {
+    errors.push(`registry config file not found: ${registryPaths.configFile}`);
+  }
+
+  const config = await readErrorbookRegistryConfig(registryPaths, fileSystem);
+  let registryEnabled = normalizeBoolean(config.enabled, true);
+  let sources = Array.isArray(config.sources) ? config.sources : [];
+
+  if (overrideSource) {
+    registryEnabled = true;
+    sources = [normalizeRegistrySource({
+      name: overrideSourceName,
+      source: overrideSource,
+      index_url: overrideIndex
+    })];
+  } else if (overrideIndex && sources.length > 0) {
+    sources = sources.map((source, sourceIndex) => (
+      sourceIndex === 0 ? { ...source, index_url: overrideIndex } : source
+    ));
+  }
+
+  if (!registryEnabled) {
+    warnings.push('registry config is disabled');
+  }
+  if (registryEnabled && sources.length === 0) {
+    errors.push('registry enabled but no sources configured');
+  }
+
+  const maxShards = Number.isFinite(Number(options.maxShards)) && Number(options.maxShards) > 0
+    ? Number(options.maxShards)
+    : 8;
+  const shardSample = Number.isFinite(Number(options.shardSample)) && Number(options.shardSample) > 0
+    ? Number(options.shardSample)
+    : 2;
+
+  const sourceResults = [];
+  for (const source of sources) {
+    const sourceName = normalizeText(source.name) || 'registry';
+    const sourceReport = {
+      source_name: sourceName,
+      source: normalizeText(source.source),
+      index_url: normalizeText(source.index_url),
+      source_ok: false,
+      index_ok: null,
+      shard_sources_checked: 0,
+      source_entries: 0,
+      shard_entries: 0,
+      warnings: [],
+      errors: []
+    };
+
+    if (!sourceReport.source) {
+      sourceReport.errors.push('source is empty');
+    } else {
+      try {
+        const payload = await loadRegistryPayload(projectPath, sourceReport.source, fileSystem);
+        const entries = extractRegistryEntries(payload, sourceName);
+        sourceReport.source_ok = true;
+        sourceReport.source_entries = entries.length;
+        if (entries.length === 0) {
+          sourceReport.warnings.push('source returned no valid entries');
+        }
+      } catch (error) {
+        sourceReport.errors.push(`failed to load source (${sourceReport.source}): ${error.message}`);
+      }
+    }
+
+    if (!sourceReport.index_url) {
+      sourceReport.warnings.push('index_url not configured; remote indexed lookup health is partially validated');
+    } else {
+      try {
+        const indexPayload = await loadRegistryPayload(projectPath, sourceReport.index_url, fileSystem);
+        const index = normalizeRegistryIndex(indexPayload, sourceName);
+        if (!index) {
+          sourceReport.errors.push(`invalid index payload: ${sourceReport.index_url}`);
+        } else {
+          sourceReport.index_ok = true;
+          const tokenToBucket = index.token_to_bucket || {};
+          const unresolved = [];
+          for (const [token, bucketRaw] of Object.entries(tokenToBucket)) {
+            const bucket = normalizeText(bucketRaw);
+            if (!bucket) {
+              continue;
+            }
+            const bucketSource = normalizeText(index.buckets[bucket] || index.buckets[token]);
+            if (!bucketSource) {
+              unresolved.push(`${token}->${bucket}`);
+            }
+          }
+          if (unresolved.length > 0) {
+            sourceReport.errors.push(`unresolved index bucket mappings: ${unresolved.slice(0, 10).join(', ')}`);
+          }
+
+          const sampleTokens = Object.keys(tokenToBucket).slice(0, 64);
+          const shardSources = collectRegistryShardSources(index, sampleTokens, maxShards);
+          sourceReport.shard_sources_checked = shardSources.length;
+          if (shardSources.length === 0) {
+            sourceReport.warnings.push('index resolved zero shard sources');
+          }
+
+          for (const shardSource of shardSources.slice(0, shardSample)) {
+            try {
+              const shardPayload = await loadRegistryPayload(projectPath, shardSource, fileSystem);
+              const shardEntries = extractRegistryEntries(shardPayload, `${sourceName}-shard`);
+              sourceReport.shard_entries += shardEntries.length;
+            } catch (error) {
+              sourceReport.errors.push(`failed to load shard (${shardSource}): ${error.message}`);
+            }
+          }
+        }
+      } catch (error) {
+        sourceReport.index_ok = false;
+        sourceReport.errors.push(`failed to load index (${sourceReport.index_url}): ${error.message}`);
+      }
+    }
+
+    for (const message of sourceReport.warnings) {
+      warnings.push(`[${sourceName}] ${message}`);
+    }
+    for (const message of sourceReport.errors) {
+      errors.push(`[${sourceName}] ${message}`);
+    }
+    sourceResults.push(sourceReport);
+  }
+
+  const result = {
+    mode: 'errorbook-health-registry',
+    checked_at: nowIso(),
+    passed: errors.length === 0,
+    warning_count: warnings.length,
+    error_count: errors.length,
+    paths: {
+      config_file: registryPaths.configFile,
+      cache_file: registryPaths.cacheFile
+    },
+    config: {
+      exists: configExists,
+      enabled: registryEnabled,
+      search_mode: config.search_mode || 'cache',
+      source_count: sources.length
+    },
+    sources: sourceResults,
+    warnings,
+    errors
+  };
+
+  if (options.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else if (!options.silent) {
+    if (result.passed) {
+      console.log(chalk.green('✓ Errorbook registry health check passed'));
+    } else {
+      console.log(chalk.red('✗ Errorbook registry health check failed'));
+    }
+    console.log(chalk.gray(`  sources: ${result.config.source_count}`));
+    console.log(chalk.gray(`  warnings: ${result.warning_count}`));
+    console.log(chalk.gray(`  errors: ${result.error_count}`));
+  }
+
+  if (options.failOnAlert && !result.passed) {
+    throw new Error(`errorbook registry health failed: ${result.error_count} error(s)`);
+  }
+
+  return result;
+}
+
 async function runErrorbookListCommand(options = {}, dependencies = {}) {
   const projectPath = dependencies.projectPath || process.cwd();
   const fileSystem = dependencies.fileSystem || fs;
@@ -1071,9 +1861,15 @@ async function runErrorbookFindCommand(options = {}, dependencies = {}) {
   const limit = Number.isFinite(Number(options.limit)) && Number(options.limit) > 0
     ? Number(options.limit)
     : 10;
-  const tokens = query.toLowerCase().split(/[\s,;|]+/).map((item) => item.trim()).filter(Boolean);
+  const tokens = tokenizeQueryText(query);
+  const includeRegistry = options.includeRegistry === true;
 
   const candidates = [];
+  let localMatched = 0;
+  let registryMatched = 0;
+  let registryCacheMatched = 0;
+  let registryRemoteMatched = 0;
+  const registryWarnings = [];
   for (const summary of index.entries) {
     if (requestedStatus && summary.status !== requestedStatus) {
       continue;
@@ -1086,8 +1882,10 @@ async function runErrorbookFindCommand(options = {}, dependencies = {}) {
     if (matchScore <= 0) {
       continue;
     }
+    localMatched += 1;
     candidates.push({
       id: entry.id,
+      entry_source: 'local',
       status: entry.status,
       quality_score: entry.quality_score,
       title: entry.title,
@@ -1099,7 +1897,96 @@ async function runErrorbookFindCommand(options = {}, dependencies = {}) {
     });
   }
 
-  candidates.sort((left, right) => {
+  if (includeRegistry) {
+    const configPaths = resolveErrorbookRegistryPaths(projectPath, {
+      configPath: options.config,
+      cachePath: options.registryCache
+    });
+    const registryConfig = await readErrorbookRegistryConfig(configPaths, fileSystem);
+    const registryMode = normalizeRegistryMode(options.registryMode, registryConfig.search_mode || 'cache');
+    const useCache = registryMode === 'cache' || registryMode === 'hybrid';
+    const useRemote = registryMode === 'remote' || registryMode === 'hybrid';
+
+    if (useRemote) {
+      const configuredSources = Array.isArray(registryConfig.sources)
+        ? registryConfig.sources.filter((item) => item.enabled && item.source)
+        : [];
+      const overrideSource = normalizeText(options.registrySource);
+      const remoteSources = overrideSource
+        ? [normalizeRegistrySource({
+          name: normalizeText(options.registrySourceName) || 'override',
+          source: overrideSource,
+          index_url: normalizeText(options.registryIndex)
+        })]
+        : configuredSources;
+
+      for (const source of remoteSources) {
+        const remoteResult = await searchRegistryRemote({
+          source,
+          query,
+          queryTokens: tokens,
+          requestedStatus,
+          maxShards: options.registryMaxShards,
+          allowRemoteFullscan: options.allowRemoteFullscan === true
+        }, {
+          projectPath,
+          fileSystem
+        });
+        registryRemoteMatched += Number(remoteResult.matched_count || 0);
+        registryMatched += Number(remoteResult.matched_count || 0);
+        if (Array.isArray(remoteResult.warnings)) {
+          registryWarnings.push(...remoteResult.warnings);
+        }
+        if (Array.isArray(remoteResult.candidates)) {
+          candidates.push(...remoteResult.candidates);
+        }
+      }
+    }
+
+    if (useCache) {
+      const cachePath = resolveProjectPath(
+        projectPath,
+        options.registryCache,
+        registryConfig.cache_file || DEFAULT_ERRORBOOK_REGISTRY_CACHE
+      );
+      const registryCache = await loadRegistryCache(projectPath, cachePath, fileSystem);
+      for (const entry of registryCache.entries) {
+        if (requestedStatus && normalizeStatus(entry.status, 'candidate') !== requestedStatus) {
+          continue;
+        }
+        const matchScore = scoreSearchMatch(entry, tokens);
+        if (matchScore <= 0) {
+          continue;
+        }
+        registryMatched += 1;
+        registryCacheMatched += 1;
+        candidates.push({
+          id: entry.id,
+          entry_source: 'registry-cache',
+          status: entry.status,
+          quality_score: entry.quality_score,
+          title: entry.title,
+          fingerprint: entry.fingerprint,
+          tags: normalizeStringList(entry.tags),
+          ontology_tags: normalizeOntologyTags(entry.ontology_tags),
+          match_score: matchScore,
+          updated_at: entry.updated_at
+        });
+      }
+    }
+  }
+
+  const dedupedCandidates = new Map();
+  for (const item of candidates) {
+    const key = normalizeText(item.fingerprint || item.id);
+    const existing = dedupedCandidates.get(key);
+    if (!existing || Number(item.match_score || 0) >= Number(existing.match_score || 0)) {
+      dedupedCandidates.set(key, item);
+    }
+  }
+  const sortedCandidates = Array.from(dedupedCandidates.values());
+
+  sortedCandidates.sort((left, right) => {
     const scoreDiff = Number(right.match_score) - Number(left.match_score);
     if (scoreDiff !== 0) {
       return scoreDiff;
@@ -1110,8 +1997,16 @@ async function runErrorbookFindCommand(options = {}, dependencies = {}) {
   const result = {
     mode: 'errorbook-find',
     query,
-    total_results: candidates.length,
-    entries: candidates.slice(0, limit)
+    include_registry: includeRegistry,
+    source_breakdown: {
+      local_results: localMatched,
+      registry_results: registryMatched,
+      registry_cache_results: registryCacheMatched,
+      registry_remote_results: registryRemoteMatched
+    },
+    warnings: normalizeStringList(registryWarnings),
+    total_results: sortedCandidates.length,
+    entries: sortedCandidates.slice(0, limit)
   };
 
   if (options.json) {
@@ -1439,6 +2334,15 @@ function registerErrorbookCommands(program) {
     .requiredOption('--query <text>', 'Search query')
     .option('--status <status>', `Filter by status (${ERRORBOOK_STATUSES.join(', ')})`)
     .option('--limit <n>', 'Maximum entries returned', parseInt, 10)
+    .option('--include-registry', 'Include external registry entries in search')
+    .option('--registry-mode <mode>', 'Registry lookup mode (cache|remote|hybrid)')
+    .option('--registry-source <url-or-path>', 'Override registry source (for remote mode)')
+    .option('--registry-source-name <name>', 'Override registry source label')
+    .option('--registry-index <url-or-path>', 'Override registry index source (for remote mode)')
+    .option('--registry-max-shards <n>', 'Max remote shards to fetch per query', parseInt, 8)
+    .option('--allow-remote-fullscan', 'Allow remote full-source fallback when index is unavailable')
+    .option('--registry-cache <path>', `Registry cache path (default: ${DEFAULT_ERRORBOOK_REGISTRY_CACHE})`)
+    .option('--config <path>', `Registry config path (default: ${DEFAULT_ERRORBOOK_REGISTRY_CONFIG})`)
     .option('--json', 'Emit machine-readable JSON')
     .action(async (options) => {
       try {
@@ -1448,6 +2352,58 @@ function registerErrorbookCommands(program) {
       }
     });
 
+  errorbook
+    .command('export')
+    .description('Export curated local entries for external registry publication')
+    .option('--status <csv>', 'Statuses to include (csv, default: promoted)', 'promoted')
+    .option('--min-quality <n>', 'Minimum quality score (default: 75)', parseInt)
+    .option('--limit <n>', 'Maximum entries exported', parseInt)
+    .option('--out <path>', `Output file (default: ${DEFAULT_ERRORBOOK_REGISTRY_EXPORT})`)
+    .option('--json', 'Emit machine-readable JSON')
+    .action(async (options) => {
+      try {
+        await runErrorbookExportCommand(options);
+      } catch (error) {
+        emitCommandError(error, options.json);
+      }
+    });
+
+  errorbook
+    .command('sync-registry')
+    .description('Sync external errorbook registry to local cache')
+    .option('--source <url-or-path>', 'Registry source JSON (https://... or local file)')
+    .option('--source-name <name>', 'Registry source name label')
+    .option('--cache <path>', `Registry cache output path (default: ${DEFAULT_ERRORBOOK_REGISTRY_CACHE})`)
+    .option('--config <path>', `Registry config path (default: ${DEFAULT_ERRORBOOK_REGISTRY_CONFIG})`)
+    .option('--json', 'Emit machine-readable JSON')
+    .action(async (options) => {
+      try {
+        await runErrorbookSyncRegistryCommand(options);
+      } catch (error) {
+        emitCommandError(error, options.json);
+      }
+    });
+
+  errorbook
+    .command('health-registry')
+    .description('Validate external registry config/source/index health')
+    .option('--config <path>', `Registry config path (default: ${DEFAULT_ERRORBOOK_REGISTRY_CONFIG})`)
+    .option('--cache <path>', `Registry cache path (default: ${DEFAULT_ERRORBOOK_REGISTRY_CACHE})`)
+    .option('--source <url-or-path>', 'Override registry source JSON (https://... or local file)')
+    .option('--source-name <name>', 'Override source name label')
+    .option('--index <url-or-path>', 'Override registry index source (https://... or local file)')
+    .option('--max-shards <n>', 'Max index-resolved shards to validate', parseInt, 8)
+    .option('--shard-sample <n>', 'Shard sample count to fetch and validate', parseInt, 2)
+    .option('--fail-on-alert', 'Exit with error when health check finds errors')
+    .option('--json', 'Emit machine-readable JSON')
+    .action(async (options) => {
+      try {
+        await runErrorbookRegistryHealthCommand(options);
+      } catch (error) {
+        emitCommandError(error, options.json);
+      }
+    });
+
   errorbook
     .command('promote <id>')
     .description('Promote entry after strict quality gate')
@@ -1508,15 +2464,23 @@ module.exports = {
   ERRORBOOK_ONTOLOGY_TAGS,
   ERRORBOOK_RISK_LEVELS,
   TEMPORARY_MITIGATION_TAG,
+  DEFAULT_ERRORBOOK_REGISTRY_CONFIG,
+  DEFAULT_ERRORBOOK_REGISTRY_CACHE,
+  DEFAULT_ERRORBOOK_REGISTRY_EXPORT,
   HIGH_RISK_SIGNAL_TAGS,
+  DEBUG_EVIDENCE_TAGS,
   DEFAULT_PROMOTE_MIN_QUALITY,
   resolveErrorbookPaths,
+  resolveErrorbookRegistryPaths,
   normalizeOntologyTags,
   normalizeRecordPayload,
   scoreQuality,
   evaluateEntryRisk,
   evaluateErrorbookReleaseGate,
   runErrorbookRecordCommand,
+  runErrorbookExportCommand,
+  runErrorbookSyncRegistryCommand,
+  runErrorbookRegistryHealthCommand,
   runErrorbookListCommand,
   runErrorbookShowCommand,
   runErrorbookFindCommand,