@event4u/agent-config 17.3.0 → 17.4.0

package/src/scripts/code_graph/providers/catalog.ts

@@ -62,11 +62,11 @@ export const CATALOG: readonly CatalogRow[] = [
         name: 'Spring Boot',
         language: 'Java',
         markers: 'pom.xml / build.gradle names spring-boot',
-        relations: ['routes-to', 'persists', 'relates', 'injects'],
+        relations: ['routes-to', 'persists', 'relates', 'injects', 'renders'],
         status: 'partial',
         fixture: 'tests/fixtures/code-graph/spring',
         usage: SO,
-        limits: '@Entity(name) is not read; a method @RequestMapping without method= is skipped; Kotlin is not covered.',
+        limits: '@Entity(name) is not read; a method @RequestMapping without method= is skipped; a view name built at runtime or held outside the file is not followed; Kotlin is not covered.',
     },
     {
         id: 'go-http',
@@ -132,7 +132,7 @@ export const CATALOG: readonly CatalogRow[] = [
         status: 'partial',
         fixture: 'tests/fixtures/code-graph/django',
         usage: SO,
-        limits: 'include() prefixes and class-based view template_name are not followed.',
+        limits: 'Class-based view template_name and include() of an attribute (admin.site.urls) are not followed.',
     },
     {
         id: 'sqlalchemy',
@@ -244,10 +244,19 @@ export const CATALOG: readonly CatalogRow[] = [
         usage: SO,
         limits: 'MapControllerRoute tables, a view name held in a variable and primary constructors are not followed.',
     },
+    {
+        id: 'rails',
+        name: 'Ruby on Rails',
+        language: 'Ruby',
+        markers: 'a Gemfile declaring the rails gem',
+        relations: ['routes-to', 'persists', 'relates', 'migrates', 'renders'],
+        status: 'partial',
+        fixture: 'tests/fixtures/code-graph/rails',
+        usage: SO,
+        limits: 'resource (singular), nested resources, scope/concerns, an explicit render, config/initializers/inflections and models outside app/models are not followed.',
+    },
     ...(
         [
-            ['ruby', 'Ruby', 'Ruby'],
-            ['rails', 'Ruby on Rails', 'Ruby'],
             ['kotlin', 'Kotlin', 'Kotlin'],
             ['rust', 'Rust', 'Rust'],
             ['c-cpp', 'C / C++', 'C / C++'],

package/src/scripts/code_graph/providers/django.ts

@@ -9,7 +9,9 @@
  *
  * A view is resolved the way the urls file names it: a same-file or imported
  * symbol, or `module.member` through a module the file imports. `include(...)`
- * is not followed, so routes of an included urls module carry no prefix; an
+ * of a dotted string, a `(module, namespace)` tuple or an imported module is
+ * followed: an included module's routes carry every prefix chain that reaches
+ * it from a URLconf nothing includes, and appear under no other path. An
  * inline lambda gets a route with no target. A template found in two template
  * folders, or built at runtime, draws nothing. The app label is the model file's
  * directory (its parent for a `models/` package) unless `Meta.app_label` says
@@ -21,7 +23,7 @@ import type { CodeNode } from '../types.js';
 import { markerRoots, pythonRoots, union } from './shared/detect.js';
 import { joinRoute, templateRoots } from './shared/extractors.js';
 import { lineIndex, makeKit } from './shared/kit.js';
-import { balanced, classBases, importedModules, kwargString, spanText, splitArgs, stringLiteral } from './shared/python.js';
+import { balanced, classBases, importedModules, kwargString, resolveModule, spanText, splitArgs, stringLiteral } from './shared/python.js';
 import type { ConventionProvider } from './types.js';
 
 const RELATION = /\b(?:models\.)?(?:ForeignKey|ManyToManyField|OneToOneField)\s*\(/g;
@@ -47,8 +49,14 @@ export const djangoProvider: ConventionProvider = {
         const inventory = new Set(kit.paths);
         const py = kit.filesWithExt('.py');
 
-        // Routes.
-        for (const f of py.filter((x) => path.posix.basename(x.path) === 'urls.py')) {
+        // Routes. Every URLconf is read once; `include()` links a parent to the
+        // module it names, and each route is emitted once per prefix chain that
+        // reaches its file from a URLconf nothing includes.
+        interface UrlRoute { path: string; view: string; line: number }
+        interface UrlConf { file: string; routes: UrlRoute[]; includes: Array<{ path: string; child: string }> }
+        const confs = new Map<string, UrlConf & { resolve: (expr: string) => string | null }>();
+        const pattern = (literal: string, re: boolean): string => (re ? literal.replace(/^\^/, '').replace(/\$$/, '') : literal);
+        for (const f of py.filter((x) => path.posix.basename(x.path) === 'urls.py' || /^urlpatterns\s*[:=]/m.test(x.source))) {
             const at = lineIndex(f.source);
             const modules = importedModules(f.path, f.source, kit.roots, inventory);
             const resolve = (expr: string): string | null => {
@@ -62,15 +70,50 @@ export const djangoProvider: ConventionProvider = {
                 const cls = kit.resolveName(f.path, head);
                 return cls ? kit.methodOf(cls, member) : null;
             };
+            /** The module an `include(...)` argument names: `"a.urls"`, `("a.urls", "ns")`, or an imported module. */
+            const includeTarget = (view: string): string | null => {
+                const open = view.indexOf('(');
+                let first = splitArgs(balanced(view, open))[0] ?? '';
+                if (first.startsWith('(') || first.startsWith('[')) first = splitArgs(balanced(first, 0))[0] ?? '';
+                const dotted = stringLiteral(first);
+                if (dotted !== null) return resolveModule(f.path, dotted, kit.roots, inventory);
+                return /^\w+$/.test(first) ? (modules.get(first) ?? null) : null;
+            };
+            const conf: UrlConf & { resolve: typeof resolve } = { file: f.path, routes: [], includes: [], resolve };
             for (const m of f.source.matchAll(/\b(path|re_path)\s*\(/g)) {
                 const args = splitArgs(balanced(f.source, (m.index as number) + m[0].length - 1));
                 const literal = stringLiteral(args[0] ?? '');
                 const view = args[1];
-                if (literal === null || view === undefined || /^include\s*\(/.test(view)) continue;
-                const routePath = m[1] === 're_path' ? literal.replace(/^\^/, '').replace(/\$$/, '') : literal;
-                const id = kit.route(f.path, 'ANY', joinRoute(routePath), at(m.index as number));
-                const target = resolve(view);
-                if (target) kit.emit(id, target, 'routes-to', 'route-table');
+                if (literal === null || view === undefined) continue;
+                const routePath = pattern(literal, m[1] === 're_path');
+                if (/^include\s*\(/.test(view)) {
+                    const child = includeTarget(view);
+                    if (child) conf.includes.push({ path: routePath, child });
+                    continue;
+                }
+                conf.routes.push({ path: routePath, view, line: at(m.index as number) });
+            }
+            confs.set(f.path, conf);
+        }
+        const included = new Set([...confs.values()].flatMap((c) => c.includes.map((i) => i.child)));
+        const prefixes = new Map<string, Set<string>>();
+        const walk = (file: string, prefix: string, stack: readonly string[]): void => {
+            const conf = confs.get(file);
+            if (!conf || stack.includes(file)) return;
+            const seen = prefixes.get(file) ?? new Set<string>();
+            if (seen.has(prefix)) return;
+            seen.add(prefix);
+            prefixes.set(file, seen);
+            for (const inc of conf.includes) walk(inc.child, joinRoute(prefix, inc.path), [...stack, file]);
+        };
+        for (const file of confs.keys()) if (!included.has(file)) walk(file, '', []);
+        for (const conf of confs.values()) {
+            for (const prefix of prefixes.get(conf.file) ?? []) {
+                for (const r of conf.routes) {
+                    const id = kit.route(conf.file, 'ANY', joinRoute(prefix, r.path), r.line);
+                    const target = conf.resolve(r.view);
+                    if (target) kit.emit(id, target, 'routes-to', 'route-table');
+                }
             }
         }
 

package/src/scripts/code_graph/providers/index.ts

@@ -19,6 +19,7 @@ import { nuxtProvider } from './nuxt.js';
 import { reactRouterProvider } from './react-router.js';
 import { springProvider } from './spring.js';
 import { sqlalchemyProvider } from './sqlalchemy.js';
+import { railsProvider } from './rails.js';
 import { sveltekitProvider } from './sveltekit.js';
 import { symfonyProvider } from './symfony.js';
 import { typeormProvider } from './typeorm.js';
@@ -51,6 +52,7 @@ export const PROVIDERS: readonly ConventionProvider[] = [
     sveltekitProvider,
     typeormProvider,
     aspnetcoreProvider,
+    railsProvider,
 ];
 
 /** Every marker basename a registered provider asks the probe to record. */

package/src/scripts/code_graph/providers/rails.ts

@@ -0,0 +1,204 @@
+/**
+ * Ruby on Rails: the links a Rails application makes by convention.
+ *
+ *   config/routes.rb   get '/x', to: 'users#index' · post 'x' => 'users#create'
+ *                      · root 'pages#home' · resources :users, only:/except:
+ *                      · namespace :admin do … end         route --routes-to--> the action
+ *   app/models         class User < ApplicationRecord     class --persists--> table:users
+ *                      self.table_name = "t" wins; a subclass of a model shares its table (STI)
+ *   app/models         has_many / has_one / belongs_to (class_name: wins)   class --relates--> model
+ *   db/migrate         create_table :t                    file  --migrates--> table:t
+ *   a controller action  app/views/<controller>/<action>.*   action --renders--> the view
+ *
+ * `resources` expands into the seven REST actions the controller actually
+ * defines, within `only:` / `except:`; an explicit route keeps its node when
+ * the action is missing. The table name is the class in snake_case, pluralised
+ * by the common English rules plus Rails' irregulars; an `inflections` file is
+ * not read. Not followed: `resource` (singular), nested `resources` blocks,
+ * `scope` / `constraints`, `concerns`, an explicit `render`, and a model
+ * outside `app/models`.
+ */
+import * as path from 'node:path';
+
+import type { CodeNode } from '../types.js';
+import { gemRoots } from './shared/detect.js';
+import { joinRoute } from './shared/extractors.js';
+import { type Kit, lineIndex, makeKit } from './shared/kit.js';
+import type { ConventionProvider } from './types.js';
+
+const REST: ReadonlyArray<[action: string, verb: string, suffix: string]> = [
+    ['index', 'GET', ''],
+    ['new', 'GET', 'new'],
+    ['create', 'POST', ''],
+    ['show', 'GET', ':id'],
+    ['edit', 'GET', ':id/edit'],
+    ['update', 'PATCH', ':id'],
+    ['destroy', 'DELETE', ':id'],
+];
+const IRREGULAR: Readonly<Record<string, string>> = { person: 'people', man: 'men', woman: 'women', child: 'children', mouse: 'mice' };
+const VERB_ROUTE = /^\s*(get|post|put|patch|delete)\s+['"]([^'"]*)['"]\s*(?:,\s*to:\s*|=>\s*)['"](\w[\w/]*)#(\w+)['"]/;
+const ROOT_ROUTE = /^\s*root\s+(?:to:\s*)?['"](\w[\w/]*)#(\w+)['"]/;
+const RESOURCES = /^\s*resources\s+:(\w+)(.*)$/;
+const NAMESPACE = /^\s*namespace\s+:(\w+)\s+do\b/;
+const OPENS_BLOCK = /\bdo(\s*\|[^|]*\|)?\s*$/;
+
+function snake(name: string): string {
+    return name.replace(/([a-z\d])([A-Z])/g, '$1_$2').replace(/([A-Z]+)([A-Z][a-z])/g, '$1_$2').toLowerCase();
+}
+
+function pluralize(word: string): string {
+    const head = word.slice(0, word.lastIndexOf('_') + 1);
+    const last = word.slice(head.length);
+    if (IRREGULAR[last]) return head + IRREGULAR[last];
+    if (/[^aeiou]y$/.test(last)) return head + last.slice(0, -1) + 'ies';
+    if (/(s|x|z|ch|sh)$/.test(last)) return head + last + 'es';
+    return head + last + 's';
+}
+
+function singularize(word: string): string {
+    for (const [one, many] of Object.entries(IRREGULAR)) if (word === many) return one;
+    if (/ies$/.test(word)) return word.slice(0, -3) + 'y';
+    if (/(s|x|z|ch|sh)es$/.test(word)) return word.slice(0, -2);
+    return word.endsWith('s') ? word.slice(0, -1) : word;
+}
+
+function camel(snakeName: string): string {
+    return snakeName.replace(/(^|_)([a-z\d])/g, (_m, _s, c: string) => c.toUpperCase());
+}
+
+/** The action method of the controller `ctrl` (`admin/reports`) under `root`, if the controller defines it. */
+function action(kit: Kit, root: string, ctrl: string, name: string): CodeNode | null {
+    const file = path.posix.join(root, 'app/controllers', `${ctrl}_controller.rb`);
+    return kit.nodesInFile(file).find((n) => n.kind === 'method' && n.label === name) ?? null;
+}
+
+function routes(kit: Kit, root: string): void {
+    const file = path.posix.join(root, 'config/routes.rb');
+    const src = kit.files.find((f) => f.path === file)?.source;
+    if (src === undefined) return;
+    // One frame per open `do` block: a namespace adds a path and a controller
+    // directory; any other block only keeps `end` balanced.
+    const frames: Array<string | null> = [];
+    const ns = (): string[] => frames.filter((f): f is string => f !== null);
+    const declare = (verb: string, routePath: string, ctrl: string, act: string, line: number, keepWithoutAction: boolean): void => {
+        const target = action(kit, root, [...ns(), ctrl].join('/'), act);
+        if (!target && !keepWithoutAction) return;
+        const id = kit.route(file, verb, joinRoute(...ns(), routePath), line);
+        if (target) kit.emit(id, target.id, 'routes-to', 'route-table');
+    };
+    src.split('\n').forEach((raw, i) => {
+        const line = i + 1;
+        // Whole-line comments only: `#` is also the controller#action separator.
+        if (/^\s*#/.test(raw)) return;
+        const text = raw;
+        if (/^\s*end\b/.test(text)) {
+            frames.pop();
+            return;
+        }
+        let m = NAMESPACE.exec(text);
+        if (m) {
+            frames.push(m[1] as string);
+            return;
+        }
+        if ((m = ROOT_ROUTE.exec(text))) declare('GET', '/', m[1] as string, m[2] as string, line, true);
+        else if ((m = VERB_ROUTE.exec(text))) declare((m[1] as string).toUpperCase(), m[2] as string, m[3] as string, m[4] as string, line, true);
+        else if ((m = RESOURCES.exec(text))) {
+            const name = m[1] as string;
+            const opts = m[2] as string;
+            const list = (key: string): string[] | null => {
+                const hit = new RegExp(`\\b${key}:\\s*\\[([^\\]]*)\\]`).exec(opts) ?? new RegExp(`\\b${key}:\\s*:(\\w+)`).exec(opts);
+                return hit ? [...(hit[1] as string).matchAll(/:?(\w+)/g)].map((x) => x[1] as string) : null;
+            };
+            const only = list('only');
+            const except = list('except') ?? [];
+            for (const [act, verb, suffix] of REST) {
+                if ((only && !only.includes(act)) || except.includes(act)) continue;
+                declare(verb, joinRoute(name, suffix), name, act, line, false);
+            }
+        }
+        if (OPENS_BLOCK.test(text)) frames.push(null);
+    });
+}
+
+function models(kit: Kit, root: string): void {
+    const dir = path.posix.join(root, 'app/models') + '/';
+    const files = kit.filesWithExt('.rb').filter((f) => f.path.startsWith(dir));
+    const classes = files.flatMap((f) =>
+        kit.nodesInFile(f.path).filter((n): n is CodeNode => n.kind === 'class').map((node) => {
+            const head = f.source.split('\n')[(node.source_location[0] as number) - 1] ?? '';
+            const parent = /<\s*([\w:]+)/.exec(head)?.[1]?.split('::').pop() ?? '';
+            const span = f.source.split('\n').slice((node.source_location[0] as number) - 1, node.source_location[2] as number).join('\n');
+            return { node, file: f, parent, span };
+        }),
+    );
+    const byName = new Map(classes.map((c) => [c.node.label, c] as const));
+    const tableOf = new Map<string, string | null>();
+    const resolveTable = (name: string, seen: Set<string> = new Set()): string | null => {
+        if (tableOf.has(name)) return tableOf.get(name) as string | null;
+        const c = byName.get(name);
+        if (!c || seen.has(name)) return null;
+        seen.add(name);
+        const explicit = /self\.table_name\s*=\s*['"]([^'"]+)['"]/.exec(c.span)?.[1];
+        const abstract = /self\.abstract_class\s*=\s*true/.test(c.span);
+        let table: string | null = null;
+        if (explicit) table = explicit;
+        else if (abstract) table = null;
+        else if (c.parent === 'ApplicationRecord' || c.parent === 'Base') table = pluralize(snake(name));
+        else if (byName.has(c.parent)) table = resolveTable(c.parent, seen);
+        tableOf.set(name, table);
+        return table;
+    };
+    for (const c of classes) {
+        const table = resolveTable(c.node.label);
+        if (table) kit.emit(c.node.id, kit.table(table, c.file.path, c.node.source_location[0] as number), 'persists', 'schema-call');
+        for (const m of c.span.matchAll(/^\s*(has_many|has_one|belongs_to|has_and_belongs_to_many)\s+:(\w+)([^\n]*)/gm)) {
+            const named = /class_name:\s*['"]([\w:]+)['"]/.exec(m[3] as string)?.[1]?.split('::').pop();
+            const assoc = m[2] as string;
+            const target = byName.get(named ?? camel(m[1] === 'has_many' || m[1] === 'has_and_belongs_to_many' ? singularize(assoc) : assoc));
+            if (target && target.node.id !== c.node.id) kit.emit(c.node.id, target.node.id, 'relates', 'orm-relation');
+        }
+    }
+}
+
+function migrations(kit: Kit, root: string): void {
+    const dir = path.posix.join(root, 'db/migrate') + '/';
+    for (const f of kit.filesWithExt('.rb').filter((x) => x.path.startsWith(dir))) {
+        const at = lineIndex(f.source);
+        for (const m of f.source.matchAll(/\bcreate_table\s+(?::(\w+)|['"]([^'"]+)['"])/g)) {
+            const table = (m[1] ?? m[2]) as string;
+            kit.emit(f.path, kit.table(table, f.path, at(m.index as number)), 'migrates', 'schema-call');
+        }
+    }
+}
+
+function views(kit: Kit, root: string): void {
+    const ctrlDir = path.posix.join(root, 'app/controllers') + '/';
+    const viewDir = path.posix.join(root, 'app/views');
+    for (const f of kit.filesWithExt('.rb').filter((x) => x.path.startsWith(ctrlDir) && x.path.endsWith('_controller.rb'))) {
+        const ctrl = f.path.slice(ctrlDir.length, -'_controller.rb'.length);
+        for (const n of kit.nodesInFile(f.path)) {
+            if (n.kind !== 'method') continue;
+            const prefix = `${viewDir}/${ctrl}/${n.label}.`;
+            const hits = kit.paths.filter((p) => p.startsWith(prefix) && !p.slice(prefix.length).includes('/'));
+            if (hits.length !== 1) continue;
+            const target = hits[0] as string;
+            kit.fileNode(target);
+            kit.emit(n.id, target, 'renders', 'directive-scan');
+        }
+    }
+}
+
+export const railsProvider: ConventionProvider = {
+    id: 'rails',
+    detect: (probe) => gemRoots(probe, 'rails'),
+    build: (input) => {
+        const kit = makeKit(input);
+        for (const root of kit.roots) {
+            routes(kit, root);
+            models(kit, root);
+            migrations(kit, root);
+            views(kit, root);
+        }
+        return kit.result();
+    },
+};

package/src/scripts/code_graph/providers/spring.ts

@@ -6,6 +6,8 @@
  *   @Entity class, @Table(name = "t") or the default      class --persists--> table:t
  *   interface R extends JpaRepository<E, Id>              R     --relates-->  E
  *   @Autowired field · constructor parameter              class --injects-->  the in-repo type
+ *   @Controller method `return "a/b"` · ModelAndView("a/b")
+ *       · a same-file `static final String` constant         method --renders--> templates/a/b.html
  *
  * The Java extractor spans a method or class from its first annotation, so a
  * mapping annotation belongs to the method whose span holds it; one outside
@@ -13,7 +15,10 @@
  * table is Spring Boot's default physical name: the entity class in snake_case
  * (`OrderLine` → `order_line`); `@Entity(name = "X")` is not read. A method-level
  * `@RequestMapping` without `method =` and a constructor of a class carrying no
- * stereotype annotation are not followed.
+ * stereotype annotation are not followed. A view name is read only in a
+ * `@Controller` file — a `@RestController` returns response bodies — and never
+ * from a `redirect:` / `forward:`; it renders the one template of that name
+ * under the Thymeleaf, FreeMarker, Mustache or JSP folders, or nothing.
  */
 import { jvmRoots } from './shared/detect.js';
 import { joinRoute, tableMapping } from './shared/extractors.js';
@@ -119,6 +124,37 @@ function injections(kit: Kit): void {
     }
 }
 
+const VIEW_ROOTS = ['src/main/resources/templates', 'src/main/webapp/WEB-INF/views', 'src/main/webapp/WEB-INF/jsp'];
+const VIEW_EXTS = ['.html', '.ftlh', '.ftl', '.mustache', '.jte', '.jsp'];
+const VIEW_NAME = /\b(?:return\s+|new\s+ModelAndView\s*\(\s*)(?:"(?<lit>[^"]*)"|(?<const>[A-Z][A-Z0-9_]*))\s*[;),]/g;
+const VIEW_CONSTANT = /\bstatic\s+final\s+String\s+(?<name>[A-Z][A-Z0-9_]*)\s*=\s*"(?<value>[^"]*)"/g;
+
+function views(kit: Kit): void {
+    const inventory = new Set(kit.paths);
+    for (const f of kit.filesWithExt('.java')) {
+        if (!/@Controller\b/.test(f.source)) continue;
+        const at = lineIndex(f.source);
+        const constants = new Map([...f.source.matchAll(VIEW_CONSTANT)].map((m) => [m.groups?.['name'] as string, m.groups?.['value'] as string]));
+        for (const m of f.source.matchAll(VIEW_NAME)) {
+            const name = m.groups?.['lit'] ?? constants.get(m.groups?.['const'] ?? '');
+            if (!name || /^(?:redirect|forward):/.test(name)) continue;
+            const method = methodAt(kit, f.path, at(m.index as number));
+            if (!method) continue;
+            const hits = new Set<string>();
+            for (const r of kit.roots)
+                for (const dir of VIEW_ROOTS)
+                    for (const ext of VIEW_EXTS) {
+                        const c = [r, dir, `${name.replace(/^\/+/, '')}${ext}`].filter(Boolean).join('/');
+                        if (inventory.has(c)) hits.add(c);
+                    }
+            if (hits.size !== 1) continue;
+            const target = [...hits][0] as string;
+            kit.fileNode(target);
+            kit.emit(method.id, target, 'renders', 'directive-scan');
+        }
+    }
+}
+
 export const springProvider: ConventionProvider = {
     id: 'spring',
     detect: (probe) => jvmRoots(probe, /spring-boot|org\.springframework\.boot/),
@@ -133,6 +169,7 @@ export const springProvider: ConventionProvider = {
         });
         repositories(kit);
         injections(kit);
+        views(kit);
         return kit.result();
     },
 };

package/src/scripts/code_graph/query.ts

@@ -13,7 +13,6 @@ import {
     emitSqliteTwin,
     type GraphIndex,
     INDEXED_READ_MIN_EDGES,
-    loadSerializedFromTwin,
     openGraphIndex,
 } from './sqlite_store.js';
 import type { CodeEdge, CodeGraph, CodeNode, Relation } from './types.js';
@@ -132,6 +131,9 @@ export function loadGraph(graphPath: string, source = graphPath): LoadedGraph {
     // used to be preferred and still returned the entire serialization, which
     // made it a cheaper blob transport rather than an index.
     const index = openGraphIndex(graphPath);
+    // `openGraphIndex` declines on exactly the conditions under which the twin
+    // is stale, absent or corrupt — so a handle here means it needs no re-emit.
+    const twinCurrent = index !== null;
     if (index) {
         if (index.edgeCount >= INDEXED_READ_MIN_EDGES) return indexBackedGraph(index, source, graphPath);
         // Small graph: the in-memory path is cheaper. Release the handle rather
@@ -139,12 +141,10 @@ export function loadGraph(graphPath: string, source = graphPath): LoadedGraph {
         index.close();
     }
 
-    // Prefer the derived SQLite twin (ADR-129): checksum/stat-verified against
-    // the canonical JSON, byte-identical content, ~1/90 the load cost at
-    // consumer scale. Fallback = parse the JSON — and best-effort re-emit the
-    // twin from it (zero-touch rebuild-on-drift, Phase 7).
-    const fromTwin = loadSerializedFromTwin(graphPath);
-    const raw = fromTwin ?? fs.readFileSync(graphPath, 'utf-8');
+    // Below the threshold the JSON is parsed. The twin no longer carries a
+    // second copy of it to read instead; a missing or stale twin is re-emitted
+    // below (zero-touch rebuild-on-drift, ADR-129 Phase 7).
+    const raw = fs.readFileSync(graphPath, 'utf-8');
     const parsed = JSON.parse(raw) as unknown;
     // A consumer's own graph file, written by another tool, is DETECTED by
     // `detect.ts` and used to throw here — detected-but-unloadable, the worst
@@ -166,8 +166,8 @@ export function loadGraph(graphPath: string, source = graphPath): LoadedGraph {
     // The twin is a cache of a file's bytes keyed on its own checksum. An
     // adapted graph's bytes are not the file's, so emitting one would cache a
     // derivation under the source's identity.
-    if (fromTwin === null && !foreignAdapted) {
-        emitSqliteTwin(graph, raw, graphPath);
+    if (!twinCurrent && !foreignAdapted) {
+        emitSqliteTwin(graph, graphPath);
     }
     const byId = new Map(graph.nodes.map((n) => [n.id, n]));
     const outM = new Map<string, CodeEdge[]>();

package/src/scripts/code_graph/refresh_lock.ts

@@ -20,9 +20,8 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 
-export const LOCK_REL = path.join('agents', 'runtime', 'state', 'code-graph-refresh.lock');
-/** Written by `code-graph auto-refresh on`; the session concern acts only while it exists. */
-export const AUTO_REFRESH_REL = path.join('agents', 'runtime', 'state', 'code-graph-auto-refresh.json');
+import { graphHome } from './graph_home.js';
+
 export const STALE_LOCK_MS = 5 * 60 * 1000;
 /**
  * How long an owner on ANOTHER host (a container sharing the checkout) is
@@ -54,12 +53,17 @@ export interface RefreshRecord {
 
 /** One file per side, so the session concern writes without reading or merging anything. */
 export const refreshRecordPath = (root: string, by: RefreshRecord['by']): string =>
-    path.join(root, path.dirname(LOCK_REL), `code-graph-refresh.${by}.json`);
+    path.join(path.dirname(graphHome(root).lockPath), `code-graph-refresh.${by}.json`);
 
 /** The last outcome of one side, so a refresh that never happens is visible. Best-effort. */
 export function recordRefresh(root: string, rec: Omit<RefreshRecord, 'at'>): void {
+    recordRefreshIn(path.dirname(graphHome(root).lockPath), rec);
+}
+
+/** For the session concern: its chunk must not carry the user-global resolver. */
+export function recordRefreshIn(stateDir: string, rec: Omit<RefreshRecord, 'at'>): void {
     try {
-        fs.writeFileSync(refreshRecordPath(root, rec.by), JSON.stringify({ at: new Date().toISOString(), ...rec }));
+        fs.writeFileSync(path.join(stateDir, `code-graph-refresh.${rec.by}.json`), JSON.stringify({ at: new Date().toISOString(), ...rec }));
     } catch {
         /* never fails a refresh */
     }
@@ -77,7 +81,7 @@ export function readRefreshRecords(root: string): Partial<Record<RefreshRecord['
     return out;
 }
 
-function pidAlive(pid: number): boolean {
+export function pidAlive(pid: number): boolean {
     try {
         process.kill(pid, 0);
         return true;
@@ -143,7 +147,7 @@ export const reclaimMutexPath = (lock: string): string => `${lock}.reclaim`;
 
 /** True when this process holds the lock (the CLI took it before calling in). */
 export function heldByThisProcess(root: string): boolean {
-    const owner = readOwner(path.join(root, LOCK_REL));
+    const owner = readOwner(graphHome(root).lockPath);
     return typeof owner !== 'string' && owner.pid === process.pid;
 }
 
@@ -162,7 +166,7 @@ export function heldByThisProcess(root: string): boolean {
  * `afterStaleCheck` exists for the interleaving test only.
  */
 export function acquire(root: string, afterStaleCheck?: () => void): (() => void) | null {
-    const lock = path.join(root, LOCK_REL);
+    const lock = graphHome(root).lockPath;
     fs.mkdirSync(path.dirname(lock), { recursive: true });
     try {
         fs.mkdirSync(lock);