pi-fovea 0.2.0 → 0.3.0

package/README.md

@@ -134,6 +134,19 @@ File-convention routers never write a route string at all — those anchors are
 
 **Known blind spots** (deliberate, logged in `src/core/anchors.ts`): Rust proc-macro attribute routers (actix `#[get("/x")]`, rocket) — ast-grep patterns can't parameterize attribute paths; frameworks with constructor-assigned prefixes (Flask Blueprint, FastAPI `APIRouter(prefix=…)`, chi `Mount`, Express `Router` mounts) — variable binding tracking is out of band; `scope`/`namespace` nesting in Phoenix/Rails/Django `include()` — prefixes across blocks aren't composed; tRPC/GraphQL/gRPC — no path token exists to anchor on.
 
+### Tier 3: discovery mode
+
+Unknown shapes self-heal. During the literal pass fovea harvests a per-repo histogram of *call-shape signatures* — `(lang · shape · callee · argIdx)` with a path-precision — and promotes statistically significant unknown ones into **implicit rules**: exact-arity ast-grep patterns, synthesized automatically, wired into the graph at **half hub gravity** with a `△` sigil in `fovea anchors` output. Sync reports discovered churn but never lets an unconfirmed hypothesis escalate to red; a hub upgrades to first-class the moment any site matches a non-implicit rule.
+
+Promotion needs: ≥4 path-carrying sites, spread over ≥2 files, and a Jeffreys-smoothed posterior `p̂ = (pathN + .5) / (n + 1) ≥ 0.55`. Measured against 8 cloned projects, junk bands land below p̂≈0.27 and real shapes above p̂≈0.75 — the line is not tuned to the corpus, it sits mid-cliff. Frameworks already known to the static pack are never re-promoted.
+
+```sh
+fovea anchors <root> --discovered   # only the △ hypothesis hubs
+fovea rules <root>                  # promoted rules + evidence, ready to paste into .fovea/rules.json
+fovea rules <root> --sigs           # every path-touching signature, by precision (audit the corpus)
+fovea rules <root> --adopt          # write them into the repo's rule pack explicitly
+```
+
 Drop `.fovea/rules.json` in a repo to extend anchor detection beyond the built-ins:
 
 ```json

package/cli.ts

@@ -6,12 +6,16 @@
 //   fovea dwell [root] [factor] [budget]     (deepens the in-process focus)
 //   fovea impact [root] [--files a,b] [--symbols x,y] [--base ref] [--no-uncommitted] [budget]
 //   fovea anchors [root] [filter]             (every feature anchor, sorted)
+//   fovea rules [root]                        (tier-3 discovered shape hypotheses)
 //
 // The CLI is stateless across invocations (dwell needs a prior focus in the
 // same process — combine ops inside pi, where sessions persist); stdout is
 // the rendered field, nothing else, so it composes with head/grep/$().
 
+import { statSync } from "node:fs";
 import { ensureState, sketch, focus, dwell, impact } from "./src/core/ops.js";
+import { aggregateFiles, posterior, promote } from "./src/core/discover.js";
+import { DEFAULT_PACK } from "./src/core/anchors.js";
 
 const [, , cmd = "status", ...argv] = process.argv;
 
@@ -37,9 +41,15 @@ const numAt = (i: number): number | undefined => {
   return Number.isFinite(n) && n > 0 ? n : undefined;
 };
 // Root is the first positional that names a path; everything else is arg data.
+// Existing directories count as paths even when bare ("next", "kernel").
 const rootAt = (i: number): string => {
   const p = pos[i];
-  return p !== undefined && (p.includes("/") || p === ".") ? p : ".";
+  if (p === undefined) return ".";
+  if (p.includes("/") || p === ".") return p;
+  try {
+    if (statSync(p).isDirectory()) return p;
+  } catch { /* not a path */ }
+  return ".";
 };
 
 try {
@@ -76,10 +86,49 @@ try {
     const root = rootAt(0);
     const filter = pos.find((p) => p !== root);
     const rows = ensureState(root).graph.anchors
-      .map((a) => `${a.kind}\t${a.id}\t${a.file}:${a.line}`)
-      .filter((r) => !filter || r.includes(filter))
+      .map((a) => `${a.implicit ? "△" : " "}\t${a.kind}\t${a.id}\t${a.file}:${a.line}`)
+      .filter((r) => (!filter || r.includes(filter)) && (!flags.has("discovered") || r.startsWith("△")))
       .sort();
     out = rows.join("\n");
+  } else if (cmd === "rules") {
+    const root = rootAt(0);
+    const st = ensureState(root);
+    const sigs = aggregateFiles(Object.fromEntries(Object.entries(st.facts).map(([k, v]) => [k, v.sigs])));
+    const promoted = promote(sigs, DEFAULT_PACK);
+    if (flags.has("adopt") && promoted.length) {
+      const { mkdirSync, writeFileSync, readFileSync } = await import("node:fs");
+      const { join } = await import("node:path");
+      mkdirSync(join(root, ".fovea"), { recursive: true });
+      const rulesFile = join(root, ".fovea", "rules.json");
+      let existing = { rules: [] as unknown[] };
+      try { existing = JSON.parse(readFileSync(rulesFile, "utf8")); } catch { /* new */ }
+      const stamp = promoted.map((r) => ({
+        id: r.id.slice("implicit:".length),
+        langs: r.langs,
+        pattern: r.patterns[0],
+        methods: r.methods,
+        kind: r.kind,
+      }));
+      existing.rules = [...existing.rules, ...stamp];
+      writeFileSync(rulesFile, JSON.stringify(existing, null, 2) + "\n");
+      out = `wrote ${stamp.length} discovered rule(s) to .fovea/rules.json`;
+    } else if (flags.has("sigs")) {
+      out = sigs.filter((s) => s.pathN > 0)
+        .sort((a, b) => posterior(b.pathN, b.n) - posterior(a.pathN, a.n))
+        .map((s) => `${posterior(s.pathN, s.n).toFixed(2)}  ${s.pathN}/${s.n} across ${s.files} files  ${s.key}`)
+        .join("\n");
+    } else if (!promoted.length) {
+      out = "(no unknown shape passes the promotion floor — tier-1/2 coverage is doing fine)";
+    } else {
+      out = promoted.map((r) => JSON.stringify({
+        id: r.id.slice("implicit:".length),
+        langs: r.langs,
+        pattern: r.patterns[0],
+        methods: r.methods.replace(/\(\?i\)/, ""),
+        kind: r.kind,
+        _evidence: `p̂=${r.evidence.posterior.toFixed(2)} (${r.evidence.pathN}/${r.evidence.n} sites, ${r.evidence.files} files)`,
+      })).join("\n");
+    }
   } else {
     console.error(`unknown command: ${cmd}`);
     process.exit(2);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-fovea",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Token-budgeted repo mapping for agent sessions: foveated heat diffusion over a cross-language code graph, with progressive disclosure.",
   "type": "module",
   "license": "MIT",

package/src/core/anchors.ts

@@ -26,7 +26,8 @@ import type { Anchor } from "./types.js";
 export interface AnchorRule {
   id: string;
   langs: string[];
-  pattern: string;
+  /** Single ast-grep pattern; tier-3 synthesized rules use `patterns` instead. */
+  pattern?: string;
   methods: string; // regex tested against the captured method metavar
   kind: string;
   /**
@@ -39,6 +40,10 @@ export interface AnchorRule {
   verbFrom?: string;
   /** Idiom writes paths mount-relative (Django `path("users/")`): root them. */
   mountRoot?: boolean;
+  /** Synthesized tier-3 rules ship as variant lists (exact arity + trailing $$$H). */
+  patterns?: string[];
+  /** Discovered rules: half hub gravity until a real join upgrades them. */
+  implicit?: boolean;
 }
 
 const HTTP_VERB_RE = /^(?i:get|post|put|delete|patch|head|options)$/;
@@ -59,12 +64,19 @@ const PLACEHOLDER_ONLY = /^(:[A-Za-z_]\w*|\{[A-Za-z_]\w*\}|\[[A-Za-z_]\w*\])$/;
 // Method names that are mounts, not verbs: Django urls, Rails match/root,
 // Spring's umbrella RequestMapping. They anchor as ANY so the hub exists
 // without pretending a verb was declared.
-const NON_VERB_METHODS = new Set(["PATH", "RE_PATH", "URL", "MATCH", "ROOT", "REQUESTMAPPING", "REDIRECT", "RESOURCES"]);
+// Method names that mount a target rather than declare a verb. fetch(url)
+// and redirect targets both resolve to GET; Django urlconfs and Rails mounts
+// accept any verb.
+const METHOD_ALIASES: Record<string, string> = {
+  PATH: "ANY", RE_PATH: "ANY", URL: "ANY", MATCH: "ANY", ROOT: "ANY",
+  REQUESTMAPPING: "ANY", RESOURCES: "ANY", FORWARD: "ANY",
+  FETCH: "GET", REDIRECT: "GET", RESPONDREDIRECT: "GET", REDIRECT_TO: "GET",
+};
 
 const deriveVerb = (method: string): string => {
   let up = method.toUpperCase();
   if (up.endsWith("MAPPING")) up = up.slice(0, -"MAPPING".length); // Spring GetMapping → GET
-  return NON_VERB_METHODS.has(up) ? "ANY" : up;
+  return METHOD_ALIASES[up] ?? up;
 };
 
 export const DEFAULT_PACK: AnchorRule[] = [
@@ -199,6 +211,24 @@ export const DEFAULT_PACK: AnchorRule[] = [
     methods: "^add_url_rule$",
     kind: "route",
   },
+  {
+    // Client fetch with no receiver: fetch("/api/x"). Precision-audited by
+    // discovery (~93% path precision in the next.js clone corpus).
+    id: "fetch-bare",
+    langs: ["TypeScript", "Tsx", "JavaScript"],
+    pattern: "$M($P, $$$H)",  // trailing $$$H absorbs the options bag; zero-arg tail matches fetch("/x") too
+    methods: "^fetch$",
+    kind: "route",
+  },
+  {
+    // Response-side route linkage: ktor respondRedirect("/myfiles") references
+    // an existing route without declaring it. Discovery found it at p̂≈0.81.
+    id: "ktor-respond-redirect",
+    langs: ["Kotlin"],
+    pattern: "$R.$M($P, $$$H)",
+    methods: "^respondRedirect$",
+    kind: "route",
+  },
   {
     id: "rust-router-chain",
     langs: ["Rust"],
@@ -238,7 +268,8 @@ export const extractAnchors = (
           if (p !== undefined && !prefixes.has(pm.file)) prefixes.set(pm.file, unquote(p));
         }
       }
-      for (const m of patternRun(rule.pattern, lang, langFiles, cwd)) {
+      const matchSets = patternRunAll(rule.patterns ?? [rule.pattern!], lang, langFiles, cwd);
+      for (const m of matchSets) {
         const method = m.single.M;
         const pathLike = m.single.P;
         if (!method || !pathLike || !methodRe.test(method)) continue;
@@ -273,6 +304,7 @@ export const extractAnchors = (
           nodeId: enclosing ?? `file:${m.file}`,
           file: m.file,
           line: m.line,
+          ...(rule.implicit ? { implicit: true } : {}),
         });
       }
     }

package/src/core/build.ts

@@ -8,10 +8,11 @@ import { existsSync, readFileSync, readdirSync, writeFileSync, mkdirSync } from
 import { tmpdir } from "node:os";
 import { basename, dirname, join as joinPath, posix } from "node:path";
 import { spawnSync } from "node:child_process";
-import { LANG_BY_EXT, isBinaryExt, isConfigFile } from "./astgrep.js";
+import { LANG_BY_EXT, isBinaryExt, isConfigFile, langOf } from "./astgrep.js";
 import { extractCalls, extractImports, extractLiterals, extractSymbols, isTestFile } from "./extract.js";
 import { buildJoinIndex } from "./join.js";
 import { extractAnchors, extractFileRoutes, loadRepoRules } from "./anchors.js";
+import { aggregateFiles, harvestFile, promote, type FileSigs, type SynthesizedRule } from "./discover.js";
 import type { CallSite, Edge, Graph, ImportSite, LiteralSite, NodeRec, SymbolRec } from "./types.js";
 import type { AnchorDraft } from "./anchors.js";
 import { coChangePairs } from "./cochange.js";
@@ -23,9 +24,13 @@ export interface FileFacts {
   calls: CallSite[];
   literals: LiteralSite[];
   anchors: AnchorDraft[];
+  // Tier-3 discovery: per-file histogram of call-shape signatures
+  // (sig -> [totalSites, pathSites]); aggregated repo-wide at load to promote
+  // statistically significant unknown shapes into implicit half-weight rules.
+  sigs?: FileSigs;
 }
 
-const CACHE_VERSION = 5; // bump when extractor semantics change
+const CACHE_VERSION = 6; // bump when extractor semantics change
 const IGNORE_DIRS = new Set([".git", "node_modules", "dist", "vendor", ".venv", "venv", "target", "coverage", ".next", "build", "__pycache__", ".pi", ".pi-fovea", "deps", "_build", ".tox", "Pods"]);
 const MAX_FILES = 24000;
 // Generated dependency manifests are enormous and carry no first-class routes.
@@ -103,8 +108,12 @@ export const loadFacts = (root: string, files: string[]): Record<string, FileFac
   } catch {
     cached = undefined;
   }
-  const { pack: anchorPack, fileRoutes, sha: rulesSha } = loadRepoRules(root);
-  const rulesChanged = cached !== undefined && cached.rulesSha !== rulesSha;
+  const { pack: basePack, fileRoutes, sha: baseRulesSha } = loadRepoRules(root);
+  const anchorPack = [...basePack];
+  // Implicit rules promote AFTER the first fact pass: their evidence lives in
+  // freshly harvested sigs, so the pack can only be finalized once facts exist.
+  let implicitRules: SynthesizedRule[] = [];
+  let rulesSha = baseRulesSha;
   if (cached && (cached.version !== CACHE_VERSION || cached.root !== root)) cached = undefined;
   const facts: Record<string, FileFacts> = {};
   const dirty: string[] = [];
@@ -133,12 +142,31 @@ export const loadFacts = (root: string, files: string[]): Record<string, FileFac
     putByFile(extractImports(code, root), (f, v) => f.imports.push(v));
     putByFile(extractCalls(code, root), (f, v) => f.calls.push(v));
     putByFile(extractLiterals(dirty, root), (f, v) => f.literals.push(v));
+    // Tier-3 harvest: regex histogram of call-shape signatures per file. Cheap
+    // (line scan, no ast-grep) and cached alongside the other facts.
+    for (const f of code) {
+      const lang = langOf(f);
+      if (!lang) continue;
+      let text = "";
+      try { text = readFileSync(joinPath(root, f), "utf8"); } catch { continue; }
+      const sigs = harvestFile(lang, text);
+      if (Object.keys(sigs).length) facts[f]!.sigs = sigs;
+    }
+  }
+  // Tier-3: promote harvested signatures into implicit rules BEFORE anchors
+  // run, and fold their ids into the rules hash so a promotion change rebuilds
+  // anchors exactly like a rules.json edit would.
+  implicitRules = promote(aggregateFiles(Object.fromEntries(Object.entries(facts).map(([k, v]) => [k, v.sigs]))), anchorPack);
+  if (implicitRules.length) {
+    anchorPack.push(...implicitRules);
+    rulesSha = createHash("sha1").update(baseRulesSha).update(JSON.stringify(implicitRules.map((r) => r.id).sort())).digest("hex");
   }
+  const rulesChangedFinal = cached !== undefined && cached.rulesSha !== rulesSha;
   // Anchors need enclosing-symbol resolution. Symbols, imports, calls and
   // literals are rules-independent — when only the rule pack changed, re-run
   // anchor extraction over every code file against cached symbols and keep
   // every other fact (green-node reuse one level up).
-  const anchorTargets = rulesChanged
+  const anchorTargets = rulesChangedFinal
     ? files.filter((f) => !isConfigFile(f))
     : dirty.filter((f) => !isConfigFile(f));
   if (anchorTargets.length) {
@@ -151,7 +179,7 @@ export const loadFacts = (root: string, files: string[]): Record<string, FileFac
     const symsByFile = new Map<string, SymbolRec[]>();
     for (const rel of anchorTargets) {
       symsByFile.set(rel, facts[rel]?.symbols.length ? facts[rel]!.symbols : (cached?.facts[rel]?.symbols ?? []));
-      if (rulesChanged) facts[rel] && (facts[rel]!.anchors = []);
+      if (rulesChangedFinal) facts[rel] && (facts[rel]!.anchors = []);
     }
     const enclosingId = (file: string, line: number): string | undefined => {
       const syms = symsByFile.get(file) ?? [];
@@ -391,13 +419,18 @@ export const assembleGraph = (root: string, files: string[], facts: Record<strin
   for (const [label, sites] of draftsByLabel) {
     const first = sites[0]!;
     const filesOf = [...new Set(sites.map((s) => s.file))];
-    anchors.push({ id: label, kind: first.kind, label: sites.length > 1 ? `${label} · ${sites.length} sites` : label, nodeId: first.nodeId, file: first.file, line: first.line });
+    // A hub is implicit only when EVERY site came from a discovered rule — a
+    // match by any real rule upgrades it back to first-class instantly.
+    const hubImplicit = sites.every((s) => s.implicit === true);
+    anchors.push({ id: label, kind: first.kind, label: sites.length > 1 ? `${label} · ${sites.length} sites` : label, nodeId: first.nodeId, file: first.file, line: first.line, ...(hubImplicit ? { implicit: true } : {}) });
     const idx = addNode(nodes, seen, {
       id: `anchor:${label}`, name: label, kind: "anchor", file: first.file, line: first.line,
-      sig: sites.length > 1 ? `${label} (${sites.length} sites)` : label, lang: "anchor",
+      sig: `${hubImplicit ? "(△ discovered) " : ""}${sites.length > 1 ? `${label} (${sites.length} sites)` : label}`, lang: "anchor",
     });
     (byFile.get(first.file) ?? byFile.set(first.file, []).get(first.file)!).push(idx);
-    const w = 1 / Math.sqrt(sites.length);
+    // Tier-3 hubs prove themselves at half conductance; a later literal join
+    // against a first-class hub can still warm them via the channel edges.
+    const w = (hubImplicit ? 0.5 : 1) / Math.sqrt(sites.length);
     for (const s of sites) {
       const handler = seen.get(s.nodeId) ?? fileIdx.get(s.file)!;
       pushEdge(idx, handler, "anchors", w);

package/src/core/discover.ts

@@ -0,0 +1,188 @@
+// Tier-3: autonomy for route extraction. The static pack catches known port
+// shapes; this module watches the literal channel for shapes the pack does NOT
+// declare, promotes statistically significant ones into synthesized "implicit"
+// rules at half hub gravity, and lets confirmatory joins against real hubs
+// upgrade them to full first-class weight.
+//
+// The promotion statistic is a per-argument conditional: given the string arg
+// at position i of call-shape (lang·shape·callee), how often does it classify
+// as a path? A Jeffreys-smoothed posterior with global floors decides — not raw
+// frequency, under which chaff like `assertEquals(...)` dwarfs every real shape.
+//
+// Corpus audit (8 repos, 183 sigs n≥4): junk bands sit below p̂≈0.27, real
+// shapes above p̂≈0.75 — the 0.55 line is a cliff, not a gradient.
+//
+// Harvest is line-regex over source text — no ast-grep pass needed. Per file we
+// store a compact signature histogram (sig -> [sites, pathSites]); promotions
+// aggregate across ALL files of the repo, so a dependency update or a style
+// drift can only flip a marginal signature when its repo-wide evidence moves.
+
+import { classifyLiteral } from "./join.js";
+
+export type Shape = "recv" | "bare" | "dec";
+
+// Compacted per-file histogram: sigKey -> [totalSites, pathSites]
+export type FileSigs = Record<string, [number, number]>;
+
+const QUOTED = /^[rbfuRBFU]{0,3}(["'`])([\s\S]*)\1$/;
+const unquote = (s: string): string | undefined => {
+  const m = QUOTED.exec(s.trim());
+  return m ? m[2] : undefined;
+};
+
+// Line-local call scan: grabs the callee shape (recv chain, bare, decorator)
+// and the raw arg list of every `X(...)` on the line. Multi-line calls still
+// land because route strings overwhelmingly sit on the call's first line.
+const CALL_LINE_RE = /(?<at>@)?(?<recv>(?:[A-Za-z_$][\w$]*\.)+)?(?<method>[A-Za-z_$][\w$]*)\s*\((?<args>[^()]*)\)/g;
+const STRING_RE = /([rbfuRBFU]{0,3})(["'`])((?:\\.|(?!\2)[^\\])*)\2/g;
+
+// Callees that are noise even at 100% precision (env/fs access, string ctors,
+// module loading — dynamic import()/require() hits the path channel but the
+// import edge already covers it, an anchor would double-count the site).
+const CALLEE_DENY = new Set([
+  "join", "resolve", "dirname", "basename", "expand_path",
+  "readFile", "readFileSync", "existsSync", "open", "load", "loads",
+  "import", "require",
+  // String predicates: membership tests hit the path column at high rate but
+  // never refer to routes. (Distinguishing cause from noise is callee-semantic.)
+  "startsWith", "endsWith", "contains", "includes", "equals", "equalsIgnoreCase",
+  "matches", "matchesPattern", "useParams", "matchPath",
+]);
+
+export const harvestFile = (lang: string, text: string): FileSigs => {
+  const sigs: FileSigs = {};
+  for (const line of text.split("\n")) {
+    if (!line.includes("(") || !(line.includes('"') || line.includes("'") || line.includes("`"))) continue;
+    CALL_LINE_RE.lastIndex = 0;
+    let c: RegExpExecArray | null;
+    while ((c = CALL_LINE_RE.exec(line))) {
+      const method = c.groups?.method;
+      if (!method || CALLEE_DENY.has(method)) continue;
+      const shape: Shape = c.groups?.at ? "dec" : c.groups?.recv ? "recv" : "bare";
+      const argsText = c.groups?.args ?? "";
+      if (!argsText) continue;
+      // True argument index of each string literal (split tolerantly on commas).
+      const args = argsText.split(",");
+      let idx = 0;
+      for (const raw of args) {
+        STRING_RE.lastIndex = 0;
+        const sm = STRING_RE.exec(raw);
+        const idxNow = idx++;
+        if (!sm) continue;
+        const lit = sm[3];
+        if (lit === undefined || lit === "") continue;
+        const key = `${lang}|${shape}|${method}|${idxNow}`;
+        const rec = sigs[key] ?? [0, 0];
+        rec[0]++;
+        if (classifyLiteral(lit) === "path") rec[1]++;
+        sigs[key] = rec;
+      }
+    }
+  }
+  return sigs;
+};
+
+export interface SigStats {
+  key: string;
+  lang: string;
+  shape: Shape;
+  callee: string;
+  argIdx: number;
+  n: number;
+  pathN: number;
+  files: number;
+}
+
+export const aggregateFiles = (perFile: Record<string, FileSigs | undefined>): SigStats[] => {
+  const agg = new Map<string, SigStats>();
+  for (const sigs of Object.values(perFile)) {
+    if (!sigs) continue;
+    for (const [key, [n, p]] of Object.entries(sigs)) {
+      const stat = agg.get(key);
+      if (stat) {
+        stat.n += n;
+        stat.pathN += p;
+        stat.files++;
+      } else {
+        const [lang, shape, callee, argIdx] = key.split("|");
+        agg.set(key, { key, lang: lang!, shape: shape as Shape, callee: callee!, argIdx: Number(argIdx), n, pathN: p, files: 1 });
+      }
+    }
+  }
+  return [...agg.values()];
+};
+
+/** Jeffreys-ish posterior: p̂ = (pathN + .5) / (n + 1). */
+export const posterior = (pathN: number, n: number): number => (pathN + 0.5) / (n + 1);
+
+export const MIN_SITES = 4;
+export const MIN_FILES = 2;
+export const MIN_POSTERIOR = 0.55;
+
+const escapeRe = (s: string): string => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+// Pattern synthesis per shape and arg position: dummy metavars for the slots
+// the corpus says are not the path, $P at the proven position. Two variants
+// per site — exact arity and with a trailing $$$H absorb — because some
+// dialects only match with explicit tail holes (Python `$X, $P, $$$H`).
+export interface SynthesizedRule {
+  id: string;
+  langs: string[];
+  patterns: string[];   // patternRunAll variants
+  methods: string;
+  kind: string;
+  implicit: true;
+  evidence: { n: number; pathN: number; files: number; posterior: number };
+}
+
+export const synthesize = (s: SigStats): SynthesizedRule | undefined => {
+  const slots: string[] = [];
+  for (let i = 0; i <= s.argIdx; i++) slots.push(i === s.argIdx ? "$P" : `$X${i}`);
+  const inner = slots.join(", ");
+  let variants: string[];
+  switch (s.shape) {
+    case "recv": variants = [`$R.$M(${inner})`, `$R.$M(${inner}, $$$H)`]; break;
+    case "bare": variants = [`$M(${inner})`, `$M(${inner}, $$$H)`]; break;
+    case "dec":  variants = [`@$M(${inner})`, `@$M(${inner}, $$$H)`]; break;
+  }
+  return {
+    id: `implicit:${s.lang.toLowerCase()}:${s.shape}:${s.callee}:${s.argIdx}`,
+    langs: [s.lang],
+    patterns: variants,
+    methods: `^(?i:${escapeRe(s.callee)})$`,
+    kind: "route",
+    implicit: true,
+    evidence: { n: s.n, pathN: s.pathN, files: s.files, posterior: posterior(s.pathN, s.n) },
+  };
+};
+
+// Shape-shape compatibility: a discovery is only NEW when no existing rule
+// already binds the callee with a compatible pattern shape in that language.
+// e.g. Java's @GetMapping is in the pack, so java:dec:GetMapping promotes nothing.
+const shapeCompatPatterns: Record<Shape, RegExp> = {
+  recv: /^\$R\.\$M\(/,
+  bare: /^\$M[(\s]/,
+  dec: /^@\$(R\.)?M\(/,
+};
+
+const isCovered = (sig: SigStats, pack: Array<{ langs: string[]; methods: string; pattern?: string; patterns?: string[] }>): boolean => {
+  const mre = (methods: string, callee: string): boolean => new RegExp(methods.replace(/^\^\(\?i\)/, "^(?i:")).test(callee);
+  return pack.some((r) => {
+    if (!r.langs.includes(sig.lang)) return false;
+    if (!mre(r.methods, sig.callee)) return false;
+    const pats = r.patterns ?? (r.pattern ? [r.pattern] : []);
+    return pats.some((p) => shapeCompatPatterns[sig.shape].test(p));
+  });
+};
+
+export const promote = (sigs: SigStats[], pack: Array<{ id: string; langs: string[]; methods: string; pattern?: string; patterns?: string[] }> = []): SynthesizedRule[] => {
+  const out: SynthesizedRule[] = [];
+  for (const s of sigs) {
+    if (s.n < MIN_SITES || s.files < MIN_FILES) continue;
+    if (posterior(s.pathN, s.n) < MIN_POSTERIOR) continue;
+    if (isCovered(s, pack)) continue;
+    const r = synthesize(s);
+    if (r) out.push(r);
+  }
+  return out;
+};

package/src/core/join.ts

@@ -14,7 +14,7 @@ export interface LitOccurrence { node: number; line: number; file: string; }
 
 export interface JoinEdge { a: number; b: number; w: number; }
 
-const PLACEHOLDER_SEGMENT = /^(?::[^/]+|\{[^}/]*\}|\$\{[^}/]*\}|<[^/>]+>|\*+)$/;
+const PLACEHOLDER_SEGMENT = /^(?::[^/]+|\{[^}/]*\}|\$\{[^}/]*\}|\$[A-Za-z_]\w*|<[^/>]+>|\*+)$/; // $x = Kotlin template shorthand
 const WORD_RE = /^[A-Za-z][\w$.\-]{6,63}$/;
 const URLISH_RE = /^(?:https?|wss?):\/\/[^/]+/;
 

package/src/core/sync.ts

@@ -64,10 +64,14 @@ export const sync = (root: string, params: SyncParams, now?: RepoState): SyncOut
     };
   }
 
