@event4u/agent-config 17.2.1 → 17.4.0

package/src/scripts/code_graph/map.ts

@@ -14,15 +14,17 @@
  * host path or anything else that differs between two builds of one commit.
  */
 import { execFileSync } from 'node:child_process';
-import { createHash } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { write_atomic } from '../_lib/fs_atomic.js';
 import { hardenedSpawnEnv } from '../_lib/spawn_env.js';
-import { buildFromRepo } from './build.js';
-import { computeVerdict, graphState, NATIVE_CACHE_REL } from './detect.js';
+import { buildFromRepo, readProjectProbe } from './build.js';
+import { acquire as acquireRefreshLock, heldByThisProcess } from './refresh_lock.js';
+import { computeVerdict, graphState } from './detect.js';
+import { graphHome } from './graph_home.js';
 import {
     areaDrift,
     buildMapModel,
@@ -38,7 +40,6 @@ import type { CodeGraph } from './types.js';
 const _HERE = path.dirname(fileURLToPath(import.meta.url));
 const VIEWER_DIR = path.join(_HERE, 'map_viewer');
 
-export const MAP_DIR_REL = path.join('agents', 'map');
 /** Rough characters-per-token used to hold MAP.md to its budget. */
 const CHARS_PER_TOKEN = 4;
 export const MAP_TOKEN_BUDGET = 2000;
@@ -49,6 +50,33 @@ export interface MapMeta {
     commit: string;
     state: string;
     summary: string;
+    /**
+     * The graph this map was drawn from: the first 16 hex of the SHA-256 of the
+     * graph cache's bytes (or of the serialized graph when there is no cache).
+     * `graph.json`, `map.json` and `index.html` agree exactly when this matches
+     * {@link graphGeneration} of the current cache — the test a reader runs
+     * instead of comparing modification times.
+     */
+    graph_generation?: string;
+}
+
+/** The generation of a graph cache: the first 16 hex of the SHA-256 of its bytes; null when unreadable. */
+export function graphGeneration(cachePath: string): string | null {
+    try {
+        return createHash('sha256').update(fs.readFileSync(cachePath)).digest('hex').slice(0, 16);
+    } catch {
+        return null;
+    }
+}
+
+/** The generation a drawn map records, or null when it records none (an older map) or cannot be read. */
+export function mapGeneration(outDir: string): string | null {
+    try {
+        const doc = JSON.parse(fs.readFileSync(path.join(outDir, 'map.json'), 'utf-8')) as { meta?: { graph_generation?: unknown } };
+        return typeof doc.meta?.graph_generation === 'string' ? doc.meta.graph_generation : null;
+    } catch {
+        return null;
+    }
 }
 
 export interface MapBuildResult {
@@ -72,32 +100,48 @@ function gitHead(root: string): string {
 }
 
 /**
- * Entry points a manifest declares: `package.json` `bin` / `main` / `module`,
- * `composer.json` `bin`. Route files and `public/index.php` are recognised by
- * path in `staticRole`; this only adds what a manifest names explicitly.
+ * Entry points the project's manifests declare, in every package root:
+ * `package.json` `bin` / `main` / `module` / `exports`, `composer.json` `bin`,
+ * `pyproject.toml` `[project.scripts]`, a Maven `<mainClass>`. Framework entry
+ * files are a provider's role (`roleOf`); this only adds what a manifest names.
  */
 export function declaredEntryFiles(root: string): string[] {
     const out = new Set<string>();
-    const add = (v: unknown): void => {
-        if (typeof v !== 'string') return;
-        out.add(path.posix.normalize(v.replace(/^\.\//, '')));
-    };
-    try {
-        const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf-8')) as Record<string, unknown>;
-        const bin = pkg['bin'];
-        if (typeof bin === 'string') add(bin);
-        else if (bin && typeof bin === 'object') for (const v of Object.values(bin)) add(v);
-        add(pkg['main']);
-        add(pkg['module']);
-    } catch {
-        /* no package.json */
-    }
-    try {
-        const composer = JSON.parse(fs.readFileSync(path.join(root, 'composer.json'), 'utf-8')) as Record<string, unknown>;
-        const bin = composer['bin'];
-        if (Array.isArray(bin)) for (const v of bin) add(v);
-    } catch {
-        /* no composer.json */
+    for (const [rel, text] of readProjectProbe(root).manifests) {
+        const dir = path.posix.dirname(rel);
+        const add = (v: unknown): void => {
+            if (typeof v !== 'string' || v.includes('*') || /^[a-z]+:/i.test(v)) return;
+            out.add(path.posix.normalize(path.posix.join(dir, v.replace(/^\.\//, ''))));
+        };
+        const base = path.posix.basename(rel);
+        try {
+            if (base === 'package.json') {
+                const pkg = JSON.parse(text) as Record<string, unknown>;
+                const leaves = (v: unknown): void => {
+                    if (typeof v === 'string') add(v);
+                    else if (v && typeof v === 'object') for (const x of Object.values(v)) leaves(x);
+                };
+                leaves(pkg['bin']);
+                add(pkg['main']);
+                add(pkg['module']);
+                leaves(pkg['exports']);
+            } else if (base === 'composer.json') {
+                const bin = (JSON.parse(text) as Record<string, unknown>)['bin'];
+                if (Array.isArray(bin)) for (const v of bin) add(v);
+            } else if (base === 'pyproject.toml') {
+                const section = /^\[project\.scripts\]\s*$([\s\S]*?)(?=^\[|(?![\s\S]))/m.exec(text)?.[1] ?? '';
+                for (const m of section.matchAll(/=\s*["']([\w.]+):[\w.]+["']/g)) {
+                    const mod = (m[1] as string).replace(/\./g, '/');
+                    add(`${mod}.py`);
+                    add(`src/${mod}.py`);
+                }
+            } else if (base === 'pom.xml') {
+                const main = /<mainClass>\s*([\w.]+)\s*<\/mainClass>/.exec(text)?.[1];
+                if (main) add(`src/main/java/${main.replace(/\./g, '/')}.java`);
+            }
+        } catch {
+            /* an unreadable manifest declares nothing */
+        }
     }
     return [...out].sort();
 }
@@ -189,12 +233,14 @@ export function diffFiles(root: string, rev: string): string[] | null {
 }
 
 /** Where `code-graph outcome` records which files a session found useful — local, never sent anywhere. */
-export const OUTCOMES_REL = path.join('agents', 'runtime', 'state', 'map-outcomes.jsonl');
+export function outcomesPath(root: string): string {
+    return path.join(graphHome(root).stateDir, 'map-outcomes.jsonl');
+}
 
 export function readOutcomes(root: string): OutcomeEvent[] {
     let text: string;
     try {
-        text = fs.readFileSync(path.join(root, OUTCOMES_REL), 'utf-8');
+        text = fs.readFileSync(outcomesPath(root), 'utf-8');
     } catch {
         return [];
     }
@@ -215,7 +261,7 @@ export function readOutcomes(root: string): OutcomeEvent[] {
 }
 
 export function recordOutcome(root: string, file: string, outcome: OutcomeEvent['outcome'], at: Date = new Date()): void {
-    const p = path.join(root, OUTCOMES_REL);
+    const p = outcomesPath(root);
     fs.mkdirSync(path.dirname(p), { recursive: true });
     const rel = path.relative(fs.realpathSync(root), fs.realpathSync(path.resolve(file)));
     if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) throw new Error(`not a file inside ${root}: ${file}`);
@@ -239,9 +285,35 @@ export function openPrs(root: string): Array<{ number: number; title: string; fi
 
 export async function buildMap(
     root: string,
-    opts: { outDir?: string; cachePath?: string; diffRev?: string; prs?: boolean; noBuild?: boolean } = {},
+    opts: {
+        outDir?: string;
+        cachePath?: string;
+        diffRev?: string;
+        prs?: boolean;
+        noBuild?: boolean;
+        /** Test seam: called after each artefact lands in the new generation. */
+        _afterWrite?: (rel: string) => void;
+    } = {},
 ): Promise<MapBuildResult> {
-    const outDir = opts.outDir ?? path.join(root, MAP_DIR_REL);
+    // Single writer, enforced here rather than trusted to callers: one redraw per
+    // process at a time, and none while another process holds the refresh lock.
+    if (drawing) throw new Error('a map redraw is already running in this process');
+    const release = heldByThisProcess(root) ? (): void => {} : acquireRefreshLock(root);
+    if (release === null) throw new Error('another process holds the code-graph refresh lock');
+    drawing = true;
+    try {
+        return await drawGeneration(root, opts);
+    } finally {
+        drawing = false;
+        release();
+    }
+}
+
+let drawing = false;
+
+async function drawGeneration(root: string, opts: Parameters<typeof buildMap>[1] = {}): Promise<MapBuildResult> {
+    const home = graphHome(root);
+    const outDir = opts.outDir ?? home.mapDir;
     // A chosen --out directory is only ever written into when it is empty or
     // already holds a map: the writer clears stale area pages, and that must
     // never reach a directory of someone else's Markdown.
@@ -253,7 +325,7 @@ export async function buildMap(
     ) {
         throw new Error(`refusing to write a map into ${outDir}: it is not empty and holds no map.json`);
     }
-    const cachePath = opts.cachePath ?? path.join(root, NATIVE_CACHE_REL);
+    const cachePath = opts.cachePath ?? home.cachePath;
     const { graph, built } = await loadOrBuildGraph(root, cachePath, opts.noBuild === true);
     let diff: { rev: string; changed: string[] } | undefined;
     if (opts.diffRev !== undefined) {
@@ -283,31 +355,88 @@ export async function buildMap(
         commit: gitHead(root),
         state: graphState(root, cachePath),
         summary: '',
+        graph_generation: graphGeneration(cachePath) ?? createHash('sha256').update(JSON.stringify(graph)).digest('hex').slice(0, 16),
     };
     meta.summary =
         `${model.files.length} files · ${model.areas.length} areas · ` +
         `${model.analyses.trustedEdges} trusted links · guess share ${pct(model.analyses.guessShare)}`;
 
+    // One generation at a time: everything is written into a sibling directory,
+    // which then replaces the live one, so a reader never sees `map.json` of one
+    // build beside pages of another, and a failed redraw leaves the last one whole.
+    // The default map stages under the gitignored runtime dir, so a killed redraw
+    // leaves nothing in agents/ itself; a chosen --out stages beside itself.
+    const suffix = `${process.pid}-${randomBytes(4).toString('hex')}`;
+    const stage = opts.outDir === undefined ? home.stateDir : path.dirname(outDir);
+    fs.mkdirSync(stage, { recursive: true });
+    const next = path.join(stage, `.map-next-${suffix}`);
+    const prev = path.join(stage, `.map-prev-${suffix}`);
     const written: string[] = [];
-    const write = (rel: string, content: string): void => {
-        const p = path.join(outDir, rel);
-        fs.mkdirSync(path.dirname(p), { recursive: true });
-        write_atomic(p, content);
-        written.push(rel);
-    };
-    const areasDir = path.join(outDir, 'areas');
-    if (fs.existsSync(areasDir)) {
-        for (const f of fs.readdirSync(areasDir)) if (f.endsWith('.md')) fs.rmSync(path.join(areasDir, f));
-    }
-    write('map.json', `${JSON.stringify({ meta, model })}\n`);
-    write('MAP.md', renderMapMd(model, meta));
-    for (const [i, a] of model.areas.entries()) {
-        if (a.files.length >= AREA_PAGE_MIN_FILES) write(path.join('areas', `${a.id}.md`), renderAreaMd(model, i, meta));
+    try {
+        const write = (rel: string, content: string): void => {
+            const p = path.join(next, rel);
+            fs.mkdirSync(path.dirname(p), { recursive: true });
+            write_atomic(p, content);
+            written.push(rel);
+            opts._afterWrite?.(rel);
+        };
+        write('map.json', `${JSON.stringify({ meta, model })}\n`);
+        write('MAP.md', renderMapMd(model, meta));
+        for (const [i, a] of model.areas.entries()) {
+            if (a.files.length >= AREA_PAGE_MIN_FILES) write(path.join('areas', `${a.id}.md`), renderAreaMd(model, i, meta));
+        }
+        write('index.html', renderHtml(model, meta));
+        carryForeignEntries(outDir, next);
+        swapIn(next, outDir, prev);
+    } finally {
+        fs.rmSync(next, { recursive: true, force: true });
     }
-    write('index.html', renderHtml(model, meta));
     return { outDir, model, meta, written, graphBuilt: built };
 }
 
+/**
+ * What a map generation consists of; anything else in the directory is someone else's and is
+ * carried over. `map-render.json` belongs to a generation although `buildMap` does not write it:
+ * it is `code-graph map`'s render check OF that generation, written after the swap, so the
+ * previous one's is dropped rather than left describing pages it never saw.
+ */
+const GENERATION_ENTRIES = new Set(['map.json', 'MAP.md', 'index.html', 'areas', 'map-render.json']);
+
+/** Copy entries the writer does not produce into the new generation, so the swap drops nothing. */
+function carryForeignEntries(live: string, next: string): void {
+    if (!fs.existsSync(live)) return;
+    for (const entry of fs.readdirSync(live)) {
+        if (GENERATION_ENTRIES.has(entry)) continue;
+        fs.cpSync(path.join(live, entry), path.join(next, entry), { recursive: true, verbatimSymlinks: true });
+    }
+}
+
+/**
+ * Replace `live` by `next` with two renames; on a failed second rename the old generation goes
+ * back. Consistent, not atomic: between the renames `live` is briefly absent, and a process
+ * killed there leaves the old generation at `prev` (under the gitignored runtime dir for the
+ * default map) — a reader sees no map, never a mixed one.
+ */
+export function swapIn(next: string, live: string, prev: string, rename: typeof fs.renameSync = fs.renameSync): void {
+    fs.mkdirSync(path.dirname(live), { recursive: true });
+    const hadLive = fs.existsSync(live);
+    if (hadLive) rename(live, prev);
+    try {
+        rename(next, live);
+    } catch (e) {
+        if (!hadLive) throw e;
+        try {
+            rename(prev, live);
+        } catch {
+            throw new Error(`map swap failed and the restore failed too; the previous generation is at ${prev}`, {
+                cause: e,
+            });
+        }
+        throw e;
+    }
+    if (hadLive) fs.rmSync(prev, { recursive: true, force: true });
+}
+
 function pct(x: number): string {
     return `${Math.round(x * 1000) / 10} %`;
 }
@@ -363,6 +492,12 @@ export function renderMapMd(m: MapModel, meta: MapMeta): string {
             `areas under ${m.thresholds.smallArea} files fold into "small parts" · an area above ` +
             `${Math.round(m.thresholds.maxAreaShare * 100)} % is split once · lists capped at ${m.thresholds.listCap}.`,
         '',
+        m.providers && m.providers.length > 0
+            ? `Convention providers: ${m.providers
+                  .map((p) => `${md(p.name)} (${p.status}${p.roots.some((r) => r !== '') ? `, ${p.roots.map((r) => code(r || '.')).join(', ')}` : ''})`)
+                  .join(' · ')} — plus the framework-neutral default.`
+            : 'Convention providers: none detected — only the framework-neutral default ran.',
+        '',
         '',
     ].join('\n');
 
@@ -501,7 +636,7 @@ export function renderMapMd(m: MapModel, meta: MapMeta): string {
         const rank = (r: (typeof rp)[number]): number =>
             (r.route.startsWith('GET ') ? 0 : 2) + (r.views.length > 0 ? 0 : 1);
         const withChain = rp
-            .filter((r) => r.views.length + r.tables.length > 0)
+            .filter((r) => r.views.length + r.tables.length + (r.inferredTables?.length ?? 0) > 0)
             .sort((a, b) => rank(a) - rank(b) || (a.route < b.route ? -1 : a.route > b.route ? 1 : 0));
         sections.push([
             'Request paths',
@@ -509,7 +644,8 @@ export function renderMapMd(m: MapModel, meta: MapMeta): string {
                 '## Request paths',
                 '',
                 `${m.analyses.requestPathsTotal} declared routes; ${m.analyses.requestPathsResolved} reach a handler in this tree. ` +
-                    'Route → handler → views it renders · tables its models persist:',
+                    'Route → handler → views it renders · tables its models persist, up to three calls deep ' +
+                    '(inferred: reached through a call bound by name alone):',
                 '',
                 ...(withChain.length ? withChain : rp).slice(0, 10).map((r) => {
                     const handlerFile = path.posix.basename(f[r.handler]?.path ?? '');
@@ -517,6 +653,7 @@ export function renderMapMd(m: MapModel, meta: MapMeta): string {
                         handlerFile.replace(/\.php$/, '') === r.handlerSymbol ? handlerFile : `${handlerFile}::${r.handlerSymbol}`,
                         ...r.views.map((v) => path.posix.basename(f[v]?.path ?? '')),
                         ...r.tables.map((t) => `table ${code(t)}`),
+                        ...(r.inferredTables ?? []).map((t) => `table ${code(t)} (inferred)`),
                     ];
                     return `- ${code(r.route)} → ${chain.map((c) => (c.startsWith('table') ? c : `${code(c)}`)).join(' → ')}`;
                 }),
@@ -721,6 +858,7 @@ export function renderHtml(m: MapModel, meta: MapMeta): string {
         '<button type="button" id="z-out">−</button>',
         '<button type="button" id="z-in">+</button>',
         '<button type="button" id="z-fit"></button>',
+        '<button type="button" id="dim" aria-pressed="false"></button>',
         '<button type="button" id="theme"></button>',
         '<button type="button" id="lang"></button>',
         '</div>',
@@ -739,7 +877,7 @@ export function renderHtml(m: MapModel, meta: MapMeta): string {
 
 /** The map a previous `code-graph map` wrote, or null when there is none. */
 export function readMap(root: string): { meta: MapMeta; model: MapModel } | null {
-    return readMapAt(path.join(root, MAP_DIR_REL));
+    return readMapAt(graphHome(root).mapDir);
 }
 
 function readMapAt(dir: string): { meta: MapMeta; model: MapModel } | null {
@@ -785,7 +923,11 @@ export interface AreaReport {
  * One area, found by id (`a3`), by exact name, or by a file it contains —
  * exact matches only, so the answer is always about the area that was named.
  */
-export function areaReport(m: MapModel, query: string): AreaReport | { refusal: string; candidates: string[] } {
+export function areaReport(
+    m: MapModel,
+    query: string,
+    pageDir: string = path.posix.join('agents', 'map'),
+): AreaReport | { refusal: string; candidates: string[] } {
     let i = m.areas.findIndex((a) => a.id === query || a.name === query);
     if (i < 0) {
         const f = m.files.findIndex((x) => x.path === query);
@@ -841,6 +983,6 @@ export function areaReport(m: MapModel, query: string): AreaReport | { refusal:
             .sort((x, y) => y[1] - x[1] || x[0] - y[0])
             .slice(0, cap)
             .map(([ai, w]) => ({ area: `${m.areas[ai]?.id ?? ''} ${m.areas[ai]?.name ?? ''}`, links: w })),
-        page: a.files.length >= AREA_PAGE_MIN_FILES ? path.posix.join('agents', 'map', 'areas', `${a.id}.md`) : null,
+        page: a.files.length >= AREA_PAGE_MIN_FILES ? path.posix.join(pageDir, 'areas', `${a.id}.md`) : null,
     };
 }

package/src/scripts/code_graph/map_model.ts

@@ -16,7 +16,8 @@ import Graph from 'graphology';
 import louvain from 'graphology-communities-louvain';
 import forceAtlas2 from 'graphology-layout-forceatlas2';
 
-import type { CodeGraph, ResolvedVia } from './types.js';
+import { catalogRow, type CoverageStatus, providerRole } from './providers/index.js';
+import type { ActiveProviderRecord, CodeGraph, ResolvedVia } from './types.js';
 import { isStatedResolution } from './types.js';
 
 export const MAP_MODEL_VERSION = 1;
@@ -35,6 +36,8 @@ export type FileRole =
 
 /** Roles whose files take part in clustering. */
 const CLUSTER_ROLES: ReadonlySet<FileRole> = new Set(['code', 'test', 'entry', 'view']);
+/** Directories of including views at which a view counts as a shared partial. */
+const SHARED_PARTIAL_DIRS = 3;
 
 /** Compact symbol: [name, kind, line]. */
 export type MapSymbol = [string, string, number];
@@ -57,6 +60,16 @@ export interface MapFile {
     externals: string[];
     /** Test files that cover this file (`tests` relation). */
     tests: number[];
+    /** Convention providers that drew an edge into or out of this file; absent when none did. */
+    linkedBy?: string[];
+}
+
+/** A convention provider active in the graph, with its catalog status. */
+export interface MapProvider {
+    id: string;
+    name: string;
+    status: CoverageStatus | 'uncatalogued';
+    roots: string[];
 }
 
 export interface MapArea {
@@ -81,7 +94,7 @@ export interface MapArea {
     neighbours: number[];
 }
 
-/** One declared route and what its handler reaches (Laravel overlay). */
+/** One declared route and what its handler reaches (a convention provider). */
 export interface RequestPath {
     route: string;
     /** Index of the routes file. */
@@ -92,6 +105,8 @@ export interface RequestPath {
     views: number[];
     models: number[];
     tables: string[];
+    /** Tables reached only through a call bound by name alone (a `dynamic` hop with one candidate). */
+    inferredTables: string[];
 }
 
 export interface MapThresholds {
@@ -118,6 +133,8 @@ export interface MapModel {
     areaEdges: Array<[number, number, number]>;
     diff?: MapDiff;
     artefacts?: MapArtefacts;
+    /** Convention providers active in the graph; absent when none was. */
+    providers?: MapProvider[];
     /** Set by the map writer, not by `buildMapModel`: they need IO. */
     drift?: AreaDrift;
     prOverlap?: PrOverlap;
@@ -208,16 +225,19 @@ const CONFIG_BASENAME =
  * The role a path has before any edge is looked at. `infra` and `isolated`
  * depend on edges and are decided later; everything here is a name fact.
  */
-export function staticRole(p: string, entries: ReadonlySet<string>): FileRole {
+export function staticRole(p: string, entries: ReadonlySet<string>, active?: readonly ActiveProviderRecord[]): FileRole {
     if (/\.mdx?$/i.test(p)) return 'doc';
     if (isTestPath(p)) return 'test';
     const base = path.posix.basename(p);
-    if (base.endsWith('.blade.php') || p.startsWith('resources/views/') || p.includes('/resources/views/')) return 'view';
+    // A provider's view role outranks the neutral rules below; any other role it
+    // gives sits where an entry would.
+    const byProvider = providerRole(p, active);
+    if (byProvider === 'view') return 'view';
     if (/(^|\/)(database\/)?migrations\//.test(p)) return 'migration';
     if (/(^|\/)(resources\/)?lang\//.test(p)) return 'translation';
     if (p.startsWith('config/') || CONFIG_BASENAME.test(base)) return 'config';
-    if (entries.has(p) || p.startsWith('routes/') || p === 'public/index.php' || p === 'artisan') return 'entry';
-    return 'code';
+    if (entries.has(p)) return 'entry';
+    return byProvider ?? 'code';
 }
 
 
@@ -307,7 +327,8 @@ export function buildMapModel(graph: CodeGraph, inputs: MapInputs = {}): MapMode
     }
 
     // 3. Roles: names first, then the two edge-dependent ones.
-    const roles: FileRole[] = paths.map((p) => staticRole(p, entries));
+    const active = graph.providers ?? [];
+    const roles: FileRole[] = paths.map((p) => staticRole(p, entries, active));
     // A layout every view extends couples views exactly the way a utility
     // couples code, so views are eligible for the hold-out too.
     const holdable = (r: FileRole | undefined): boolean => r === 'code' || r === 'view';
@@ -322,9 +343,29 @@ export function buildMapModel(graph: CodeGraph, inputs: MapInputs = {}): MapMode
         if ((inFiles[i] as number) > infraInDegree) roles[i] = 'infra';
         else if (roles[i] === 'code' && inFiles[i] === 0 && outFiles[i] === 0) roles[i] = 'isolated';
     }
+    // A partial that views of SHARED_PARTIAL_DIRS directories include is shared
+    // the way a utility is: kept in, it glues every page that shows it into one
+    // area and names that area after itself. Counted by including directory,
+    // not by in-degree, because a project's code dwarfs its views in the p99.
+    const includers = new Map<number, Set<string>>();
+    for (const [s, t] of edges) {
+        if (roles[s] !== 'view' || roles[t] !== 'view') continue;
+        const dirs = includers.get(t) ?? new Set<string>();
+        dirs.add(path.posix.dirname(paths[s] as string));
+        includers.set(t, dirs);
+    }
+    for (const [t, dirs] of includers) if (dirs.size >= SHARED_PARTIAL_DIRS) roles[t] = 'infra';
+    // A routes file links to every handler it routes, so in the clustering it
+    // is the hub of whatever it touches. It sits out the clustering and then
+    // joins the area most of its handlers landed in.
+    const routeFiles = new Set<number>();
+    for (const n of graph.nodes) {
+        const i = n.kind === 'route' ? idx.get(n.source_file) : undefined;
+        if (i !== undefined && CLUSTER_ROLES.has(roles[i] as FileRole)) routeFiles.add(i);
+    }
 
     // 4. Areas: seeded Louvain over the coupled roles.
-    const clusterable = (i: number): boolean => CLUSTER_ROLES.has(roles[i] as FileRole);
+    const clusterable = (i: number): boolean => CLUSTER_ROLES.has(roles[i] as FileRole) && !routeFiles.has(i);
     const undirected = new Map<string, number>();
     for (const [s, t, w] of edges) {
         if (!clusterable(s) || !clusterable(t)) continue;
@@ -398,6 +439,15 @@ export function buildMapModel(graph: CodeGraph, inputs: MapInputs = {}): MapMode
     drafts.forEach((d, ai) => {
         for (const f of d.files) areaOf[f] = ai;
     });
+    for (const rf of [...routeFiles].sort((a, b) => a - b)) {
+        const pull = new Map<number, number>();
+        for (const [s, t, w] of edges) if (s === rf && (areaOf[t] as number) >= 0) pull.set(areaOf[t] as number, (pull.get(areaOf[t] as number) ?? 0) + w);
+        const best = [...pull.entries()].sort((a, b) => b[1] - a[1] || a[0] - b[0])[0]?.[0];
+        const ai = best ?? drafts.push({ files: [], kind: 'small-parts', hub: rf, name: `small parts · ${topDir(paths[rf] as string)}` }) - 1;
+        const d = drafts[ai] as Draft;
+        d.files = [...d.files, rf].sort((a, b) => byPath(paths[a] as string, paths[b] as string));
+        areaOf[rf] = ai;
+    }
 
     // 6. Area metrics, area→area weights, layouts.
     const areaWeights = new Map<string, number>();
@@ -506,6 +556,22 @@ export function buildMapModel(graph: CodeGraph, inputs: MapInputs = {}): MapMode
     const trustedTotal = edges.reduce((n, e) => n + e[2], 0);
     const guessTotal = guessEdges.reduce((n, e) => n + e[2], 0);
 
+    const linkedBy = new Map<number, Set<string>>();
+    const sourceFileOf = new Map(graph.nodes.map((n) => [n.id, n.source_file] as const));
+    const fileIndexOf = (id: string): number | undefined => {
+        const f = sourceFileOf.get(id);
+        return f === undefined ? undefined : idx.get(f);
+    };
+    for (const e of graph.edges) {
+        if (!e.provider_id) continue;
+        for (const i of [fileIndexOf(e.source), fileIndexOf(e.target)]) {
+            if (i === undefined) continue;
+            const set = linkedBy.get(i) ?? new Set<string>();
+            set.add(e.provider_id);
+            linkedBy.set(i, set);
+        }
+    }
+
     const symbolsPerFile = 40;
     const files: MapFile[] = paths.map((p, i) => {
         const syms = (symbolsOf.get(p) ?? []).sort((a, b) => a[2] - b[2] || byPath(a[0], b[0]));
@@ -520,8 +586,13 @@ export function buildMapModel(graph: CodeGraph, inputs: MapInputs = {}): MapMode
             symbolsOmitted: Math.max(0, syms.length - symbolsPerFile),
             externals: [...(externals.get(i) ?? [])].sort(byPath),
             tests: [...(testsOf.get(i) ?? [])].sort((a, b) => a - b),
+            ...(linkedBy.has(i) ? { linkedBy: [...(linkedBy.get(i) as Set<string>)].sort() } : {}),
         };
     });
+    const providers: MapProvider[] = (graph.providers ?? []).map((p) => {
+        const row = catalogRow(p.id);
+        return { id: p.id, name: row?.name ?? p.id, status: row?.status ?? 'uncatalogued', roots: p.roots };
+    });
 
     let diff: MapDiff | undefined;
     if (inputs.diff) {
@@ -599,6 +670,7 @@ export function buildMapModel(graph: CodeGraph, inputs: MapInputs = {}): MapMode
         guessEdges,
         areas,
         areaEdges,
+        ...(providers.length > 0 ? { providers } : {}),
         ...(diff ? { diff } : {}),
         ...(artefacts ? { artefacts } : {}),
         analyses: {
@@ -623,6 +695,9 @@ export function buildMapModel(graph: CodeGraph, inputs: MapInputs = {}): MapMode
  * tables. Read off the overlay's edges only; a route whose handler did not
  * resolve keeps `handler: -1` rather than a guess.
  */
+/** How many calls deep a request path follows the handler: handler → service → repository → model. */
+const REQUEST_HOPS = 3;
+
 function collectRequestPaths(graph: CodeGraph, idx: ReadonlyMap<string, number>): RequestPath[] {
     const nodeById = new Map(graph.nodes.map((n) => [n.id, n] as const));
     const out = new Map<string, CodeGraph['edges']>();
@@ -648,20 +723,37 @@ function collectRequestPaths(graph: CodeGraph, idx: ReadonlyMap<string, number>)
         const views = new Set<number>();
         const models = new Set<number>();
         const tables = new Set<string>();
+        const inferred = new Set<string>();
         if (target) {
-            // The handler method's own links, plus what its file imports:
-            // a controller names its models in `use` lines, not in calls the
-            // extractor can bind.
-            const handlerFile = nodeById.get(target)?.source_file;
-            const reach = [...(out.get(target) ?? []), ...(handlerFile ? (out.get(handlerFile) ?? []) : [])];
-            for (const e of reach) {
-                if (!isStatedResolution(e.resolved_via as ResolvedVia)) continue;
-                if (e.relation === 'renders') views.add(fileIdx(e.target));
-                const modelTables = tableOf.get(e.target);
-                if (modelTables) {
-                    models.add(fileIdx(e.target));
-                    for (const t of modelTables) tables.add(t);
+            // What the handler's own code reaches, up to REQUEST_HOPS calls
+            // deep: a service, its repository, the model. Only functions and
+            // methods are expanded — a class's links would hand every model it
+            // knows to every route it serves. A chain is stated when every hop
+            // is; one hop bound by name alone makes what it reaches inferred.
+            const best = new Map<string, boolean>([[target, true]]);
+            let frontier: Array<[string, boolean]> = [[target, true]];
+            for (let hop = 0; hop < REQUEST_HOPS && frontier.length > 0; hop++) {
+                const next: Array<[string, boolean]> = [];
+                for (const [id, stated] of frontier) {
+                    for (const e of out.get(id) ?? []) {
+                        const sure = isStatedResolution(e.resolved_via as ResolvedVia);
+                        if (!sure && !(e.resolved_via === 'dynamic' && nodeById.has(e.target))) continue;
+                        const chain = stated && sure;
+                        if (e.relation === 'renders' && chain) views.add(fileIdx(e.target));
+                        const model = tableOf.has(e.target) ? e.target : e.target.split('::')[0];
+                        const modelTables = model ? tableOf.get(model) : undefined;
+                        if (modelTables) {
+                            if (chain) models.add(fileIdx(model as string));
+                            for (const t of modelTables) (chain ? tables : inferred).add(t);
+                        }
+                        const kind = nodeById.get(e.target)?.kind;
+                        if (e.relation !== 'calls' || (kind !== 'method' && kind !== 'function')) continue;
+                        if (best.get(e.target) === true || best.get(e.target) === chain) continue;
+                        best.set(e.target, chain);
+                        next.push([e.target, chain]);
+                    }
                 }
+                frontier = next;
             }
         }
         paths.push({
@@ -672,6 +764,7 @@ function collectRequestPaths(graph: CodeGraph, idx: ReadonlyMap<string, number>)
             views: [...views].filter((v) => v >= 0).sort((a, b) => a - b),
             models: [...models].filter((v) => v >= 0).sort((a, b) => a - b),
             tables: [...tables].sort(),
+            inferredTables: [...inferred].filter((t) => !tables.has(t)).sort(),
         });
     }
     return paths.sort((a, b) => (a.route < b.route ? -1 : a.route > b.route ? 1 : a.file - b.file));