@fiodos/cli 0.1.25 → 0.1.26

package/src/shopifyTheme.js

@@ -0,0 +1,300 @@
+/**
+ * Shopify theme support — the closed-platform branch of the analyze pipeline.
+ *
+ * A Shopify store's "codebase" is its Liquid theme (GitHub-synced via
+ * Shopify's native integration), and its live catalog is PUBLIC JSON
+ * (/collections.json, /products.json). This module:
+ *
+ *   1. detects a theme repo (layout/theme.liquid + templates/),
+ *   2. fetches a public storefront snapshot and exposes it as synthetic FILE
+ *      blocks (_fyodos/storefront/*.json) so the analyzer can personalize
+ *      routes/bubbles/examples to the REAL catalog — and so evidence
+ *      verification has concrete files to point at,
+ *   3. injects the embed snippet into layout/theme.liquid (idempotent
+ *      FYODOS:ORB markers, same pattern as every other wire step), including
+ *      a Liquid-rendered screen context so the agent knows the visible
+ *      product's variant id (what add_to_cart needs).
+ *
+ * No wiring/session/screen blocks apply here: commerce actions carry
+ * declarative `execution` templates resolved by buildApiActionRegistries in
+ * the embed at runtime ({baseUrl} → the store's own origin).
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/** CDN URL of the self-contained embed bundle (global `Fiodos`). Keep in sync
+ *  with dashboard/src/lib/shopifyInstall.ts. */
+const FIODOS_EMBED_CDN_URL =
+  'https://unpkg.com/@fiodos/web-core@latest/dist/embed/fiodos-embed.js';
+
+const ORB_START = '<!-- FYODOS:ORB:START (Fiodos agent — safe to remove) -->';
+const ORB_END = '<!-- FYODOS:ORB:END -->';
+
+/** Repo-relative folder of the synthetic storefront snapshot files. */
+const SNAPSHOT_DIR = '_fyodos/storefront';
+
+/** A Shopify theme repo is unmistakable: layout/theme.liquid is the layout
+ *  every Online Store 2.0 theme must have, plus templates/ or sections/. */
+function isShopifyThemeRoot(appRoot) {
+  const has = (rel) => {
+    try {
+      return fs.existsSync(path.join(appRoot, rel));
+    } catch {
+      return false;
+    }
+  };
+  return (
+    has('layout/theme.liquid') &&
+    (has('templates') || has('sections') || has('config/settings_schema.json'))
+  );
+}
+
+/** Store name from the theme's settings_schema.json (theme_info), best-effort. */
+function readThemeMeta(appRoot) {
+  const meta = {};
+  try {
+    const raw = fs.readFileSync(path.join(appRoot, 'config', 'settings_schema.json'), 'utf8');
+    const schema = JSON.parse(raw);
+    const info = Array.isArray(schema)
+      ? schema.find((s) => s && (s.name === 'theme_info' || s.theme_name))
+      : null;
+    if (info && info.theme_name) meta.themeName = String(info.theme_name);
+  } catch {
+    /* not required */
+  }
+  return meta;
+}
+
+function normalizeStoreDomain(raw) {
+  const s = String(raw || '').trim();
+  if (!s) return '';
+  return s
+    .replace(/^https?:\/\//i, '')
+    .replace(/\/.*$/, '')
+    .toLowerCase();
+}
+
+async function fetchJson(url, { timeoutMs = 8000 } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetch(url, {
+      signal: controller.signal,
+      headers: { accept: 'application/json' },
+    });
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    return await res.json();
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+function stripHtml(html) {
+  return String(html || '')
+    .replace(/<[^>]*>/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/** The universal storefront surface, written into the snapshot so evidence
+ *  ("_fyodos/storefront/storefront.json", symbol "shopify_storefront") is
+ *  backed by a real file among the ones sent to the model. */
+function universalSurfaceDoc(storeDomain) {
+  return {
+    shopify_storefront: true,
+    store: storeDomain || '(unknown — no --store domain provided)',
+    universalRoutes: ['/', '/collections/all', '/search', '/cart'],
+    universalActions: [
+      { intent: 'search_products', handler: 'shopifySearchProducts', api: '{baseUrl}/search/suggest.json' },
+      { intent: 'add_to_cart', handler: 'shopifyAddToCart', api: '{baseUrl}/cart/add.js' },
+      { intent: 'get_cart', handler: 'shopifyGetCart', api: '{baseUrl}/cart.js' },
+      { intent: 'update_cart_item', handler: 'shopifyUpdateCartItem', api: '{baseUrl}/cart/change.js' },
+      { intent: 'go_checkout', kind: 'link', navTarget: '/checkout' },
+    ],
+    note:
+      'Universal Shopify storefront surface — present on every Shopify store ' +
+      'regardless of theme. Ajax Cart API + Predictive Search, anonymous access.',
+  };
+}
+
+/**
+ * Fetch the public storefront snapshot for a store and return it as synthetic
+ * collection entries ({ rel, content, tier, chars }) ready to append to the
+ * collector's `included` list.
+ *
+ * Fail-open: any fetch error still yields storefront.json (the universal
+ * surface), so the analysis and its evidence contract always work — the
+ * manifest just loses catalog personalization when the store is unreachable.
+ */
+async function fetchStorefrontSnapshot(storeRaw, { log = () => {} } = {}) {
+  const store = normalizeStoreDomain(storeRaw);
+  const files = [];
+  const pushFile = (name, data) => {
+    const content = JSON.stringify(data, null, 2);
+    files.push({ rel: `${SNAPSHOT_DIR}/${name}`, content, tier: 0, chars: content.length });
+  };
+
+  const warnings = [];
+  let collections = [];
+  let products = [];
+  if (store) {
+    const base = `https://${store}`;
+    try {
+      const data = await fetchJson(`${base}/collections.json?limit=250`);
+      collections = (data.collections || []).map((c) => ({
+        handle: c.handle,
+        title: c.title,
+        description: stripHtml(c.body_html).slice(0, 200),
+        productsCount: c.products_count,
+        updatedAt: c.updated_at,
+      }));
+    } catch (e) {
+      warnings.push(`collections.json: ${e.message}`);
+    }
+    try {
+      const data = await fetchJson(`${base}/products.json?limit=50`);
+      products = (data.products || []).map((p) => ({
+        handle: p.handle,
+        title: p.title,
+        productType: p.product_type,
+        vendor: p.vendor,
+        tags: p.tags,
+        description: stripHtml(p.body_html).slice(0, 200),
+        priceRange: (() => {
+          const prices = (p.variants || []).map((v) => Number(v.price)).filter((n) => !Number.isNaN(n));
+          if (!prices.length) return undefined;
+          return { min: Math.min(...prices), max: Math.max(...prices) };
+        })(),
+        variantSample: (p.variants || []).slice(0, 3).map((v) => ({ id: v.id, title: v.title, price: v.price })),
+      }));
+    } catch (e) {
+      warnings.push(`products.json: ${e.message}`);
+    }
+  } else {
+    warnings.push('no store domain provided (--store) — catalog personalization limited to theme files');
+  }
+
+  pushFile('storefront.json', {
+    ...universalSurfaceDoc(store),
+    fetchedAt: new Date().toISOString(),
+    collectionsCount: collections.length,
+    productSampleCount: products.length,
+    ...(warnings.length ? { warnings } : {}),
+  });
+  if (collections.length) pushFile('collections.json', { collections });
+  if (products.length) pushFile('products.json', { products });
+
+  for (const w of warnings) log(`[shopify] snapshot warning: ${w}`);
+  log(
+    `[shopify] storefront snapshot: ${collections.length} collections, ` +
+    `${products.length} product sample${store ? ` (${store})` : ''}`,
+  );
+  return { files, store, collections, products, warnings };
+}
+
+/**
+ * The theme.liquid block: loads the embed, fetches the published manifest and
+ * mounts the orb with API-wired registries. Mirrors the dashboard's
+ * buildShopifySnippet, plus a Liquid-rendered PRODUCT screen context so the
+ * agent knows the visible variant id (what add_to_cart needs by voice).
+ */
+function buildShopifySnippet({ apiKey, apiUrl }) {
+  const key = apiKey || '<your-api-key>';
+  const url = String(apiUrl || '').replace(/\/$/, '');
+  return [
+    ORB_START,
+    `<script src="${FIODOS_EMBED_CDN_URL}" defer></script>`,
+    '<script>',
+    "  {% if template contains 'product' and product %}",
+    '  {% capture fyodos_screen_text %}The customer is viewing the product page of: {{ product.title }} (price {{ product.price | money | strip_html }}). Add-to-cart variantId: {{ product.selected_or_first_available_variant.id }}.{% endcapture %}',
+    "  window.__fyodosScreen = { kind: 'product', text: {{ fyodos_screen_text | json }} };",
+    '  {% endif %}',
+    "  window.addEventListener('DOMContentLoaded', function () {",
+    `    var FYODOS_API_KEY = '${key}';`,
+    `    var FYODOS_API_URL = '${url}';`,
+    "    fetch(FYODOS_API_URL + '/v1/client/manifest', { headers: { 'x-api-key': FYODOS_API_KEY } })",
+    '      .then(function (r) { return r.json(); })',
+    '      .then(function (data) {',
+    '        if (!data || !data.manifest || !window.Fiodos) return;',
+    '        var agent = Fiodos.createFiodosAgent({',
+    '          baseUrl: FYODOS_API_URL,',
+    '          apiKey: FYODOS_API_KEY,',
+    '          manifest: data.manifest,',
+    '          registries: Fiodos.buildApiActionRegistries(data.manifest, {',
+    '            baseUrl: window.location.origin,',
+    '          }),',
+    "          localeDetection: 'document',",
+    '        });',
+    '        if (window.__fyodosScreen) agent.setScreenContext(window.__fyodosScreen);',
+    '      });',
+    '  });',
+    '</script>',
+    ORB_END,
+  ].join('\n');
+}
+
+function escapeRe(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * Inject (or refresh) the snippet in layout/theme.liquid, right before
+ * </body>. Idempotent via the FYODOS:ORB markers: an existing block is
+ * replaced in place, so re-running the CLI updates the snippet instead of
+ * duplicating it. Returns { status: 'added'|'already'|'skipped'|'failed',
+ * file, reason? }.
+ */
+function wireShopifyTheme(appRoot, { apiKey, apiUrl, noWire = false } = {}) {
+  const relFile = path.join('layout', 'theme.liquid');
+  const file = path.join(appRoot, relFile);
+  if (!fs.existsSync(file)) {
+    return { status: 'failed', file: relFile, reason: 'layout/theme.liquid not found' };
+  }
+  const snippet = buildShopifySnippet({ apiKey, apiUrl });
+  const source = fs.readFileSync(file, 'utf8');
+
+  const markerRe = new RegExp(`${escapeRe(ORB_START)}[\\s\\S]*?${escapeRe(ORB_END)}`);
+  if (markerRe.test(source)) {
+    const existing = source.match(markerRe)[0];
+    if (existing === snippet) return { status: 'already', file: relFile };
+    if (noWire) return { status: 'skipped', file: relFile, reason: '--no-wire' };
+    fs.writeFileSync(file, source.replace(markerRe, snippet));
+    return { status: 'added', file: relFile, refreshed: true };
+  }
+
+  if (noWire) return { status: 'skipped', file: relFile, reason: '--no-wire' };
+  const bodyClose = source.lastIndexOf('</body>');
+  const next = bodyClose === -1
+    ? `${source}\n${snippet}\n`
+    : `${source.slice(0, bodyClose)}${snippet}\n  ${source.slice(bodyClose)}`;
+  fs.writeFileSync(file, next);
+  return { status: 'added', file: relFile };
+}
+
+function reportShopifyWire(result, colors = {}, { quiet = false } = {}) {
+  const { blue = '', cyan = '', reset = '' } = colors;
+  const say = (line) => console.error(`${cyan}◉${reset} ${blue}Fiodos${reset} · ${line}`);
+  if (result.status === 'added') {
+    say(`orb embedded in ${result.file}${result.refreshed ? ' (snippet refreshed)' : ''} — commit & push to deploy via Shopify's GitHub sync`);
+  } else if (result.status === 'already') {
+    say(`orb already embedded in ${result.file}`);
+  } else if (result.status === 'failed') {
+    say(`could not embed the orb: ${result.reason}`);
+  } else if (!quiet) {
+    say(`orb embed skipped (${result.reason || result.status})`);
+  }
+}
+
+module.exports = {
+  isShopifyThemeRoot,
+  readThemeMeta,
+  fetchStorefrontSnapshot,
+  buildShopifySnippet,
+  wireShopifyTheme,
+  reportShopifyWire,
+  normalizeStoreDomain,
+  FIODOS_EMBED_CDN_URL,
+  SNAPSHOT_DIR,
+};

package/src/verify.js

@@ -31,6 +31,40 @@ function fileHasIdentifier(content, identifier) {
   return re.test(content);
 }
 
+const EXECUTION_METHODS = new Set(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']);
+
+/**
+ * Structural check of a declarative `execution` block (closed platforms).
+ * Mirrors @fiodos/core validateExecution: http kind, known method, non-empty
+ * url, and every {placeholder} resolvable (baseUrl or a declared parameter).
+ * Returns a problem string, or null when the block is sound.
+ */
+function validateExecutionShape(action) {
+  const exec = action.execution;
+  if (!exec || typeof exec !== 'object') return 'missing execution object';
+  if (exec.kind !== 'http') return `kind '${exec.kind}' is not 'http'`;
+  if (!EXECUTION_METHODS.has(exec.method)) return `invalid method '${exec.method}'`;
+  if (typeof exec.url !== 'string' || !exec.url.trim()) return 'empty url';
+  if (!String(action.handler || '').trim()) return 'function action has no handler name';
+  const declared = new Set(Object.keys(action.parameters || {}));
+  const placeholders = new Set();
+  const collect = (value) => {
+    if (typeof value === 'string') {
+      for (const m of value.matchAll(/\{([A-Za-z_][A-Za-z0-9_]*)\}/g)) placeholders.add(m[1]);
+    } else if (value && typeof value === 'object') {
+      for (const v of Object.values(value)) collect(v);
+    }
+  };
+  collect(exec.url);
+  collect(exec.body);
+  for (const name of placeholders) {
+    if (name !== 'baseUrl' && !declared.has(name)) {
+      return `execution references undeclared parameter '{${name}}'`;
+    }
+  }
+  return null;
+}
+
 /**
  * Upper bound on examples kept per route/action. The enriched prompt asks the
  * model for 5-8 varied phrasings; this cap protects the cacheable system prompt
@@ -160,12 +194,48 @@ function verifyManifest(manifest, evidence, sentFiles, staticRoutes, opts = {})
     });
   }
 
+  const isShopify = opts.platform === 'shopify';
   const actions = [];
   for (const action of manifest.actions || []) {
     const ev = evidence.actions?.[action.intent] || {};
     const evFile = String(ev.file || '').replace(/\\/g, '/').replace(/^\.\//, '');
     const content = byRel.get(evFile);
 
+    // Shopify (closed platform): the ground truth for API actions is the
+    // platform itself, not app code. An action carrying a declarative
+    // `execution` block is verified STRUCTURALLY (http kind + method + url and
+    // every {placeholder} declared) — a synthetic handler name can never match
+    // an identifier in a .liquid file, and requiring it would drop the whole
+    // universal commerce set. The universal "/checkout" link is likewise
+    // platform-guaranteed (themes rarely hardcode that href).
+    if (isShopify && action.kind !== 'link' && action.execution) {
+      const problem = validateExecutionShape(action);
+      if (problem) {
+        provenance.actions.push({
+          intent: action.intent, included: false,
+          reason: `invalid execution block — ${problem} — DROPPED`,
+        });
+        continue;
+      }
+      actions.push(action);
+      provenance.actions.push({
+        intent: action.intent, included: true,
+        verification: 'declarative execution (Shopify storefront API — platform-guaranteed)',
+        evidence: ev,
+      });
+      continue;
+    }
+    if (isShopify && action.kind === 'link' && String(action.navTarget || '').trim() === '/checkout') {
+      action.handler = '';
+      actions.push(action);
+      provenance.actions.push({
+        intent: action.intent, included: true,
+        verification: 'universal Shopify checkout link (platform-guaranteed)',
+        evidence: ev,
+      });
+      continue;
+    }
+
     if (!content) {
       provenance.actions.push({
         intent: action.intent, included: false,
@@ -254,6 +324,59 @@ function verifyManifest(manifest, evidence, sentFiles, staticRoutes, opts = {})
     else delete route.actionIntents;
   }
 
+  // Escort target: keep each action's showcaseRoute fail-open. It must point
+  // at a SURVIVING, navigable route intent (never BACK); anything else —
+  // hallucinated ids, dropped routes, non-strings — is silently removed so a
+  // wrong escort can never ship (a wrong screen is worse than no escort).
+  const navigableRouteIntents = new Set(
+    dedupedRoutes.filter((r) => r.route !== 'BACK').map((r) => r.intent),
+  );
+  for (const action of dedupedActions) {
+    if (action.showcaseRoute === undefined) continue;
+    if (typeof action.showcaseRoute !== 'string' || !navigableRouteIntents.has(action.showcaseRoute)) {
+      provenance.notes.push(
+        `action '${action.intent}': showcaseRoute '${String(action.showcaseRoute)}' does not match a navigable route — removed`,
+      );
+      delete action.showcaseRoute;
+    }
+  }
+
+  // Audience map (fail-open): only the two known values survive; anything else
+  // is dropped so an invalid claim can never HIDE a capability from a user.
+  // 'public' is the implicit default, so it is normalized away (absent = public).
+  // requiredCapabilities become a deduped list of short snake_case names; a
+  // malformed list is dropped entirely (a bogus capability must never hide an
+  // action behind a flag no session will ever report).
+  for (const item of [...dedupedRoutes, ...dedupedActions]) {
+    if (item.audience !== undefined && item.audience !== 'authenticated') {
+      if (item.audience !== 'public') {
+        provenance.notes.push(
+          `'${item.intent}': audience '${String(item.audience)}' is not public/authenticated — removed`,
+        );
+      }
+      delete item.audience;
+    }
+  }
+  for (const action of dedupedActions) {
+    if (action.requiredCapabilities === undefined) continue;
+    const caps = Array.isArray(action.requiredCapabilities)
+      ? [
+          ...new Set(
+            action.requiredCapabilities
+              .filter((c) => typeof c === 'string' && /^[a-z][a-z0-9_]{0,63}$/.test(c.trim()))
+              .map((c) => c.trim()),
+          ),
+        ].slice(0, 8)
+      : [];
+    if (caps.length > 0) action.requiredCapabilities = caps;
+    else {
+      provenance.notes.push(
+        `action '${action.intent}': requiredCapabilities had no valid snake_case names — removed`,
+      );
+      delete action.requiredCapabilities;
+    }
+  }
+
   // Examples hygiene (fail-open): trim, dedupe and cap the enriched phrasings on
   // every surviving route and action. Never drops the item; falls back to the
   // label so the core validator's non-empty-examples rule still holds.
@@ -299,4 +422,4 @@ function verifyManifest(manifest, evidence, sentFiles, staticRoutes, opts = {})
   };
 }
 
-module.exports = { verifyManifest, normalizeHref, sanitizeExamples, MAX_EXAMPLES };
+module.exports = { verifyManifest, normalizeHref, sanitizeExamples, validateExecutionShape, MAX_EXAMPLES };

package/src/wireHandlers.js

@@ -467,13 +467,79 @@ function buildAiEntry({ appRoot, fyodosDirRel, base, aiW, manifestParams }) {
   };
 }
 
+/**
+ * MECHANICAL ANCHOR RESCUE — the fix for the dominant wiring failure class
+ * ("the insertion point in '<file>' is ambiguous / not found").
+ *
+ * The AI's anchor only needs to locate the RIGHT COMPONENT SCOPE: the actual
+ * insertion goes before the nearest JSX `return` (see insertRegisterBlock), so
+ * when the AI picks a line that appears several times in a big file we do not
+ * have to give up. We derive a deterministic anchor ourselves: the line where
+ * one of the identifiers the `invoke` expression CALLS/READS is DECLARED
+ * (`const [x, setX] = useState(...)`, `function foo(`, `const foo =`, a class
+ * field, …). Declarations are unique per scope in real code, and anchoring on
+ * the declaration guarantees the registration lands in the scope where the
+ * symbol is visible. Correctness is still gated by the same compile-regression
+ * + effect-probe verification as every other wiring — this only replaces the
+ * "reject" with a better, mechanical candidate.
+ */
+function deriveBridgeAnchor(content, invoke) {
+  const src = stripLiterals(String(invoke || ''));
+  // Identifiers the invoke CALLS first (most specific), then everything it reads.
+  const ordered = [];
+  const pushId = (id) => {
+    if (!id || id === 'args' || id === 'this') return;
+    if (JS_KEYWORDS.has(id) || SAFE_GLOBALS.has(id)) return;
+    if (!ordered.includes(id)) ordered.push(id);
+  };
+  let m;
+  const callRe = /(?:^|[^.\w$])([A-Za-z_$][\w$]*)\s*\(/g;
+  while ((m = callRe.exec(src))) pushId(m[1]);
+  for (const id of freeIdentifiers(invoke)) pushId(id);
+
+  for (const id of ordered) {
+    // Full LINES that look like a declaration of `id` in the file.
+    const lineRe = new RegExp(
+      `^[ \\t]*(?:export\\s+)?(?:const|let|var|function|async\\s+function|private|public|protected|readonly)\\b[^\\n]*(?:^|[^.\\w$])${esc(id)}(?![\\w$])[^\\n]*$`,
+      'gm',
+    );
+    const decls = [];
+    while ((m = lineRe.exec(content))) decls.push(m[0]);
+    // Exactly ONE declaration line, and that line must be unique as a substring
+    // (so indexOf-based insertion is deterministic and idempotent).
+    if (decls.length === 1 && countOccurrences(content, decls[0]) === 1) {
+      return decls[0];
+    }
+  }
+  return null;
+}
+
+/**
+ * True when an anchor that appears several times is HARMLESS: every occurrence
+ * resolves to the same actual insertion point (the nearest JSX `return`), so
+ * the ambiguity cannot change where the registration lands.
+ */
+function ambiguousAnchorSameInsertion(content, anchor) {
+  const points = new Set();
+  let idx = content.indexOf(anchor);
+  while (idx !== -1) {
+    points.add(nearestJsxReturn(content, idx));
+    if (points.size > 1) return false;
+    idx = content.indexOf(anchor, idx + anchor.length);
+  }
+  // A single resolved point that exists (-1 = no JSX return found → not safe).
+  return points.size === 1 && !points.has(-1);
+}
+
 /**
  * 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),
+ *   · the component file exists and the anchor resolves to ONE unambiguous
+ *     insertion point — when the AI's anchor is missing/ambiguous, a mechanical
+ *     anchor is derived from the declaration of the invoked symbol (see
+ *     deriveBridgeAnchor) instead of giving up,
  *   · 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
@@ -483,7 +549,7 @@ function buildAiEntry({ appRoot, fyodosDirRel, base, aiW, manifestParams }) {
 function buildAiBridgeEntry({ appRoot, fyodosDirRel, base, aiW }) {
   const b = aiW.bridge || {};
   const file = normRel(b.file);
-  const anchor = String(b.anchor || '').trim();
+  let anchor = String(b.anchor || '').trim();
   const invoke = String(b.invoke || '').trim();
   const why = aiW.bridgeReason ? ` (${aiW.bridgeReason})` : '';
 
@@ -491,11 +557,29 @@ function buildAiBridgeEntry({ appRoot, fyodosDirRel, base, aiW }) {
   const content = readFileSafe(appRoot, file);
   if (content == null) return { reason: `could not read the component '${file}' to apply the bridge` };
   if (!invoke) return { reason: `the AI did not provide the bridge 'invoke' expression for '${file}'` };
-  if (!anchor) return { reason: `the AI did not provide an insertion anchor in '${file}'` };
 
-  const occ = countOccurrences(content, anchor);
-  if (occ === 0) return { reason: `no safe insertion point was found in '${file}' — wire this action manually` };
-  if (occ > 1) return { reason: `the insertion point in '${file}' is ambiguous — wire this action manually` };
+  // Anchor resolution ladder: exact-unique AI anchor → harmless-ambiguous AI
+  // anchor → mechanically derived declaration anchor → review. The old behavior
+  // (reject on 0/>1 occurrences) left real, wireable actions "manual" whenever
+  // the AI picked a repeated line in a big file.
+  let anchorDerived = false;
+  const occ = anchor ? countOccurrences(content, anchor) : 0;
+  if (occ !== 1) {
+    const scope = b.scope === 'class-field' ? 'class-field' : 'statement';
+    if (occ > 1 && scope === 'statement' && ambiguousAnchorSameInsertion(content, anchor)) {
+      // Keep the AI anchor: every occurrence lands on the same insertion point.
+    } else {
+      const derived = deriveBridgeAnchor(content, invoke);
+      if (derived) {
+        anchor = derived;
+        anchorDerived = true;
+      } else if (!anchor || occ === 0) {
+        return { reason: `no safe insertion point was found in '${file}' — wire this action manually` };
+      } else {
+        return { reason: `the insertion point in '${file}' is ambiguous — wire this action manually` };
+      }
+    }
+  }
 
   // requiredSymbols must really exist.
   const required = Array.isArray(aiW.requiredSymbols) ? aiW.requiredSymbols : [];
@@ -1854,6 +1938,8 @@ module.exports = {
   findExportedFunction,
   findStoreMethod,
   mapParams,
+  deriveBridgeAnchor,
+  ambiguousAnchorSameInsertion,
   // shared with wireSession (same verification + injection machinery)
   fileHasSymbol,
   freeIdentifiers,