@fiodos/cli 0.1.0

package/src/wireHandlers.js

@@ -0,0 +1,1789 @@
+/**
+ * wireHandlers — consent-based, security-aware auto-wiring of action handlers.
+ *
+ * Runs at the very end of a WEB analysis, AFTER the orb wiring (wireWeb) and its
+ * confirmation. The orb mounts, but the agent cannot DO anything until each
+ * action detected in the manifest is connected to the real function in the app
+ * that performs it. This module prepares that "bridge" and asks for a SECOND,
+ * separate, informed confirmation before writing any code.
+ *
+ * Contract:
+ *   1. PREPARE — for every action in the (just produced) manifest, figure out
+ *      whether we can connect it to a real app function WITH CONFIDENCE:
+ *        · exported standalone function whose params we can map by name, or
+ *        · a zustand store method (STORE.getState().method) we can map by name.
+ *      Anything else (class methods, React context/hooks, local component
+ *      functions, ambiguous params, unknown signatures) is NEVER guessed: it is
+ *      marked "manual" with a reason. A wrong wiring is worse than none.
+ *   2. DOCUMENT — write a human-readable doc into the project's Fiodos folder
+ *      explaining exactly what will be wired, which files are created, why it is
+ *      needed, and the security notes (which actions stay behind confirmation).
+ *   3. CONFIRM — print the doc path and ask "[yes/no]" in the terminal. On a
+ *      non-TTY (CI) or "no", nothing in the developer's code is written.
+ *   4. APPLY (yes only) — write the generated registry file idempotently (it is
+ *      fully regenerated each run and clearly marked GENERATED). The developer's
+ *      existing files are never edited; the one-line `registries=` wiring is
+ *      printed so the mount step matches how the orb itself is wired.
+ *
+ * SECURITY (non-negotiable):
+ *   · A generated handler only CALLS your function. It NEVER decides whether a
+ *     sensitive action runs: the Fiodos engine enforces the manifest's
+ *     requireConfirmation / voiceConfirmation BEFORE any handler is invoked
+ *     (see @fiodos/web-core decideAction). So auto-wiring cannot bypass a
+ *     confirmation, by construction.
+ *   · No secrets are read, embedded or exposed; only function names + the
+ *     params the manifest already declares are referenced.
+ *   · Low confidence → "manual", with the reason in the doc. Never guess.
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+const { probeEffect, compileRegressed } = require('./verifyWire');
+
+const DOC_BASENAME = 'FYODOS_HANDLERS.md';
+const REGISTRY_BASENAME = 'handlers.generated';
+const BRIDGE_BASENAME = 'bridge';
+const REGISTRY_EXPORT = 'fyodosGeneratedRegistries';
+const GENERATED_MARKER = 'GENERATED by Fiodos — handler wiring';
+// Markers wrapping every line Fiodos inserts INTO the user's own files, so the
+// edits are idempotent (re-runs strip+rewrite) and trivially reversible.
+const EDIT_START = '// FYODOS:BRIDGE:START (auto-generado por Fiodos — seguro de eliminar)';
+const EDIT_END = '// FYODOS:BRIDGE:END';
+
+function esc(name) {
+  return String(name).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function normRel(p) {
+  return String(p || '').replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+function readFileSafe(appRoot, fileRel) {
+  const abs = path.join(appRoot, normRel(fileRel));
+  if (!fs.existsSync(abs)) return null;
+  try {
+    return fs.readFileSync(abs, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+/** Count non-overlapping occurrences of a literal substring. */
+function countOccurrences(haystack, needle) {
+  if (!needle) return 0;
+  let count = 0;
+  let idx = haystack.indexOf(needle);
+  while (idx !== -1) {
+    count += 1;
+    idx = haystack.indexOf(needle, idx + needle.length);
+  }
+  return count;
+}
+
+// ── Mechanical verification (the safety net for AI-proposed wiring) ─────────────
+
+/** True if `symbol` appears as a standalone identifier somewhere in the file. */
+function fileHasSymbol(appRoot, fileRel, symbol) {
+  if (!fileRel || !symbol) return false;
+  const abs = path.join(appRoot, normRel(fileRel));
+  if (!fs.existsSync(abs)) return false;
+  let content;
+  try {
+    content = fs.readFileSync(abs, 'utf8');
+  } catch {
+    return false;
+  }
+  return new RegExp(`(^|[^\\w$])${esc(symbol)}([^\\w$]|$)`).test(content);
+}
+
+/**
+ * Identifiers a generated `call` expression is allowed to reference for free
+ * (i.e. without an explicit import). Anything else must be an imported name, or
+ * the wiring is rejected — we never write code that calls an unknown symbol.
+ */
+// JS syntax keywords are not symbols; they must never count as "unknown ids".
+// Includes TS-only keywords/built-in type names so a cast like `x as any` or a
+// type annotation never looks like a call to a hallucinated identifier.
+const JS_KEYWORDS = new Set([
+  'const', 'let', 'var', 'if', 'else', 'for', 'while', 'do', 'switch', 'case',
+  'break', 'continue', 'return', 'function', 'class', 'extends', 'new', 'typeof',
+  'instanceof', 'in', 'of', 'void', 'delete', 'await', 'async', 'yield', 'throw',
+  'try', 'catch', 'finally', 'this', 'super', 'default', 'export', 'import',
+  'from', 'as', 'true', 'false', 'null', 'undefined',
+  // TypeScript type keywords / built-in type names (appear in casts/annotations).
+  'any', 'unknown', 'never', 'string', 'number', 'boolean', 'object', 'symbol',
+  'bigint', 'readonly', 'keyof', 'infer', 'satisfies', 'is',
+]);
+
+const SAFE_GLOBALS = new Set([
+  'params', 'await', 'async', 'new', 'typeof', 'void', 'delete', 'in', 'of',
+  'instanceof', 'return', 'true', 'false', 'null', 'undefined', 'this',
+  'crypto', 'Date', 'JSON', 'Math', 'Number', 'String', 'Boolean', 'Object',
+  'Array', 'Promise', 'console', 'parseInt', 'parseFloat', 'isNaN', 'isFinite',
+  'RegExp', 'Map', 'Set', 'Symbol', 'BigInt', 'structuredClone', 'globalThis',
+]);
+
+function stripLiterals(src) {
+  return String(src || '')
+    .replace(/`(?:\\.|[^`\\])*`/g, '``')
+    .replace(/'(?:\\.|[^'\\])*'/g, "''")
+    .replace(/"(?:\\.|[^"\\])*"/g, '""');
+}
+
+/**
+ * Names BOUND locally inside the expression (so they are NOT external symbols
+ * that must be imported): const/let/var declarations (incl. destructuring),
+ * function/arrow parameters and catch bindings. Heuristic, used only to avoid
+ * false rejections in the safety check.
+ */
+function declaredLocals(expr) {
+  const out = new Set();
+  const src = stripLiterals(expr);
+  const addNames = (binding) => {
+    const ids = String(binding || '').match(/[A-Za-z_$][\w$]*/g) || [];
+    for (const id of ids) out.add(id);
+  };
+  // const/let/var <binding> =
+  let m;
+  const declRe = /\b(?:const|let|var)\s+(\{[^}]*\}|\[[^\]]*\]|[A-Za-z_$][\w$]*)/g;
+  while ((m = declRe.exec(src))) addNames(m[1]);
+  // arrow params:  (a, b) =>   and   bareName =>
+  const arrowParenRe = /\(([^()]*)\)\s*=>/g;
+  while ((m = arrowParenRe.exec(src))) addNames(m[1]);
+  const arrowBareRe = /(?:^|[^.\w$])([A-Za-z_$][\w$]*)\s*=>/g;
+  while ((m = arrowBareRe.exec(src))) out.add(m[1]);
+  // function (a, b) {   and   catch (e) {
+  const fnRe = /\bfunction\b[^(]*\(([^)]*)\)/g;
+  while ((m = fnRe.exec(src))) addNames(m[1]);
+  const catchRe = /\bcatch\s*\(([^)]*)\)/g;
+  while ((m = catchRe.exec(src))) addNames(m[1]);
+  return out;
+}
+
+/**
+ * Collect the "head" identifiers a JS expression reads from the outer scope:
+ * skips property accesses (after `.`), object-literal keys (before `:`) and
+ * string/template literal contents. Heuristic, but it only feeds a SAFETY check
+ * — anything we cannot account for makes the wiring fail closed (→ review).
+ */
+function freeIdentifiers(expr) {
+  const out = new Set();
+  const stripped = stripLiterals(expr);
+  const re = /(\.)?\b([A-Za-z_$][\w$]*)\b(\s*:)?/g;
+  let m;
+  while ((m = re.exec(stripped))) {
+    const isMember = Boolean(m[1]);
+    const isObjectKey = Boolean(m[3]);
+    if (isMember || isObjectKey) continue;
+    out.add(m[2]);
+  }
+  return out;
+}
+
+/**
+ * Detect the "detached instance" anti-pattern: the call constructs an object
+ * with `new X()`, binds it to a local, then uses that local as the receiver of
+ * a method call (e.g. `const svc = new FooService(); svc.mutate()`). For DI
+ * singletons (Angular @Injectable services, etc.) this creates a NEW instance
+ * disconnected from the one the UI renders, so the action would never be
+ * observable. We reject it rather than wire something that silently does
+ * nothing. `new X(...)` used purely as a value/argument is left alone.
+ */
+function detachedInstanceReceiver(expr) {
+  const src = stripLiterals(expr);
+  const re = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*new\s+([A-Za-z_$][\w$]*)/g;
+  let m;
+  while ((m = re.exec(src))) {
+    const local = m[1];
+    if (new RegExp(`\\b${esc(local)}\\s*\\.`).test(src)) return m[2];
+  }
+  return null;
+}
+
+// ── Signature parsing ─────────────────────────────────────────────────────────
+
+/**
+ * Split a raw parameter list into structured params, honouring nesting and
+ * default values. A destructured/rest param has name=null and safe=false: it
+ * can only be left unmapped if it is optional.
+ */
+function parseParamList(raw) {
+  const s = String(raw || '').trim();
+  if (!s) return [];
+  const parts = [];
+  let depth = 0;
+  let cur = '';
+  for (const ch of s) {
+    if ('([{'.includes(ch)) depth += 1;
+    else if (')]}'.includes(ch)) depth -= 1;
+    if (ch === ',' && depth === 0) {
+      parts.push(cur);
+      cur = '';
+    } else {
+      cur += ch;
+    }
+  }
+  if (cur.trim()) parts.push(cur);
+  return parts.map((p) => {
+    const t = p.trim();
+    const optional = /[?=]/.test(t) || t.startsWith('...');
+    if (t.startsWith('{') || t.startsWith('[') || t.startsWith('...')) {
+      return { name: null, optional, raw: t, safe: false };
+    }
+    const idm = t.match(/^([A-Za-z_$][\w$]*)/);
+    return { name: idm ? idm[1] : null, optional, raw: t, safe: Boolean(idm) };
+  });
+}
+
+/** Exported standalone function/const. Returns { params, isDefault } or null. */
+function findExportedFunction(content, name) {
+  const n = esc(name);
+  const def = content.match(new RegExp(`export\\s+default\\s+(?:async\\s+)?function\\s+${n}\\s*\\(([^)]*)\\)`));
+  if (def) return { params: parseParamList(def[1]), isDefault: true };
+
+  const patterns = [
+    new RegExp(`export\\s+(?:async\\s+)?function\\s+${n}\\s*\\(([^)]*)\\)`),
+    new RegExp(`export\\s+const\\s+${n}\\s*=\\s*(?:async\\s*)?\\(([^)]*)\\)\\s*=>`),
+    new RegExp(`export\\s+const\\s+${n}\\s*=\\s*(?:async\\s+)?function\\s*[A-Za-z0-9_$]*\\s*\\(([^)]*)\\)`),
+  ];
+  for (const re of patterns) {
+    const m = content.match(re);
+    if (m) return { params: parseParamList(m[1]), isDefault: false };
+  }
+
+  // Re-export of a local definition: `export { name }` + a local def.
+  if (new RegExp(`export\\s*\\{[^}]*\\b${n}\\b[^}]*\\}`).test(content)) {
+    const local =
+      content.match(new RegExp(`(?:async\\s+)?function\\s+${n}\\s*\\(([^)]*)\\)`)) ||
+      content.match(new RegExp(`const\\s+${n}\\s*=\\s*(?:async\\s*)?\\(([^)]*)\\)\\s*=>`));
+    if (local) return { params: parseParamList(local[1]), isDefault: false };
+  }
+
+  // CommonJS: `exports.name = (...) =>` / `module.exports.name = function(...)`.
+  const cjsAssign = content.match(
+    new RegExp(`(?:module\\.)?exports\\.${n}\\s*=\\s*(?:async\\s*)?(?:function\\s*[A-Za-z0-9_$]*\\s*)?\\(([^)]*)\\)`),
+  );
+  if (cjsAssign) return { params: parseParamList(cjsAssign[1]), isDefault: false };
+
+  // CommonJS: `module.exports = { name, … }` + a local definition.
+  if (new RegExp(`module\\.exports\\s*=\\s*\\{[^}]*\\b${n}\\b`).test(content)) {
+    const local =
+      content.match(new RegExp(`(?:async\\s+)?function\\s+${n}\\s*\\(([^)]*)\\)`)) ||
+      content.match(new RegExp(`const\\s+${n}\\s*=\\s*(?:async\\s*)?\\(([^)]*)\\)\\s*=>`));
+    if (local) return { params: parseParamList(local[1]), isDefault: false };
+  }
+  return null;
+}
+
+/** Zustand-style store method. Returns { store, params } or null. */
+function findStoreMethod(content, name) {
+  const storeM = content.match(
+    /export\s+const\s+([A-Za-z_$][\w$]*)\s*=\s*create(?:WithEqualityFn|Store)?\s*[<(]/,
+  );
+  if (!storeM) return null;
+  const store = storeM[1];
+  const createIdx = storeM.index || 0;
+  // Search only WITHIN the store body. A TypeScript interface declaring the same
+  // method (e.g. `addToCart: (...) => boolean;`) appears BEFORE create(...) and
+  // would otherwise be matched instead of the real implementation.
+  const body = content.slice(createIdx);
+  const n = esc(name);
+  const patterns = [
+    new RegExp(`${n}\\s*:\\s*(?:async\\s*)?\\(([^)]*)\\)\\s*=>`),
+    new RegExp(`${n}\\s*:\\s*(?:async\\s+)?function\\s*\\(([^)]*)\\)`),
+    new RegExp(`${n}\\s*\\(([^)]*)\\)\\s*\\{`),
+  ];
+  for (const re of patterns) {
+    const m = body.match(re);
+    if (m) return { store, params: parseParamList(m[1]) };
+  }
+  return null;
+}
+
+/**
+ * Map the target function's parameters to the manifest-declared params, by
+ * NAME (never by position — positional guessing is exactly what we must avoid).
+ * Returns { ok:true, args } or { ok:false, reason }.
+ */
+function mapParams(targetParams, manifestParams) {
+  const manifestNames = new Set(manifestParams.map((p) => p.name));
+  const targetNames = new Set(targetParams.filter((p) => p.name).map((p) => p.name));
+
+  for (const mp of manifestParams) {
+    if (mp.required && !targetNames.has(mp.name)) {
+      return {
+        ok: false,
+        reason: `el parámetro requerido '${mp.name}' del manifiesto no existe en la firma de la función`,
+      };
+    }
+  }
+
+  const args = [];
+  for (const tp of targetParams) {
+    if (!tp.safe || tp.name === null) {
+      if (tp.optional) {
+        args.push(null);
+        continue;
+      }
+      return {
+        ok: false,
+        reason: 'la función usa desestructuración o un parámetro rest que no se puede mapear con seguridad',
+      };
+    }
+    if (manifestNames.has(tp.name)) {
+      args.push(`params[${JSON.stringify(tp.name)}]`);
+    } else if (tp.optional) {
+      args.push(null);
+    } else {
+      return {
+        ok: false,
+        reason: `el parámetro '${tp.name}' de la función no tiene un equivalente en el manifiesto`,
+      };
+    }
+  }
+  while (args.length && args[args.length - 1] === null) args.pop();
+  return { ok: true, args: args.map((a) => (a === null ? 'undefined' : a)) };
+}
+
+// ── Plan ──────────────────────────────────────────────────────────────────────
+
+function relImport(fromDirRel, toFileRel) {
+  let rel = path.relative(fromDirRel, normRel(toFileRel)).split(path.sep).join('/');
+  rel = rel.replace(/\.(t|j)sx?$/, '');
+  if (!rel.startsWith('.')) rel = `./${rel}`;
+  return rel;
+}
+
+/**
+ * Turn the AI's proposed wiring for ONE action into a verified `auto` entry, or
+ * return { reason } when the proposal cannot be safely trusted. This is the
+ * heart of the new model: the AI proposes (imports + a call expression read
+ * straight from the user's code) and the verifier confirms every symbol exists
+ * and every identifier the call reads is either imported or a safe global.
+ */
+function buildAiEntry({ appRoot, fyodosDirRel, base, aiW, manifestParams }) {
+  if (!aiW || typeof aiW !== 'object') return { reason: 'la IA no propuso cableado para esta acción' };
+  if (aiW.strategy === 'bridge') {
+    return buildAiBridgeEntry({ appRoot, fyodosDirRel, base, aiW });
+  }
+  if (aiW.strategy && aiW.strategy !== 'module') {
+    return { reason: `estrategia de cableado desconocida: '${aiW.strategy}'` };
+  }
+
+  const call = String(aiW.call || '').trim();
+  if (!call) return { reason: 'la IA no aportó una expresión de llamada (call) verificable' };
+
+  const rawImports = Array.isArray(aiW.imports) ? aiW.imports : [];
+  // 1) Every required symbol must really exist where the AI says it does.
+  const required = Array.isArray(aiW.requiredSymbols) ? aiW.requiredSymbols : [];
+  for (const r of required) {
+    if (!fileHasSymbol(appRoot, r && r.file, r && r.name)) {
+      return {
+        reason: `el verificador no encontró el símbolo '${r && r.name}' en '${normRel(r && r.file)}' (la IA lo propuso pero no existe en el código)`,
+      };
+    }
+  }
+
+  // 2) Build verified imports. Each imported file+name must exist on disk.
+  const imports = [];
+  const importedNames = new Set();
+  for (const imp of rawImports) {
+    const name = String((imp && imp.name) || '').trim();
+    const from = normRel(imp && imp.from);
+    const kind = (imp && imp.kind) || 'named';
+    if (!name || !from) return { reason: 'un import propuesto por la IA está incompleto (falta name/from)' };
+    if (!fs.existsSync(path.join(appRoot, from))) {
+      return { reason: `el import propuesto apunta a un archivo inexistente: '${from}'` };
+    }
+    // For named imports the symbol must be present in that file; default/namespace
+    // bind the module's default/whole export so only file existence is checked.
+    if (kind === 'named' && !fileHasSymbol(appRoot, from, name)) {
+      return { reason: `el import nombrado '${name}' no existe en '${from}'` };
+    }
+    imports.push({ kind, name, importPath: relImport(fyodosDirRel, from) });
+    importedNames.add(name);
+  }
+
+  // 3) Reject the "detached instance" anti-pattern (new Service() + mutate).
+  const detached = detachedInstanceReceiver(call);
+  if (detached) {
+    return {
+      reason:
+        `la expresión instancia '${detached}' con 'new' y la usa como receptor; ` +
+        'si es un servicio/estado inyectado (DI) o un singleton, esa instancia nueva ' +
+        'queda desconectada de la que ve la UI y la acción no tendría efecto observable. ' +
+        'Necesita un puente al singleton real en vez de instanciarlo.',
+    };
+  }
+
+  // 4) Safety: every free identifier the call reads must be imported, a locally
+  //    declared binding, or a safe global. Anything else fails closed (→ review).
+  const locals = declaredLocals(call);
+  for (const id of freeIdentifiers(call)) {
+    if (JS_KEYWORDS.has(id) || importedNames.has(id) || SAFE_GLOBALS.has(id) || locals.has(id)) continue;
+    return {
+      reason: `la expresión de la IA referencia '${id}', que no se importa ni es un global/variable local conocido; no se cablea para no llamar a algo inexistente`,
+    };
+  }
+
+  return {
+    ...base,
+    confidence: 'auto',
+    source: 'ai',
+    kind: 'ai-call',
+    imports,
+    callExpr: call,
+    usesParams: /\bparams\b/.test(call),
+  };
+}
+
+/**
+ * Verify the AI's BRIDGE proposal for ONE action. A bridge edits the user's own
+ * component (under consent) to register the live, in-scope function/instance so
+ * the standalone registry can reach component-local state. The verifier confirms
+ * the edit can be applied SAFELY and that nothing is fabricated:
+ *   · the component file exists and the anchor line is present EXACTLY once
+ *     (so the insertion point is unambiguous and idempotent),
+ *   · every requiredSymbol exists in the code,
+ *   · `invoke` does not create a detached `new Service()` instance,
+ *   · every identifier `invoke` reads is `args`/`this`, a safe global, an import
+ *     the AI declared (and that resolves), or a symbol that exists in the file.
+ * Returns an `auto` entry (kind 'bridge') or { reason } → review.
+ */
+function buildAiBridgeEntry({ appRoot, fyodosDirRel, base, aiW }) {
+  const b = aiW.bridge || {};
+  const file = normRel(b.file);
+  const anchor = String(b.anchor || '').trim();
+  const invoke = String(b.invoke || '').trim();
+  const why = aiW.bridgeReason ? ` (${aiW.bridgeReason})` : '';
+
+  if (!file) return { reason: `la IA marcó puente pero no indicó el archivo del componente${why}` };
+  const content = readFileSafe(appRoot, file);
+  if (content == null) return { reason: `no se pudo leer el componente '${file}' para aplicar el puente` };
+  if (!invoke) return { reason: `la IA no aportó la expresión 'invoke' del puente para '${file}'` };
+  if (!anchor) return { reason: `la IA no aportó un ancla de inserción en '${file}'` };
+
+  const occ = countOccurrences(content, anchor);
+  if (occ === 0) return { reason: `el ancla de inserción no aparece en '${file}'; no se puede ubicar el puente con seguridad` };
+  if (occ > 1) return { reason: `el ancla de inserción aparece ${occ} veces en '${file}'; es ambigua, no se inserta a ciegas` };
+
+  // requiredSymbols must really exist.
+  const required = Array.isArray(aiW.requiredSymbols) ? aiW.requiredSymbols : [];
+  for (const r of required) {
+    if (!fileHasSymbol(appRoot, r && r.file, r && r.name)) {
+      return { reason: `el verificador no encontró el símbolo '${r && r.name}' en '${normRel(r && r.file)}' (puente no verificable)` };
+    }
+  }
+
+  // Never create a fresh, detached instance of a service/singleton.
+  const detached = detachedInstanceReceiver(invoke);
+  if (detached) {
+    return {
+      reason:
+        `el puente instancia '${detached}' con 'new' y la usa como receptor; eso crea una ` +
+        'instancia desconectada de la que ve la UI. Debe usar la instancia real (p. ej. this.<servicio>), no instanciarla.',
+    };
+  }
+
+  // Verify extra imports the invoke needs.
+  const imports = [];
+  const importedNames = new Set();
+  for (const imp of Array.isArray(b.imports) ? b.imports : []) {
+    const name = String((imp && imp.name) || '').trim();
+    const from = normRel(imp && imp.from);
+    const kind = (imp && imp.kind) || 'named';
+    if (!name || !from) return { reason: 'un import del puente está incompleto (falta name/from)' };
+    if (!fs.existsSync(path.join(appRoot, from))) return { reason: `el import del puente apunta a un archivo inexistente: '${from}'` };
+    if (kind === 'named' && !fileHasSymbol(appRoot, from, name)) return { reason: `el import nombrado '${name}' no existe en '${from}'` };
+    imports.push({ kind, name, importPath: relImport(path.dirname(file), from) });
+    importedNames.add(name);
+  }
+
+  // Safety: identifiers `invoke` reads must be accounted for. Inside a component
+  // the scope is rich, so we accept anything that actually appears in the file;
+  // truly unknown identifiers (typos, hallucinations) fail closed.
+  const locals = declaredLocals(invoke);
+  for (const id of freeIdentifiers(invoke)) {
+    if (id === 'args' || JS_KEYWORDS.has(id) || SAFE_GLOBALS.has(id) || locals.has(id) || importedNames.has(id)) continue;
+    if (fileHasSymbol(appRoot, file, id)) continue;
+    return {
+      reason: `el puente referencia '${id}', que no está en el ámbito del componente '${file}' ni se importa; no se cablea para no romper el código`,
+    };
+  }
+
+  const bridgeMethod = base.intent;
+  const scope = b.scope === 'class-field' ? 'class-field' : 'statement';
+  return {
+    ...base,
+    confidence: 'auto',
+    source: 'ai',
+    kind: 'bridge',
+    bridge: {
+      file,
+      anchor,
+      invoke,
+      scope,
+      method: bridgeMethod,
+      imports,
+      importPathToBridge: relImport(path.dirname(file), path.join(fyodosDirRel, BRIDGE_BASENAME)),
+    },
+    callExpr: `getFiodosBridge()[${JSON.stringify(bridgeMethod)}](params)`,
+    usesParams: true,
+  };
+}
+
+/**
+ * Mechanical fallback for ONE action (the original pattern detector), now used
+ * only when the AI did not provide usable wiring. Returns an `auto` entry in the
+ * unified shape, or { reason }.
+ */
+function buildMechanicalEntry({ appRoot, fyodosDirRel, base, manifestParams }) {
+  const { file: evFile, handler } = base;
+  if (!evFile) return { reason: 'el análisis no aportó un archivo de evidencia para esta acción' };
+  const absFile = path.join(appRoot, evFile);
+  let content = null;
+  if (fs.existsSync(absFile)) {
+    try {
+      content = fs.readFileSync(absFile, 'utf8');
+    } catch {
+      content = null;
+    }
+  }
+  if (!content) return { reason: `no se pudo leer el archivo de evidencia '${evFile}'` };
+
+  const exported = findExportedFunction(content, handler);
+  const store = exported ? null : findStoreMethod(content, handler);
+  if (!exported && !store) {
+    return {
+      reason:
+        `no se encontró '${handler}' como función exportada ni como método de store en '${evFile}'. ` +
+        'Puede vivir en un componente, una clase o un hook/contexto. No se cablea a ciegas.',
+    };
+  }
+
+  const targetParams = (exported || store).params;
+  const mapped = mapParams(targetParams, manifestParams);
+  if (!mapped.ok) return { reason: `firma no mapeable con seguridad: ${mapped.reason}` };
+
+  const importPath = relImport(fyodosDirRel, evFile);
+  if (exported) {
+    const localName = exported.isDefault ? `__fyodos_${handler}` : handler;
+    return {
+      ...base,
+      confidence: 'auto',
+      source: 'mechanical',
+      kind: 'exported-fn',
+      imports: [{ kind: exported.isDefault ? 'default' : 'named', name: localName, importPath }],
+      callExpr: `${localName}(${mapped.args.join(', ')})`,
+      usesParams: /params\[/.test(mapped.args.join(', ')),
+    };
+  }
+  return {
+    ...base,
+    confidence: 'auto',
+    source: 'mechanical',
+    kind: 'store-method',
+    imports: [{ kind: 'named', name: store.store, importPath }],
+    callExpr: `${store.store}.getState().${handler}(${mapped.args.join(', ')})`,
+    usesParams: /params\[/.test(mapped.args.join(', ')),
+  };
+}
+
+/**
+ * Build the wiring plan from the produced manifest + evidence + AI wiring.
+ * Source of truth is the AI's per-action wiring (verified); the mechanical
+ * detector is only a fallback. Anything still unverified becomes a `review`
+ * entry (never wired blindly).
+ *
+ * @param {object} args
+ * @param {string} args.appRoot
+ * @param {object} args.manifest
+ * @param {object} args.evidence  { actions: { intent: { file, symbol, whatItDoes } } }
+ * @param {object} [args.wiring]  { <intent>: { strategy, imports, call, requiredSymbols } }
+ * @param {string} args.fyodosDirRel  where the generated registry will live
+ */
+function prepareHandlerPlan({ appRoot, manifest, evidence, wiring = {}, fyodosDirRel }) {
+  const actions = (manifest && manifest.actions) || [];
+  const evActions = (evidence && evidence.actions) || {};
+  const aiWiring = wiring || {};
+  const entries = [];
+
+  for (const action of actions) {
+    const intent = action.intent;
+    const handler = action.handler || intent;
+    const ev = evActions[intent] || {};
+    const evFile = normRel(ev.file);
+    const manifestParams = Object.entries(action.parameters || {}).map(([name, spec]) => ({
+      name,
+      required: spec && spec.required === true,
+    }));
+
+    const base = {
+      intent,
+      handler,
+      label: action.label || intent,
+      file: evFile || null,
+      symbol: ev.symbol || null,
+      whatItDoes: ev.whatItDoes || ev.what || null,
+      requireConfirmation: action.requireConfirmation === true,
+      voiceConfirmation: action.voiceConfirmation || null,
+      idempotencyCheck: action.idempotencyCheck || null,
+      manifestParams,
+    };
+
+    // 1) AI-proposed wiring (verified). Primary source.
+    const aiTry = buildAiEntry({ appRoot, fyodosDirRel, base, aiW: aiWiring[intent], manifestParams });
+    if (aiTry.confidence === 'auto') {
+      entries.push(aiTry);
+      continue;
+    }
+
+    // 2) Mechanical fallback (the old pattern detector).
+    const mechTry = buildMechanicalEntry({ appRoot, fyodosDirRel, base, manifestParams });
+    if (mechTry.confidence === 'auto') {
+      entries.push({ ...mechTry, aiReason: aiTry.reason });
+      continue;
+    }
+
+    // 3) Neither could be verified → needs review, with both reasons.
+    entries.push({
+      ...base,
+      confidence: 'review',
+      reason: aiTry.reason || mechTry.reason,
+      aiReason: aiTry.reason,
+      mechReason: mechTry.reason,
+    });
+  }
+
+  const auto = entries.filter((e) => e.confidence === 'auto');
+  // `manual` retained as an alias for backward-compatible callers/tests.
+  const review = entries.filter((e) => e.confidence === 'review');
+  return { entries, auto, review, manual: review };
+}
+
+// ── Registry codegen (idempotent: regenerated wholesale, clearly marked) ───────
+
+function buildRegistryModule(plan, opts = {}) {
+  const ts = opts.ts !== false;
+  const esm = opts.esm !== false;
+  const hasBridge = plan.auto.some((e) => e.kind === 'bridge');
+
+  // Group MODULE-strategy imports by source path. Bridge entries do NOT import
+  // the user's symbols here — they reach them through the bridge holder — so
+  // their `imports` belong to the component edit, not the registry.
+  const importsByPath = new Map();
+  for (const e of plan.auto) {
+    if (e.kind === 'bridge') continue;
+    for (const imp of e.imports || []) {
+      if (!importsByPath.has(imp.importPath)) {
+        importsByPath.set(imp.importPath, { named: new Set(), defaults: new Set(), namespaces: new Set() });
+      }
+      const grp = importsByPath.get(imp.importPath);
+      if (imp.kind === 'default') grp.defaults.add(imp.name);
+      else if (imp.kind === 'namespace') grp.namespaces.add(imp.name);
+      else grp.named.add(imp.name);
+    }
+  }
+
+  const importLines = [];
+  if (hasBridge) {
+    importLines.push(
+      esm
+        ? `import { getFiodosBridge } from './${BRIDGE_BASENAME}';`
+        : `const { getFiodosBridge } = require('./${BRIDGE_BASENAME}');`,
+    );
+  }
+  for (const [p, grp] of importsByPath) {
+    if (esm) {
+      for (const local of grp.defaults) importLines.push(`import ${local} from '${p}';`);
+      for (const local of grp.namespaces) importLines.push(`import * as ${local} from '${p}';`);
+      if (grp.named.size) importLines.push(`import { ${[...grp.named].join(', ')} } from '${p}';`);
+    } else {
+      if (grp.named.size) importLines.push(`const { ${[...grp.named].join(', ')} } = require('${p}');`);
+      for (const local of grp.defaults) importLines.push(`const ${local} = require('${p}');`);
+      for (const local of grp.namespaces) importLines.push(`const ${local} = require('${p}');`);
+    }
+  }
+
+  // Self-contained types (no @fyodos import) so the file typechecks even before
+  // the SDK is installed; the shape stays structurally compatible with
+  // ActionRegistries when passed to <FiodosAgent registries={...}/>.
+  const typeDefs = ts
+    ? 'type FiodosActionResult = { success: boolean; data?: Record<string, unknown>; error?: string };\n' +
+      'type FiodosRegistries = {\n' +
+      '  handlers: Record<string, (params: Record<string, any>) => Promise<FiodosActionResult>>;\n' +
+      '  idempotencyCheckers: Record<string, (params: Record<string, any>) => boolean | Promise<boolean>>;\n' +
+      '};\n'
+    : '';
+  const resultType = ts ? ': Promise<FiodosActionResult>' : '';
+  const paramsType = ts ? ': Record<string, any>' : '';
+
+  const handlerBlocks = plan.auto.map((e) => {
+    const takesParams = e.usesParams != null ? e.usesParams : /\bparams\b/.test(e.callExpr);
+    const arg = takesParams ? `params${paramsType}` : `_params${paramsType}`;
+    const confNote = e.requireConfirmation
+      ? '\n      // Acción con confirmación: el motor de Fiodos ya pidió confirmación ANTES de llamar aquí.'
+      : '';
+    // `: unknown` lets the truthiness test below be legal even when the wired
+    // call returns void (e.g. db.delete(...)) — otherwise TS errors on `result &&`.
+    const resultDecl = ts ? 'const result: unknown' : 'const result';
+    return (
+      `    ${e.handler}: async (${arg})${resultType} => {${confNote}\n` +
+      `      try {\n` +
+      `        ${resultDecl} = await Promise.resolve(${e.callExpr});\n` +
+      `        return { success: true, data: (result && typeof result === 'object') ? result as Record<string, unknown> : { result } };\n` +
+      `      } catch (err) {\n` +
+      `        return { success: false, error: err instanceof Error ? err.message : String(err) };\n` +
+      `      }\n` +
+      `    },`
+    );
+  });
+
+  // Plain-JS variant: drop the `as` cast.
+  const handlerText = (ts ? handlerBlocks.join('\n') : handlerBlocks.join('\n').replace(/ as Record<string, unknown>/g, ''));
+
+  const manualNotes = plan.manual.map(
+    (e) => `    // MANUAL — '${e.intent}' (${e.handler}): ${e.reason}`,
+  );
+
+  const header =
+    `/**\n` +
+    ` * ${GENERATED_MARKER}.\n` +
+    ` * No edites a mano: re-ejecuta el instalador de Fiodos para regenerarlo.\n` +
+    ` * Lee ${DOC_BASENAME} (misma carpeta) para saber qué cablea y por qué.\n` +
+    ` *\n` +
+    ` * SEGURIDAD: este archivo solo LLAMA a tus funciones. Nunca decide si una\n` +
+    ` * acción sensible se ejecuta — el motor de Fiodos aplica las confirmaciones\n` +
+    ` * del manifiesto (requireConfirmation / voiceConfirmation) ANTES de invocar\n` +
+    ` * cualquier handler de aquí.\n` +
+    ` */\n`;
+
+  const decl = esm
+    ? `export const ${REGISTRY_EXPORT}${ts ? ': FiodosRegistries' : ''} = {`
+    : `const ${REGISTRY_EXPORT}${ts ? ': FiodosRegistries' : ''} = {`;
+
+  const body =
+    `${header}\n` +
+    `${importLines.join('\n')}\n\n` +
+    (typeDefs ? `${typeDefs}\n` : '') +
+    `${decl}\n` +
+    `  handlers: {\n` +
+    `${handlerText}\n` +
+    (manualNotes.length ? `${manualNotes.join('\n')}\n` : '') +
+    `  },\n` +
+    `  // Los idempotency checkers leen el estado de tu app; impleméntalos a mano si\n` +
+    `  // alguna acción declara idempotencyCheck (ver ${DOC_BASENAME}).\n` +
+    `  idempotencyCheckers: {},\n` +
+    `};\n` +
+    (esm ? '' : `\nmodule.exports = { ${REGISTRY_EXPORT} };\n`);
+
+  return body;
+}
+
+/**
+ * The bridge holder module: a tiny module-level registry the component writes
+ * its LIVE in-scope functions into (registerFiodosBridge) and the generated
+ * handlers read from (getFiodosBridge). This is what lets a standalone module
+ * reach component-local state without ever creating a detached instance.
+ */
+function buildBridgeModule(opts = {}) {
+  const ts = opts.ts !== false;
+  const esm = opts.esm !== false;
+  const header =
+    `/**\n` +
+    ` * ${GENERATED_MARKER} (bridge holder).\n` +
+    ` * No edites a mano. Tu componente registra aquí sus funciones reales y los\n` +
+    ` * handlers generados las invocan. Es lo que conecta el agente con el estado\n` +
+    ` * que vive dentro de tus componentes, sin crear instancias desconectadas.\n` +
+    ` */\n`;
+  if (ts) {
+    return (
+      `${header}\n` +
+      `type FiodosBridge = Record<string, (args: any) => any>;\n\n` +
+      `let __fyodosBridge: FiodosBridge = {};\n\n` +
+      `export function registerFiodosBridge(fns: FiodosBridge): void {\n` +
+      `  __fyodosBridge = { ...__fyodosBridge, ...fns };\n` +
+      `}\n\n` +
+      `export function getFiodosBridge(): FiodosBridge {\n` +
+      `  return __fyodosBridge;\n` +
+      `}\n`
+    );
+  }
+  if (esm) {
+    return (
+      `${header}\n` +
+      `let __fyodosBridge = {};\n\n` +
+      `export function registerFiodosBridge(fns) {\n` +
+      `  __fyodosBridge = { ...__fyodosBridge, ...fns };\n` +
+      `}\n\n` +
+      `export function getFiodosBridge() {\n` +
+      `  return __fyodosBridge;\n` +
+      `}\n`
+    );
+  }
+  return (
+    `${header}\n` +
+    `let __fyodosBridge = {};\n\n` +
+    `function registerFiodosBridge(fns) {\n` +
+    `  __fyodosBridge = { ...__fyodosBridge, ...fns };\n` +
+    `}\n\n` +
+    `function getFiodosBridge() {\n` +
+    `  return __fyodosBridge;\n` +
+    `}\n\n` +
+    `module.exports = { registerFiodosBridge, getFiodosBridge };\n`
+  );
+}
+
+/**
+ * Plan the edits to the user's own component files for all BRIDGE entries.
+ * Groups bridge entries by component file and produces, per file:
+ *   · the import line for registerFiodosBridge (+ any extra imports invoke needs),
+ *   · a single registerFiodosBridge({...}) block,
+ *   · the anchor after which the block is inserted (the one occurring LAST in
+ *     the file among the group, so every referenced symbol is already defined).
+ * The actual mutation/idempotence/backup happens in applyComponentEdits.
+ */
+function planComponentEdits(appRoot, plan, opts = {}) {
+  const ts = opts.ts !== false;
+  const byFile = new Map();
+  for (const e of plan.auto) {
+    if (e.kind !== 'bridge') continue;
+    if (!byFile.has(e.bridge.file)) byFile.set(e.bridge.file, []);
+    byFile.get(e.bridge.file).push(e);
+  }
+
+  const edits = [];
+  for (const [file, entries] of byFile) {
+    const content = readFileSafe(appRoot, file) || '';
+    // Pick the anchor that appears LAST in the file (all symbols defined by then).
+    let anchor = entries[0].bridge.anchor;
+    let bestIdx = content.indexOf(anchor);
+    for (const e of entries) {
+      const idx = content.indexOf(e.bridge.anchor);
+      if (idx > bestIdx) {
+        bestIdx = idx;
+        anchor = e.bridge.anchor;
+      }
+    }
+
+    const argType = ts ? ': any' : '';
+    const classField = entries.some((e) => e.bridge.scope === 'class-field');
+    const methods = entries.map((e) => {
+      const inv = e.bridge.invoke;
+      return `  ${JSON.stringify(e.bridge.method)}: (args${argType}) => (${inv}),`;
+    });
+
+    // Imports: registerFiodosBridge + any extra the invokes need (deduped).
+    const importPathToBridge = entries[0].bridge.importPathToBridge;
+    const importLines = [`import { registerFiodosBridge } from '${importPathToBridge}';`];
+    const seen = new Set();
+    for (const e of entries) {
+      for (const imp of e.bridge.imports || []) {
+        const key = `${imp.kind}:${imp.name}:${imp.importPath}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        if (imp.kind === 'default') importLines.push(`import ${imp.name} from '${imp.importPath}';`);
+        else if (imp.kind === 'namespace') importLines.push(`import * as ${imp.name} from '${imp.importPath}';`);
+        else importLines.push(`import { ${imp.name} } from '${imp.importPath}';`);
+      }
+    }
+
+    // In a class body a bare call is a syntax error; bind it to a field so the
+    // arrow functions capture the live `this` (the real injected instance).
+    const registerCall = classField
+      ? `private __fyodosBridge = registerFiodosBridge({\n${methods.join('\n')}\n});`
+      : `registerFiodosBridge({\n${methods.join('\n')}\n});`;
+    const registerBlock = `${EDIT_START}\n${registerCall}\n${EDIT_END}`;
+
+    // Match the anchor's leading indentation so the inserted block stays tidy.
+    const lineStart = content.lastIndexOf('\n', bestIdx) + 1;
+    const indent = (content.slice(lineStart, bestIdx).match(/^\s*/) || [''])[0];
+
+    edits.push({
+      file,
+      anchor,
+      scope: classField ? 'class-field' : 'statement',
+      importBlock: `${EDIT_START}\n${importLines.join('\n')}\n${EDIT_END}`,
+      registerBlock: registerBlock.split('\n').map((l) => (l ? indent + l : l)).join('\n'),
+      intents: entries.map((e) => e.intent),
+    });
+  }
+  return edits;
+}
+
+// ── Document codegen ───────────────────────────────────────────────────────────
+
+function confLabel(e) {
+  if (!e.requireConfirmation) return 'no requiere confirmación';
+  const mode = e.voiceConfirmation ? ` (voz: ${e.voiceConfirmation})` : '';
+  return `requiere confirmación${mode}`;
+}
+
+function buildHandlerDoc(plan, ctx = {}) {
+  const {
+    appName = 'tu app', framework = 'web', registryRel = '', mountSnippet = '',
+    bridgeRel = '', edits = [], verification = null,
+  } = ctx;
+  const L = [];
+  L.push('# Cableado de acciones de Fiodos (handler wiring)');
+  L.push('');
+  L.push(
+    'Este documento describe **exactamente** qué hará Fiodos para conectar las ' +
+      'acciones detectadas en tu app con las funciones reales que las ejecutan. ' +
+      '**Nada se aplica hasta que aceptes en el terminal.**',
+  );
+  L.push('');
+  const review = plan.review || plan.manual || [];
+  const aiCount = plan.auto.filter((e) => e.source === 'ai').length;
+  L.push(`- App: **${appName}**`);
+  L.push(`- Framework detectado: **${framework}**`);
+  L.push(`- Acciones que se cablearán automáticamente: **${plan.auto.length}** ` +
+    `(${aiCount} cableadas por la IA, ${plan.auto.length - aiCount} por el detector mecánico de respaldo)`);
+  L.push(`- Acciones que necesitan revisión: **${review.length}**`);
+  L.push('');
+  L.push('## ¿Cómo se genera este cableado?');
+  L.push('');
+  L.push(
+    'La **misma IA** que analizó tu código para detectar las acciones también propuso ' +
+      'cómo ejecutarlas: qué función/módulo real llamar y cómo mapear los parámetros. ' +
+      'Después, un **verificador mecánico** comprueba que cada símbolo referenciado ' +
+      'existe de verdad en tu código antes de escribir nada. Si la IA propone algo que ' +
+      'el verificador no encuentra, esa acción queda **para revisión**, nunca se cablea a ciegas.',
+  );
+  L.push('');
+  if (Array.isArray(verification) && verification.length) {
+    L.push('## Verificación automática (efecto real + reintentos)');
+    L.push('');
+    L.push(
+      'Tras tu "yes", la instalación **no se fía** de que el cableado compile: por cada ' +
+        'acción ejecuta un bucle **cablear → verificar → diagnosticar → corregir** sin ' +
+        'intervención humana. La verificación comprueba (1) que el proyecto **sigue ' +
+        'compilando** con esa acción cableada y, cuando es seguro simularlo, (2) que al ' +
+        'invocar el handler **el estado real cambia** (la tarea se añade, etc.). Si una ' +
+        'acción falla, la IA recibe el **error concreto** y reintenta con un cableado ' +
+        'corregido (hasta varios intentos). Una acción solo se marca **lista** cuando pasa ' +
+        'la verificación; si tras los reintentos no se logra, se **revierte solo esa ' +
+        'acción** y se marca abajo como "no se pudo cablear" — nunca se deja fingiendo.',
+    );
+    L.push('');
+    L.push('| Acción (intent) | Resultado | Intentos | Verificación | Detalle |');
+    L.push('| --- | --- | --- | --- | --- |');
+    for (const v of verification) {
+      const res = v.status === 'ready' ? '✅ lista' : '❌ no se pudo';
+      let lvl = '—';
+      if (v.status === 'ready') {
+        lvl = v.level === 'effect' ? 'efecto real (UI)'
+          : v.level === 'unverifiable' ? '⚠️ efecto NO verificable (revisar a mano)'
+            : 'compilación';
+      }
+      const detail = String(v.detail || v.error || '').replace(/\|/g, '\\|').slice(0, 160);
+      L.push(`| \`${v.intent}\` | ${res} | ${v.attempts} | ${lvl} | ${detail} |`);
+    }
+    L.push('');
+    L.push('_"efecto real (UI)" = se montó el componente real en un DOM de prueba (jsdom) con ' +
+      'la herramienta estándar del framework (React: react-dom; Vue: vue + @vue/compiler-sfc), ' +
+      'se invocó el handler cableado y se **observó el cambio en la UI/estado** (la tarea aparece, ' +
+      'el item se alterna, etc.). Para la capa de datos (Dexie/store) el efecto se observa ejecutando ' +
+      'la acción contra una instancia real. "compilación" = compila y el símbolo real existe y se ' +
+      'invoca, pero el efecto no pudo simularse de forma segura aquí. "⚠️ efecto NO verificable" = ' +
+      'el cableado se aplicó pero el efecto real no se pudo confirmar automáticamente (componente no ' +
+      'montable en aislamiento, o acción sensible que no se dispara) — **revisar/probar a mano**. Las ' +
+      'acciones sensibles (con confirmación) **nunca** se disparan en la prueba._');
+    L.push('');
+  }
+
+  L.push('## ¿Por qué es necesario?');
+  L.push('');
+  L.push(
+    'El orbe ya está montado, pero el agente no puede **ejecutar** acciones hasta ' +
+      'que cada acción del manifiesto esté conectada a la función real de tu app. ' +
+      'Este cableado es ese puente: traduce cada acción (p. ej. `addToCart`) en una ' +
+      'llamada a tu función (p. ej. `useShop.getState().addToCart(...)`).',
+  );
+  L.push('');
+  const bridgeEntries = plan.auto.filter((e) => e.kind === 'bridge');
+  L.push('## Qué archivos se crean / editan');
+  L.push('');
+  L.push(`- **CREA** \`${registryRel}\` — el registro de handlers generado.`);
+  if (bridgeEntries.length && bridgeRel) {
+    L.push(`- **CREA** \`${bridgeRel}\` — el "puente" donde tu componente registra sus funciones reales.`);
+  }
+  if (edits.length) {
+    L.push('- **EDITA los siguientes archivos TUYOS** (solo añade líneas marcadas con ' +
+      '`FYODOS:BRIDGE`, reversibles):');
+    for (const ed of edits) L.push(`  - \`${ed.file}\` — registra: ${ed.intents.map((i) => `\`${i}\``).join(', ')}`);
+  } else {
+    L.push('- **No se edita ningún archivo existente tuyo** (todas las acciones eran ' +
+      'alcanzables desde un módulo).');
+  }
+  L.push('- Para activarlo, pasa el registro generado a `<FiodosAgent/>` (ver "Cómo activarlo").');
+  L.push('');
+
+  if (edits.length) {
+    L.push('## Cambios EXACTOS dentro de tus componentes');
+    L.push('');
+    L.push('Estas son las líneas que Fiodos añadirá a tus archivos (cada bloque va entre ' +
+      'marcas `FYODOS:BRIDGE:START` / `END`, así puedes quitarlas o revertirlas sin tocar ' +
+      'tu propio código):');
+    L.push('');
+    for (const ed of edits) {
+      L.push(`### \`${ed.file}\``);
+      L.push('');
+      L.push('Tras la última línea `import`, se añade:');
+      L.push('');
+      L.push('```ts');
+      L.push(ed.importBlock);
+      L.push('```');
+      L.push('');
+      L.push(ed.file.endsWith('.vue')
+        ? 'Justo antes de `</script>`, se añade:'
+        : `Junto al ancla \`${(ed.anchor || '').trim().slice(0, 80)}\`, se añade:`);
+      L.push('');
+      L.push('```ts');
+      L.push(ed.registerBlock.replace(/^\s+/gm, (s) => s)); // keep as-is
+      L.push('```');
+      L.push('');
+    }
+  }
+
+  if (plan.auto.length) {
+    L.push(`## Acciones que se cablearán automáticamente (${plan.auto.length})`);
+    L.push('');
+    L.push('| Acción (intent) | Cómo se ejecuta | Dónde | Parámetros | Tipo | Seguridad |');
+    L.push('| --- | --- | --- | --- | --- | --- |');
+    for (const e of plan.auto) {
+      const expr = e.kind === 'bridge' ? e.bridge.invoke : e.callExpr;
+      const call = `\`${String(expr).replace(/\|/g, '\\|')}\``;
+      const where = e.kind === 'bridge' ? `\`${e.bridge.file}\`` : `\`${e.file || '—'}\``;
+      const params = e.manifestParams.length
+        ? e.manifestParams.map((p) => `${p.name}${p.required ? '*' : ''}`).join(', ')
+        : '—';
+      const kind = e.kind === 'bridge'
+        ? 'puente (edita tu componente)'
+        : (e.source === 'ai' ? 'módulo (IA)' : 'módulo (mecánico)');
+      L.push(`| \`${e.intent}\` | ${call} | ${where} | ${params} | ${kind} | ${confLabel(e)} |`);
+    }
+    L.push('');
+    L.push('_`*` = parámetro requerido. Cada llamada fue propuesta por la IA leyendo tu ' +
+      'código y **confirmada por el verificador** (los símbolos existen). Los parámetros ' +
+      'se mapean **por nombre**, nunca por posición._');
+    L.push('');
+  }
+
+  if (review.length) {
+    L.push(`## Acciones que necesitan REVISIÓN (${review.length})`);
+    L.push('');
+    L.push(
+      'Para estas acciones, ni la IA propuso un cableado **verificable** ni el detector ' +
+        'mecánico de respaldo encontró la función con seguridad. Cablearlas mal sería ' +
+        'peor que dejarlas sin cablear, así que se marcan para revisión y te explicamos por qué:',
+    );
+    L.push('');
+    for (const e of review) {
+      L.push(`### \`${e.intent}\` — ${e.label}`);
+      L.push('');
+      L.push(`- Handler esperado: \`${e.handler}\``);
+      if (e.file) L.push(`- Archivo de evidencia: \`${e.file}\``);
+      L.push(`- Motivo: ${e.reason}`);
+      L.push(
+        `- Qué hacer: añade un handler \`${e.handler}\` en \`${registryRel}\` (o en tu ` +
+          'propio registro) que llame a la función real y devuelva ' +
+          '`{ success: true }` (o `{ success: false, message }`).',
+      );
+      L.push('');
+    }
+  }
+
+  const confirmed = plan.entries.filter((e) => e.requireConfirmation);
+  L.push('## Seguridad');
+  L.push('');
+  L.push(
+    '- El cableado generado **solo llama** a tus funciones. **Nunca** decide si una ' +
+      'acción sensible se ejecuta: el motor de Fiodos aplica las confirmaciones del ' +
+      'manifiesto (`requireConfirmation` / `voiceConfirmation`) **antes** de invocar ' +
+      'el handler. Es imposible que el auto-cableado salte una confirmación.',
+  );
+  if (confirmed.length) {
+    L.push('- Acciones protegidas por confirmación (el agente pedirá confirmar antes de ejecutarlas):');
+    for (const e of confirmed) {
+      L.push(`  - \`${e.intent}\` — ${confLabel(e)}.`);
+    }
+  } else {
+    L.push('- Ninguna de las acciones detectadas requiere confirmación en el manifiesto.');
+  }
+  L.push('- El cableado no lee, incrusta ni expone secretos; solo referencia nombres de');
+  L.push('  función y los parámetros que el manifiesto ya declara.');
+  L.push('');
+
+  L.push('## Cómo activarlo');
+  L.push('');
+  if (mountSnippet) {
+    L.push('Pasa el registro generado a tu `<FiodosAgent/>`:');
+    L.push('');
+    L.push('```tsx');
+    L.push(mountSnippet);
+    L.push('```');
+  } else {
+    L.push('Importa `' + REGISTRY_EXPORT + '` desde el archivo generado y pásalo como ' +
+      '`registries` a tu `<FiodosAgent/>`.');
+  }
+  L.push('');
+  L.push('## Si dijiste "no"');
+  L.push('');
+  L.push(
+    'No se ha tocado tu código. Puedes implementar el cableado tú mismo siguiendo ' +
+      'este documento, o volver a ejecutar el instalador para aceptar el auto-cableado ' +
+      '(`--wire-yes` para aceptarlo sin preguntar).',
+  );
+  L.push('');
+  return L.join('\n');
+}
+
+// ── Editing the user's own files (idempotent + reversible) ─────────────────────
+
+/** Remove any previously-inserted Fiodos blocks (idempotence across re-runs). */
+function stripFiodosBlocks(content) {
+  const re = new RegExp(`\\n?${esc(EDIT_START)}[\\s\\S]*?${esc(EDIT_END)}\\n?`, 'g');
+  return content.replace(re, '\n');
+}
+
+/** Insert an import block right after the file's last top-level import line. */
+function insertImportBlock(content, importBlock) {
+  const importLineRe = /^[ \t]*import\b[^\n]*\n/gm;
+  let lastEnd = -1;
+  let m;
+  while ((m = importLineRe.exec(content))) lastEnd = m.index + m[0].length;
+  if (lastEnd === -1) {
+    // No imports (rare). Put it after a leading <script ...> tag if present.
+    const scriptM = content.match(/<script\b[^>]*>\s*\n/);
+    if (scriptM) {
+      const at = scriptM.index + scriptM[0].length;
+      return content.slice(0, at) + importBlock + '\n' + content.slice(at);
+    }
+    return importBlock + '\n' + content;
+  }
+  return content.slice(0, lastEnd) + importBlock + '\n' + content.slice(lastEnd);
+}
+
+/** Index of the JSX/paren `return (` or `return <` line nearest to `anchorIdx`. */
+function nearestJsxReturn(content, anchorIdx) {
+  const re = /^[ \t]*return\s*[(<]/gm;
+  let best = -1;
+  let bestDist = Infinity;
+  let m;
+  while ((m = re.exec(content))) {
+    const dist = Math.abs(m.index - anchorIdx);
+    if (dist < bestDist) { bestDist = dist; best = m.index; }
+  }
+  return best;
+}
+
+/**
+ * Insert the registration block at a SYNTACTICALLY VALID spot:
+ *   · .vue files → just before the last </script>,
+ *   · class-field scope (Angular @Component) → right AFTER the anchor line, inside
+ *     the class body (the anchor is a sibling class field),
+ *   · statement scope (React/JS function component) → just BEFORE the JSX `return`
+ *     nearest the anchor, so the call is always a statement and NEVER lands inside
+ *     JSX (which produced `Expected "}" but found ":"`). The AI's anchor only needs
+ *     to locate the right component, not the exact insertion line.
+ *   · fallback (no JSX return: object-returning factories, etc.) → before a
+ *     `return` anchor, else after the anchor line.
+ */
+function insertRegisterBlock(content, file, anchor, block, scope) {
+  if (file.endsWith('.vue')) {
+    const close = content.lastIndexOf('</script>');
+    if (close !== -1) {
+      const lineStart = content.lastIndexOf('\n', close) + 1;
+      return content.slice(0, lineStart) + block + '\n' + content.slice(lineStart);
+    }
+  }
+  const at = content.indexOf(anchor);
+  if (at === -1) return content; // verified earlier; defensive
+
+  if (scope === 'class-field') {
+    const lineEnd = content.indexOf('\n', at);
+    const endIdx = lineEnd === -1 ? content.length : lineEnd;
+    return content.slice(0, endIdx) + '\n' + block + content.slice(endIdx);
+  }
+
+  const ret = nearestJsxReturn(content, at);
+  if (ret !== -1) {
+    const lineStart = content.lastIndexOf('\n', ret) + 1;
+    return content.slice(0, lineStart) + block + '\n' + content.slice(lineStart);
+  }
+
+  const lineStart = content.lastIndexOf('\n', at) + 1;
+  if (anchor.trim().startsWith('return')) {
+    return content.slice(0, lineStart) + block + '\n' + content.slice(lineStart);
+  }
+  const lineEnd = content.indexOf('\n', at);
+  const endIdx = lineEnd === -1 ? content.length : lineEnd;
+  return content.slice(0, endIdx) + '\n' + block + content.slice(endIdx);
+}
+
+/**
+ * Apply all planned component edits. Snapshots each file's original content
+ * first (for clean revert) and is idempotent (strips prior Fiodos blocks before
+ * re-inserting). Returns { backups: [{file, original}], edited: [file...] }.
+ */
+function applyComponentEdits(appRoot, edits) {
+  const backups = [];
+  const edited = [];
+  for (const edit of edits) {
+    const abs = path.join(appRoot, normRel(edit.file));
+    const original = fs.readFileSync(abs, 'utf8');
+    backups.push({ file: edit.file, abs, original });
+
+    let next = stripFiodosBlocks(original);
+    next = insertImportBlock(next, edit.importBlock);
+    next = insertRegisterBlock(next, edit.file, edit.anchor, edit.registerBlock, edit.scope);
+    fs.writeFileSync(abs, next);
+    edited.push(edit.file);
+  }
+  return { backups, edited };
+}
+
+/** Restore files to their pre-edit content and delete generated files. */
+function revertAll(backups, generatedFiles) {
+  for (const b of backups || []) {
+    try {
+      fs.writeFileSync(b.abs, b.original);
+    } catch {
+      /* best effort */
+    }
+  }
+  for (const f of generatedFiles || []) {
+    try {
+      if (fs.existsSync(f)) fs.rmSync(f);
+    } catch {
+      /* best effort */
+    }
+  }
+}
+
+// ── Consent ────────────────────────────────────────────────────────────────────
+
+function askYesNo(question) {
+  return new Promise((resolve) => {
+    if (!process.stdin.isTTY) {
+      resolve(false);
+      return;
+    }
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(/^(y|yes|s|si|sí)/i.test((answer || '').trim()));
+    });
+  });
+}
+
+// ── Folder resolution ───────────────────────────────────────────────────────────
+
+/** Where the Fiodos folder lives in the user's project (relative to appRoot). */
+function resolveFiodosDirRel(appRoot) {
+  if (fs.existsSync(path.join(appRoot, 'src'))) return path.join('src', 'fyodos');
+  return 'fyodos';
+}
+
+function detectTsEsm(appRoot) {
+  let ts = fs.existsSync(path.join(appRoot, 'tsconfig.json'));
+  let esm = true;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(appRoot, 'package.json'), 'utf8'));
+    if (pkg.type === 'commonjs') esm = false;
+    const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+    if (deps.typescript) ts = true;
+  } catch {
+    /* defaults */
+  }
+  return { ts, esm };
+}
+
+// ── Auto-correction loop (verify → diagnose → correct → retry, per action) ─────
+
+/** Build the single verified entry for one action from a given wiring candidate. */
+function planOneAction({ appRoot, manifest, evidence, candidate, intent, fyodosDirRel }) {
+  const action = (manifest.actions || []).find((a) => a.intent === intent);
+  const plan = prepareHandlerPlan({
+    appRoot,
+    manifest: { ...manifest, actions: [action] },
+    evidence,
+    wiring: { [intent]: candidate },
+    fyodosDirRel,
+  });
+  return { entry: plan.auto[0] || null, review: plan.review[0] || null };
+}
+
+/** Pick the few files the corrector needs (keeps the re-prompt small/cheap). */
+function pickRelevantFiles(files, evidence, candidate, intent) {
+  if (!Array.isArray(files) || !files.length) return [];
+  const wanted = new Set();
+  const ev = (evidence.actions || {})[intent];
+  if (ev && ev.file) wanted.add(normRel(ev.file));
+  if (candidate) {
+    if (candidate.bridge && candidate.bridge.file) wanted.add(normRel(candidate.bridge.file));
+    for (const imp of candidate.imports || []) if (imp && imp.from) wanted.add(normRel(imp.from));
+    for (const imp of (candidate.bridge && candidate.bridge.imports) || []) if (imp && imp.from) wanted.add(normRel(imp.from));
+    for (const r of candidate.requiredSymbols || []) if (r && r.file) wanted.add(normRel(r.file));
+  }
+  const picked = files.filter((f) => wanted.has(normRel(f.rel)));
+  return picked.length ? picked : files.slice(0, 4);
+}
+
+/** Write ONLY one entry (registry + bridge + its edit) for isolated verification. */
+function writeIsolated({ appRoot, fyodosDirAbs, entry, ts, esm, ext }) {
+  const onePlan = { auto: [entry], review: [], manual: [], entries: [entry] };
+  const registryAbs = path.join(fyodosDirAbs, `${REGISTRY_BASENAME}${ext}`);
+  const bridgeAbs = path.join(fyodosDirAbs, `${BRIDGE_BASENAME}${ext}`);
+  const generated = [registryAbs];
+  if (entry.kind === 'bridge') {
+    fs.writeFileSync(bridgeAbs, buildBridgeModule({ ts, esm }));
+    generated.push(bridgeAbs);
+  }
+  fs.writeFileSync(registryAbs, buildRegistryModule(onePlan, { ts, esm }));
+  const edits = planComponentEdits(appRoot, onePlan, { ts });
+  const { backups } = applyComponentEdits(appRoot, edits);
+  return { backups, generated, touched: [...edits.map((e) => e.file), registryAbs, bridgeAbs] };
+}
+
+/**
+ * The install-time loop. For EVERY action: build its wiring candidate, write it
+ * in isolation, verify (compile regression + effect probe), and on failure ask
+ * the AI to correct it with the concrete error — up to maxAttempts. An action is
+ * only "ready" once it passes; otherwise it is dropped (its edits reverted) and
+ * reported honestly. Finally the ready entries are written together and a last
+ * build confirms the combination did not regress.
+ */
+async function runAutoCorrectionLoop(ctx) {
+  const {
+    appRoot, fyodosDirRel, fyodosDirAbs, manifest, evidence, wiringMap,
+    ts, esm, ext, testRunner, corrector, files, framework,
+    maxAttempts = 3, tag, dim, reset, registryRel,
+  } = ctx;
+
+  const log = (m) => console.error(`${tag} · ${dim || ''}${m}${reset || ''}`);
+  log('verificando y auto-corrigiendo cada acción (puede tardar)…');
+  const baseline = await testRunner(appRoot, { framework });
+
+  const ready = [];
+  const dropped = [];
+  const attemptsLog = [];
+
+  for (const action of manifest.actions || []) {
+    const intent = action.intent;
+    let attempt = 0;
+    let lastError = '';
+    let resolved = null;
+    const history = [];
+
+    while (attempt < maxAttempts) {
+      attempt += 1;
+      const { entry, review } = planOneAction({ appRoot, manifest, evidence, candidate: wiringMap[intent], intent, fyodosDirRel });
+
+      if (!entry) {
+        lastError = (review && review.reason) || 'no verificable mecánicamente';
+        history.push({ attempt, stage: 'mechanical', ok: false, error: lastError });
+      } else {
+        const iso = writeIsolated({ appRoot, fyodosDirAbs, entry, ts, esm, ext });
+        let ok = true;
+        let stage = 'compile';
+        try {
+          const after = await testRunner(appRoot, { framework });
+          const reg = compileRegressed(baseline.output, after.output, iso.touched);
+          if (!reg.ok) { ok = false; lastError = `compilación: ${reg.newErrors.join(' | ').slice(0, 600)}`; }
+          if (ok) {
+            const eff = await probeEffect(appRoot, entry, { fyodosDirRel, framework, sources: files, sensitive: entry.requireConfirmation });
+            if (eff.status === 'fail') { ok = false; stage = 'effect'; lastError = `efecto: ${eff.detail}`; }
+            else {
+              const level = eff.status === 'effect-pass' ? 'effect'
+                : eff.status === 'unverifiable' ? 'unverifiable'
+                  : 'compile';
+              resolved = { entry, level, detail: eff.detail };
+            }
+          }
+        } catch (err) {
+          ok = false; lastError = `verificación lanzó: ${err && err.message}`;
+        } finally {
+          revertAll(iso.backups, iso.generated);
+        }
+        history.push({ attempt, stage, ok, error: ok ? undefined : lastError, level: resolved && resolved.level, detail: resolved && resolved.detail });
+        if (resolved) break;
+      }
+
+      if (attempt >= maxAttempts || typeof corrector !== 'function') break;
+      log(`acción '${intent}' falló (intento ${attempt}): ${lastError.slice(0, 120)} → pidiendo corrección a la IA…`);
+      try {
+        const relevantFiles = pickRelevantFiles(files, evidence, wiringMap[intent], intent);
+        const corrected = await corrector({ action, intent, evidence: (evidence && evidence.actions) || {}, relevantFiles, prevWiring: wiringMap[intent], errorText: lastError, attempt });
+        if (corrected && corrected[intent]) wiringMap[intent] = corrected[intent];
+        else { history.push({ attempt, stage: 'correct', ok: false, error: 'la IA no devolvió cableado corregido' }); break; }
+      } catch (err) {
+        history.push({ attempt, stage: 'correct', ok: false, error: `corrector falló: ${err && err.message}` });
+        break;
+      }
+    }
+
+    if (resolved) {
+      ready.push(resolved.entry);
+      attemptsLog.push({ intent, attempts: attempt, status: 'ready', level: resolved.level, detail: resolved.detail, history });
+      log(`✓ '${intent}' verificada en ${attempt} intento(s) [${resolved.level === 'effect' ? 'efecto real' : 'compilación'}].`);
+    } else {
+      dropped.push({ ...action, intent, reason: lastError, attempts: attempt, handler: action.handler || intent, label: action.label || intent, manifestParams: Object.entries(action.parameters || {}).map(([name, spec]) => ({ name, required: spec && spec.required === true })) });
+      attemptsLog.push({ intent, attempts: attempt, status: 'dropped', error: lastError, history });
+      log(`✗ '${intent}' no se pudo cablear tras ${attempt} intento(s): ${lastError.slice(0, 140)}`);
+    }
+  }
+
+  return { baseline, ready, dropped, attemptsLog };
+}
+
+// ── Public API ───────────────────────────────────────────────────────────────
+
+/**
+ * Prepare + document + (on consent) apply the handler wiring.
+ * Returns { status, docPath?, registryFile?, autoCount, manualCount, plan }.
+ *   status: 'no-actions' | 'manual-only' | 'declined' | 'declined-noninteractive'
+ *         | 'applied' | 'skipped' | 'failed'
+ */
+async function wireHandlers(appRoot, opts = {}) {
+  const {
+    manifest,
+    evidence = {},
+    wiring = {},
+    colors = {},
+    assumeYes = false,
+    noWire = false,
+    framework = 'web',
+    appName,
+    registryExt: registryExtOpt,
+    esm: esmOpt,
+    ts: tsOpt,
+    runTest = false,
+    revertOnFailure = true,
+    testRunner = null,
+    corrector = null,
+    files = [],
+    maxAttempts = 3,
+  } = opts;
+  const { blue, cyan, dim, reset } = colors;
+  const tag = `${cyan || ''}◉${reset || ''} ${blue || ''}Fiodos${reset || ''}`;
+
+  if (noWire) return { status: 'skipped' };
+  const actions = (manifest && manifest.actions) || [];
+  if (!actions.length) return { status: 'no-actions' };
+
+  const fyodosDirRel = resolveFiodosDirRel(appRoot);
+  const fyodosDirAbs = path.join(appRoot, fyodosDirRel);
+  const detected = detectTsEsm(appRoot);
+  const ts = tsOpt != null ? tsOpt : detected.ts;
+  const esm = esmOpt != null ? esmOpt : detected.esm;
+  const ext = registryExtOpt || (ts ? '.ts' : esm ? '.js' : '.cjs');
+
+  const plan = prepareHandlerPlan({ appRoot, manifest, evidence, wiring, fyodosDirRel });
+  const hasBridge = plan.auto.some((e) => e.kind === 'bridge');
+  const componentEdits = planComponentEdits(appRoot, plan, { ts });
+  const registryRel = path.join(fyodosDirRel, `${REGISTRY_BASENAME}${ext}`).split(path.sep).join('/');
+  const bridgeRel = path.join(fyodosDirRel, `${BRIDGE_BASENAME}${ext}`).split(path.sep).join('/');
+  const registryImport = `./${REGISTRY_BASENAME}`;
+
+  const mountSnippet =
+    `import { ${REGISTRY_EXPORT} } from '${registryImport}';\n` +
+    `\n` +
+    `<FiodosAgent\n` +
+    `  apiKey={/* tu API key */}\n` +
+    `  registries={${REGISTRY_EXPORT}}\n` +
+    `/>`;
+
+  // 1) ALWAYS write the document first, so the developer can read before consenting.
+  fs.mkdirSync(fyodosDirAbs, { recursive: true });
+  const docAbs = path.join(fyodosDirAbs, DOC_BASENAME);
+  const docText = buildHandlerDoc(plan, {
+    appName: appName || path.basename(appRoot),
+    framework,
+    registryRel,
+    bridgeRel,
+    edits: componentEdits,
+    mountSnippet,
+  });
+  fs.writeFileSync(docAbs, docText);
+  const docRel = path.relative(appRoot, docAbs);
+
+  // 2) Nothing can be wired with confidence → leave the doc, explain, never guess.
+  //    BUT when an auto-corrector is available the initial plan being empty is not
+  //    terminal: the loop will re-prompt the AI to FIX each action, so we proceed
+  //    to consent and let the loop decide what ends up wired.
+  const loopEnabled = typeof corrector === 'function' && runTest && testRunner;
+  if (!plan.auto.length && !loopEnabled) {
+    console.error(
+      `\n${tag} · ${dim || ''}preparé el cableado de acciones, pero ninguna de las ` +
+        `${plan.manual.length} acción(es) se puede conectar con confianza.${reset || ''}`,
+    );
+    console.error(
+      `${tag} · revisa qué hace falta y cómo hacerlo a mano en: ${docRel}`,
+    );
+    return { status: 'manual-only', docPath: docAbs, autoCount: 0, manualCount: plan.manual.length, plan };
+  }
+
+  // 3) Second, separate confirmation (after the orb's), referencing the doc.
+  const touchNote = componentEdits.length
+    ? ` Se editarán ${componentEdits.length} archivo(s) TUYO(s) (con marcas reversibles).`
+    : '';
+  const prompt =
+    `\n${tag} · El cableado de acciones necesario para que el agente ejecute funciones ` +
+    `está listo (${plan.auto.length} automática(s), ${plan.manual.length} en revisión).${touchNote}\n` +
+    `${tag} · Puedes revisar exactamente qué cambios se harán en tu código en este archivo:\n` +
+    `         ${docRel}\n` +
+    `${tag} · ¿Aceptas aplicar estos cambios después de revisarlo? [yes/no] `;
+
+  if (!assumeYes && !process.stdin.isTTY) {
+    console.error(prompt.trimEnd());
+    console.error(
+      `${tag} · ${dim || ''}terminal no interactivo: no toco tu código. El documento ` +
+        `queda en ${docRel}. Re-ejecuta con --wire-yes para aplicarlo.${reset || ''}`,
+    );
+    return { status: 'declined-noninteractive', docPath: docAbs, autoCount: plan.auto.length, manualCount: plan.manual.length, plan };
+  }
+
+  const yes = assumeYes || (await askYesNo(prompt));
+  if (!yes) {
+    console.error(
+      `${tag} · ${dim || ''}no modifico tu código. El documento queda en ${docRel} ` +
+        `por si quieres cablearlo a mano o re-ejecutar con --wire-yes.${reset || ''}`,
+    );
+    return { status: 'declined', docPath: docAbs, autoCount: plan.auto.length, manualCount: plan.manual.length, plan };
+  }
+
+  // 4) Baseline: BEFORE touching anything, check whether the app already builds.
+  //    This lets us tell "we broke it" (revert) from "it was already broken"
+  //    (don't revert a good wiring over a pre-existing failure).
+  let baseline = null;
+  if (runTest && testRunner) {
+    console.error(`${tag} · ${dim || ''}comprobando el estado del build ANTES de cablear (baseline)…${reset || ''}`);
+    try {
+      baseline = await testRunner(appRoot, { framework });
+    } catch (err) {
+      baseline = { ok: false, stage: 'runner', output: err && err.message };
+    }
+  }
+
+  const registryAbs = path.join(fyodosDirAbs, `${REGISTRY_BASENAME}${ext}`);
+  const bridgeAbs = path.join(fyodosDirAbs, `${BRIDGE_BASENAME}${ext}`);
+
+  // 4b) AUTO-CORRECTION LOOP. When a corrector (AI re-prompt) is available we run
+  //     the verify→diagnose→correct→retry loop per action. Only actions that PASS
+  //     verification are written; the rest are reverted and reported honestly.
+  if (corrector && runTest && testRunner) {
+    const wiringMap = { ...wiring };
+    const loop = await runAutoCorrectionLoop({
+      appRoot, fyodosDirRel, fyodosDirAbs, manifest, evidence, wiringMap,
+      ts, esm, ext, testRunner, corrector, files, framework, maxAttempts,
+      tag, dim, reset, registryRel, baseline,
+    });
+
+    const finalAuto = loop.ready;
+    const droppedReview = loop.dropped.map((d) => ({
+      ...d,
+      confidence: 'review',
+      reason: `no se pudo cablear automáticamente tras ${d.attempts} intento(s): ${d.reason}`,
+    }));
+    const finalPlan = {
+      auto: finalAuto, review: droppedReview, manual: droppedReview,
+      entries: [...finalAuto, ...droppedReview],
+    };
+    const finalEdits = planComponentEdits(appRoot, finalPlan, { ts });
+    const finalHasBridge = finalAuto.some((e) => e.kind === 'bridge');
+
+    // Rewrite the doc with the REAL verification results (attempts, levels, drops).
+    fs.writeFileSync(docAbs, buildHandlerDoc(finalPlan, {
+      appName: appName || path.basename(appRoot),
+      framework, registryRel, bridgeRel, edits: finalEdits, mountSnippet,
+      verification: loop.attemptsLog,
+    }));
+
+    if (!finalAuto.length) {
+      return {
+        status: 'manual-only', docPath: docAbs, autoCount: 0,
+        manualCount: droppedReview.length, plan: finalPlan,
+        verification: loop.attemptsLog, dropped: loop.dropped, baseline,
+      };
+    }
+
+    const generatedFiles = [registryAbs];
+    let backups = [];
+    try {
+      if (finalHasBridge) {
+        fs.writeFileSync(bridgeAbs, buildBridgeModule({ ts, esm }));
+        generatedFiles.push(bridgeAbs);
+      }
+      fs.writeFileSync(registryAbs, buildRegistryModule(finalPlan, { ts, esm }));
+      ({ backups } = applyComponentEdits(appRoot, finalEdits));
+    } catch (err) {
+      revertAll(backups, generatedFiles);
+      return { status: 'failed', docPath: docAbs, error: err, plan: finalPlan, verification: loop.attemptsLog };
+    }
+
+    // Final combined build (each action passed in isolation; confirm the union).
+    let test;
+    try {
+      test = await testRunner(appRoot, { framework });
+    } catch (err) {
+      test = { ok: false, stage: 'runner', output: err && err.message };
+    }
+    const reg = compileRegressed((baseline && baseline.output) || '', (test && test.output) || '',
+      [...finalEdits.map((e) => e.file), 'handlers.generated', 'bridge']);
+    const combinedRegression = !reg.ok && baseline && baseline.ok;
+    if (combinedRegression && revertOnFailure) {
+      revertAll(backups, generatedFiles);
+      return {
+        status: 'reverted', docPath: docAbs, plan: finalPlan, test,
+        verification: loop.attemptsLog, dropped: loop.dropped, baseline,
+      };
+    }
+    return {
+      status: reg.ok ? 'applied' : 'applied-untested',
+      docPath: docAbs, registryFile: registryAbs, registryRel,
+      bridgeFile: finalHasBridge ? bridgeAbs : null, mountSnippet,
+      autoCount: finalAuto.length, manualCount: droppedReview.length,
+      editedFiles: finalEdits.map((e) => e.file), plan: finalPlan,
+      verification: loop.attemptsLog, dropped: loop.dropped,
+      baseline, test, preexistingFailure: baseline && baseline.ok === false && baseline.stage !== 'skipped-no-deps',
+    };
+  }
+
+  // 5) Apply (single-shot path, no corrector): bridge module (if any) + registry +
+  //    the edits inside the user's own components. Everything idempotent; component
+  //    files are snapshotted so we can revert cleanly if the post-wiring test fails.
+  const generatedFiles = [registryAbs];
+  let backups = [];
+  try {
+    if (hasBridge) {
+      fs.writeFileSync(bridgeAbs, buildBridgeModule({ ts, esm }));
+      generatedFiles.push(bridgeAbs);
+    }
+    fs.writeFileSync(registryAbs, buildRegistryModule(plan, { ts, esm }));
+    if (!fs.readFileSync(registryAbs, 'utf8').includes(GENERATED_MARKER)) {
+      throw new Error('post-write verification failed');
+    }
+    ({ backups } = applyComponentEdits(appRoot, componentEdits));
+  } catch (err) {
+    revertAll(backups, generatedFiles);
+    return { status: 'failed', docPath: docAbs, error: err, plan };
+  }
+
+  const baseResult = {
+    docPath: docAbs,
+    registryFile: registryAbs,
+    registryRel,
+    bridgeFile: hasBridge ? bridgeAbs : null,
+    mountSnippet,
+    autoCount: plan.auto.length,
+    manualCount: plan.manual.length,
+    editedFiles: componentEdits.map((e) => e.file),
+    baseline,
+    plan,
+  };
+
+  // 6) Post-wiring test: make sure WE did not break the app. We only revert when
+  //    the app built BEFORE and fails AFTER (a regression we caused). If it was
+  //    already broken, we keep the wiring and flag it (can't verify via build).
+  if (runTest && testRunner) {
+    if (baseline && baseline.ok === false && baseline.stage !== 'skipped-no-deps') {
+      return { status: 'applied-untested', ...baseResult, test: baseline, preexistingFailure: true };
+    }
+    console.error(`${tag} · ${dim || ''}probando que la app sigue compilando tras el cableado…${reset || ''}`);
+    let test;
+    try {
+      test = await testRunner(appRoot, { framework });
+    } catch (err) {
+      test = { ok: false, stage: 'runner', output: err && err.message };
+    }
+    // Regression we caused: built before, fails now → revert.
+    if (!test.ok && baseline && baseline.ok && revertOnFailure) {
+      revertAll(backups, generatedFiles);
+      return { status: 'reverted', ...baseResult, test };
+    }
+    return { status: test.ok ? 'applied' : 'applied-untested', ...baseResult, test };
+  }
+
+  return { status: 'applied', ...baseResult };
+}
+
+function reportHandlerResult(result, colors = {}) {
+  if (!result) return;
+  const { blue, cyan, dim, reset } = colors;
+  const tag = `${cyan || ''}◉${reset || ''} ${blue || ''}Fiodos${reset || ''}`;
+  switch (result.status) {
+    case 'applied':
+    case 'applied-untested': {
+      const rel = result.registryRel || result.registryFile;
+      console.error(`${tag} · ✓ cableado de handlers aplicado → ${rel} (${result.autoCount} acción(es)).`);
+      if (Array.isArray(result.verification) && result.verification.length) {
+        const ready = result.verification.filter((v) => v.status === 'ready');
+        const corrected = ready.filter((v) => v.attempts > 1).length;
+        const firstTry = ready.length - corrected;
+        const eff = ready.filter((v) => v.level === 'effect').length;
+        console.error(`${tag} · ${dim || ''}verificación: ${ready.length} acción(es) listas (${firstTry} a la primera, ${corrected} tras auto-corrección, ${eff} con efecto real comprobado).${reset || ''}`);
+      }
+      if (result.editedFiles && result.editedFiles.length) {
+        console.error(`${tag} · ${dim || ''}puentes añadidos (reversibles) en: ${result.editedFiles.join(', ')}.${reset || ''}`);
+      }
+      if (Array.isArray(result.dropped) && result.dropped.length) {
+        console.error(`${tag} · ${dim || ''}${result.dropped.length} acción(es) NO se pudieron cablear tras los reintentos (revertidas, ver documento): ${result.dropped.map((d) => d.intent).join(', ')}.${reset || ''}`);
+      } else if (result.manualCount) {
+        console.error(`${tag} · ${dim || ''}${result.manualCount} acción(es) quedaron para revisión (ver el documento).${reset || ''}`);
+      }
+      if (result.test && result.test.ok) {
+        console.error(`${tag} · ✓ test post-cableado OK (${result.test.stage}).`);
+      } else if (result.preexistingFailure) {
+        console.error(`${tag} · ${dim || ''}aviso: tu app YA no compilaba ANTES del cableado (${result.test && result.test.stage}); no es por Fiodos, así que conservo el cableado pero no puedo verificarlo por build.${reset || ''}`);
+      } else if (result.status === 'applied-untested') {
+        console.error(`${tag} · ${dim || ''}aviso: no pude verificar el build (${result.test && result.test.stage}); revísalo.${reset || ''}`);
+      }
+      console.error(`${tag} · ${dim || ''}actívalo pasando registries={fyodosGeneratedRegistries} a <FiodosAgent/> (snippet en el documento).${reset || ''}`);
+      break;
+    }
+    case 'reverted':
+      console.error(`${tag} · ✗ el test post-cableado falló (${result.test && result.test.stage}); REVERTÍ todos los cambios para no dejar tu app rota.`);
+      console.error(`${tag} · ${dim || ''}detalle en el documento; nada quedó modificado en tu código.${reset || ''}`);
+      break;
+    case 'manual-only':
+      console.error(`${tag} · ${dim || ''}cableado documentado; aplícalo a mano siguiendo ${result.docPath}.${reset || ''}`);
+      break;
+    case 'declined':
+    case 'declined-noninteractive':
+      // already reported inline
+      break;
+    case 'failed':
+      console.error(`${tag} · ✗ no se pudo escribir el registro de handlers: ${result.error && result.error.message}`);
+      break;
+    case 'no-actions':
+    case 'skipped':
+    default:
+      break;
+  }
+}
+
+module.exports = {
+  wireHandlers,
+  reportHandlerResult,
+  // exported for tests
+  prepareHandlerPlan,
+  buildHandlerDoc,
+  buildRegistryModule,
+  buildBridgeModule,
+  planComponentEdits,
+  applyComponentEdits,
+  stripFiodosBlocks,
+  revertAll,
+  runAutoCorrectionLoop,
+  writeIsolated,
+  planOneAction,
+  pickRelevantFiles,
+  parseParamList,
+  findExportedFunction,
+  findStoreMethod,
+  mapParams,
+};