-  // Version drifted: measure what moved.
-  const current = new Set(state.graph.anchors.map((a) => a.id));
-  const added = [...current].filter((id) => !prev.anchors.has(id));
-  const removed = [...prev.anchors].filter((id) => !current.has(id));
+  // Version drifted: measure what moved. Implicit (tier-3 discovered) hubs
+  // churn is reported but NEVER escalates alone — hypotheses with no first-class
+  // backing don't get to wake the model with a red verdict.
+  const current = new Map(state.graph.anchors.map((a) => [a.id, a.implicit === true]));
+  const currentIds = new Set(current.keys());
+  const added = [...currentIds].filter((id) => !prev.anchors.has(id));
+  const removed = [...prev.anchors].filter((id) => !currentIds.has(id));
+  const newlyImplicit = added.filter((id) => current.get(id));
 
   const session = getSession(root);
   const disclosedFiles = new Set<string>();
@@ -92,7 +96,7 @@ export const sync = (root: string, params: SyncParams, now?: RepoState): SyncOut
 
   baselines.set(root, { ...snapshot(state), warmed: warmNow });
 
-  const red = added.length + removed.length > 0 || warmNew.length >= Math.max(1, params.warmFileThreshold);
+  const red = (added.length - newlyImplicit.length) + removed.length > 0 || warmNew.length >= Math.max(1, params.warmFileThreshold);
   if (!red) {
     return {
       structural: true, red: false, tokens: 0,
@@ -102,7 +106,8 @@ export const sync = (root: string, params: SyncParams, now?: RepoState): SyncOut
 
   const lines: string[] = [];
   lines.push(`fovea sync · v ${state.version} · edit cascade did not stay local`);
-  for (const id of added.slice(0, 12)) lines.push(`  ⚑=new ${id}`);
+  for (const id of added.filter((a) => !newlyImplicit.includes(a)).slice(0, 12)) lines.push(`  ⚑=new ${id}`);
+  for (const id of newlyImplicit.slice(0, 6)) lines.push(`  △ newly discovered hub ${id}`);
   for (const id of removed.slice(0, 12)) lines.push(`  ⚑-removed ${id}`);
   if (warmNew.length) {
     lines.push(`  newly warm undisclosed files (revisit with fovea_focus):`);

package/src/core/types.ts

@@ -48,6 +48,7 @@ export interface Anchor {
   nodeId: string;    // handler symbol node id, or enclosing node
   file: string;
   line: number;
+  implicit?: boolean; // tier-3 discovered shape: half hub gravity, shown with △
 }
 
 export interface Graph {