@event4u/agent-config 14.17.0 → 14.19.0

package/src/scripts/code_graph/extract.ts

@@ -36,6 +36,37 @@ export interface RawEdge {
     enclosingClassId?: string;
     /** scope token for `Scope::m()` scoped calls (a class name / self / static). */
     scopeName?: string;
+    /**
+     * `imports` only: the module specifier as written (`'./types.js'`,
+     * `'node:path'`), stripped of its quotes.
+     *
+     * Before this field the extractor read the import CLAUSE and threw the
+     * `from` away, so the build pass had nothing to resolve against but a
+     * repo-wide same-name table — which is how `import * as path from
+     * 'node:path'` came to bind to this repository's own `path()` function in
+     * `query.ts`, at `EXTRACTED`, in four of eleven files. The specifier is the
+     * one piece of evidence that says WHERE the name came from, and it is in
+     * the source text; discarding it turned a syntactic fact into a guess.
+     *
+     * Absent for PHP `use`, which names a fully-qualified symbol rather than a
+     * module path — those still resolve by name, and the build pass labels them
+     * accordingly.
+     */
+    moduleSpecifier?: string;
+    /**
+     * `imports` only: which import form produced this binding. `namespace`
+     * (`import * as x`) and `default` bind the MODULE (or its default export),
+     * never a named export, so neither may be matched against a same-named
+     * symbol inside the target file.
+     */
+    importKind?: 'namespace' | 'named' | 'default';
+    /**
+     * `imports` only: the LOCAL binding name, when it differs from
+     * `targetName` (`import { foo as bar }` → targetName `foo`, localName
+     * `bar`). The file's scope is keyed on the local name; the target file is
+     * searched for the remote one.
+     */
+    localName?: string;
 }
 
 export interface FileExtract {
@@ -245,29 +276,101 @@ function extractPhp(root: TsNode, file: string, out: FileExtract): void {
 
 // ── TypeScript / JavaScript ───────────────────────────────────────────────────
 
+/**
+ * Node types that open a new function or class scope. A `const` inside one of
+ * these is a LOCAL variable, not a module-level declaration, and emitting a
+ * node for it would put every loop counter in the symbol table — the
+ * count-inflation failure `2.1` is explicitly not allowed to cause.
+ */
+const TS_SCOPE_INTRODUCERS = new Set([
+    'arrow_function',
+    'function_expression',
+    'function_declaration',
+    'generator_function',
+    'generator_function_declaration',
+    'method_definition',
+    'class_declaration',
+    'class',
+    'class_body',
+]);
+
 function extractTsJs(root: TsNode, file: string, out: FileExtract): void {
     const fileId = file;
 
-    const walk = (n: TsNode, classId: string | null, scopeId: string): void => {
+    const walk = (n: TsNode, classId: string | null, scopeId: string, topLevel: boolean): void => {
+        // A declaration is module-level until the walk descends through a
+        // function or class scope; from there down it is a local.
+        const inner = topLevel && !TS_SCOPE_INTRODUCERS.has(n.type);
         switch (n.type) {
             case 'import_statement': {
+                const src = n.childForFieldName('source');
+                // The specifier node is a `string`; its text carries the quotes.
+                const specifier = src ? src.text.replace(/^['"`]/, '').replace(/['"`]$/, '') : undefined;
                 const clause = firstNamed(n, new Set(['import_clause']));
+                const emitImport = (
+                    remote: string,
+                    local: string,
+                    importKind: 'namespace' | 'named' | 'default',
+                ): void => {
+                    out.rawEdges.push({
+                        sourceId: fileId,
+                        relation: 'imports',
+                        targetName: baseName(remote),
+                        confidenceHint: 'EXTRACTED',
+                        ...(specifier === undefined ? {} : { moduleSpecifier: specifier }),
+                        importKind,
+                        ...(local === remote ? {} : { localName: local }),
+                    });
+                };
                 if (clause) {
-                    for (const spec of namedChildren(clause)) {
-                        for (const idn of [spec, ...namedChildren(spec)])
-                            if (idn.type === 'identifier' || idn.type === 'import_specifier') {
-                                const nm = idn.type === 'import_specifier' ? nameField(idn) ?? idn.text : idn.text;
-                                out.rawEdges.push({
-                                    sourceId: fileId,
-                                    relation: 'imports',
-                                    targetName: baseName(nm),
-                                    confidenceHint: 'EXTRACTED',
-                                });
+                    for (const child of namedChildren(clause)) {
+                        if (child.type === 'namespace_import') {
+                            // `import * as path from 'node:path'` — the binding
+                            // is the MODULE. Matching `path` against a local
+                            // symbol of the same name is the false edge 1.1
+                            // exists to remove.
+                            const idn = firstNamed(child, new Set(['identifier']));
+                            if (idn) emitImport(idn.text, idn.text, 'namespace');
+                        } else if (child.type === 'named_imports') {
+                            for (const sp of namedChildren(child)) {
+                                if (sp.type !== 'import_specifier') continue;
+                                const nameNode = sp.childForFieldName('name');
+                                const aliasNode = sp.childForFieldName('alias');
+                                const remote = nameNode ? nameNode.text : sp.text;
+                                emitImport(remote, aliasNode ? aliasNode.text : remote, 'named');
                             }
+                        } else if (child.type === 'identifier') {
+                            emitImport(child.text, child.text, 'default');
+                        }
                     }
                 }
                 return;
             }
+            // `const`, `type`, `interface`, `enum` — the shapes the v2 corpus
+            // asks `references` questions about (`EXT_LANG` is a const,
+            // `SettingsClass` a type alias). The extractor used to emit none of
+            // them, which is the named mechanical cause of `references` recall
+            // 0.333 against grep's 1.000.
+            //
+            // The body is not walked: a type or interface position holds no
+            // call sites, and an enum body holds member names rather than
+            // symbols this graph answers questions about.
+            case 'interface_declaration':
+            case 'type_alias_declaration':
+            case 'enum_declaration': {
+                const nmNode = n.childForFieldName('name') ?? firstNamed(n, NAME_TYPES);
+                const nm = nmNode ? nmNode.text : '<anon>';
+                const kind =
+                    n.type === 'interface_declaration'
+                        ? 'interface'
+                        : n.type === 'type_alias_declaration'
+                          ? 'type'
+                          : 'enum';
+                const id = `${file}#${nm}`;
+                out.nodes.push({ id, label: nm, kind, source_file: file, source_location: loc(n) });
+                out.rawEdges.push({ sourceId: fileId, relation: 'member', targetName: nm, confidenceHint: 'EXTRACTED' });
+                return;
+            }
             case 'class_declaration': {
                 const nm = nameField(n) ?? '<anon>';
                 const id = `${file}#${nm}`;
@@ -280,7 +383,7 @@ function extractTsJs(root: TsNode, file: string, out: FileExtract): void {
                             if (idn.type === 'identifier' || idn.type === 'type_identifier')
                                 out.inherits.push({ classId: id, parentName: baseName(idn.text) });
                 const body = n.childForFieldName('body');
-                if (body) for (const c of namedChildren(body)) walk(c, id, id);
+                if (body) for (const c of namedChildren(body)) walk(c, id, id, false);
                 return;
             }
             case 'method_definition': {
@@ -294,7 +397,7 @@ function extractTsJs(root: TsNode, file: string, out: FileExtract): void {
                     confidenceHint: 'EXTRACTED',
                 });
                 const body = n.childForFieldName('body');
-                if (body) for (const c of namedChildren(body)) walk(c, classId, id);
+                if (body) for (const c of namedChildren(body)) walk(c, classId, id, false);
                 return;
             }
             case 'function_declaration': {
@@ -303,7 +406,7 @@ function extractTsJs(root: TsNode, file: string, out: FileExtract): void {
                 out.nodes.push({ id, label: nm, kind: 'function', source_file: file, source_location: loc(n) });
                 out.rawEdges.push({ sourceId: fileId, relation: 'member', targetName: nm, confidenceHint: 'EXTRACTED' });
                 const body = n.childForFieldName('body');
-                if (body) for (const c of namedChildren(body)) walk(c, classId, id);
+                if (body) for (const c of namedChildren(body)) walk(c, classId, id, false);
                 return;
             }
             // Modern TS declares most of its functions as bindings, not as
@@ -313,17 +416,58 @@ function extractTsJs(root: TsNode, file: string, out: FileExtract): void {
             // 170-vs-13,428 TS/PHP symbol gap: the six handled kinds simply do
             // not cover the dominant declaration form.
             //
-            // Scoped deliberately to bindings whose value IS a function. A
-            // `const x = 3` is data, not a symbol this graph answers questions
-            // about, and emitting a node per constant would inflate the count
-            // without improving recall — which is the cosmetic-improvement
-            // failure the phase falsifier exists to catch.
+            // The scoping note that stood here said a `const x = 3` is "data,
+            // not a symbol this graph answers questions about", and that
+            // emitting a node per constant would raise the count without
+            // improving recall. **The v2 benchmark falsified the first half and
+            // the second half no longer follows.** Two of its three
+            // `references` questions probe exactly this shape — `EXT_LANG` (a
+            // const) and `SettingsClass` (a type alias) — and the class scored
+            // recall 0.333 against grep's 1.000 because neither had a node to
+            // resolve to. The count-inflation worry was real and is answered by
+            // SCOPE rather than by refusal: a binding earns a node only at
+            // MODULE level (`topLevel`), so a loop counter inside a function
+            // body still gets none. The reason is kept rather than deleted,
+            // because a reversed decision whose reason disappears gets re-taken.
             case 'lexical_declaration':
             case 'variable_declaration': {
                 for (const d of namedChildren(n)) {
                     if (d.type !== 'variable_declarator') continue;
                     const value = d.childForFieldName('value');
-                    if (!value || (value.type !== 'arrow_function' && value.type !== 'function_expression')) {
+                    const nmNode = d.childForFieldName('name');
+                    const isFn =
+                        value !== null &&
+                        value !== undefined &&
+                        (value.type === 'arrow_function' || value.type === 'function_expression');
+                    const isClassExpr = value?.type === 'class';
+                    if (!isFn) {
+                        // Only a plain `identifier` name: a destructuring
+                        // pattern (`const { a, b } = x`) binds several names and
+                        // none of them is a declaration this graph can id.
+                        if (topLevel && nmNode?.type === 'identifier') {
+                            const nm = nmNode.text;
+                            const id = classId ? `${classId}::${nm}` : `${file}#${nm}`;
+                            out.nodes.push({
+                                id,
+                                label: nm,
+                                // `const Widget = class {}` IS constructible;
+                                // calling it a constant would let the build pass
+                                // reject a `new Widget()` that is perfectly real.
+                                kind: isClassExpr ? 'class' : 'constant',
+                                source_file: file,
+                                source_location: loc(d),
+                            });
+                            out.rawEdges.push({
+                                sourceId: classId ?? fileId,
+                                relation: 'member',
+                                targetName: nm,
+                                confidenceHint: 'EXTRACTED',
+                            });
+                        }
+                        // Non-function declarators still need walking for their
+                        // calls — returning early on the whole declaration
+                        // silently drops call edges from initialisers.
+                        walk(d, classId, scopeId, inner);
                         continue;
                     }
                     const nm = nameField(d) ?? '<anon>';
@@ -353,16 +497,7 @@ function extractTsJs(root: TsNode, file: string, out: FileExtract): void {
                     // can iterate children because a `statement_block` is never
                     // the interesting node; here it often is.
                     const body = value.childForFieldName('body');
-                    if (body) walk(body, classId, id);
-                }
-                // Non-function declarators still need walking for their calls.
-                for (const d of namedChildren(n)) {
-                    if (d.type !== 'variable_declarator') continue;
-                    const value = d.childForFieldName('value');
-                    if (value && (value.type === 'arrow_function' || value.type === 'function_expression')) {
-                        continue;
-                    }
-                    walk(d, classId, scopeId);
+                    if (body) walk(body, classId, id, false);
                 }
                 return;
             }
@@ -388,7 +523,7 @@ function extractTsJs(root: TsNode, file: string, out: FileExtract): void {
                         confidenceHint: 'EXTRACTED',
                     });
                     const body = value.childForFieldName('body');
-                    if (body) walk(body, classId, id);
+                    if (body) walk(body, classId, id, false);
                     return;
                 }
                 break;
@@ -481,11 +616,11 @@ function extractTsJs(root: TsNode, file: string, out: FileExtract): void {
             default:
                 break;
         }
-        for (const c of namedChildren(n)) walk(c, classId, scopeId);
+        for (const c of namedChildren(n)) walk(c, classId, scopeId, inner);
     };
 
     out.nodes.push({ id: fileId, label: file, kind: 'file', source_file: file, source_location: [] });
-    walk(root, null, fileId);
+    walk(root, null, fileId, true);
 }
 
 /**

package/src/scripts/code_graph/types.ts

@@ -21,7 +21,20 @@ export interface CodeNode {
     /** Path-qualified from day one: `<relpath>#<symbol>` (collision-free). */
     id: string;
     label: string;
-    kind: 'file' | 'class' | 'interface' | 'trait' | 'function' | 'method' | 'skipped';
+    /**
+     * `constant` / `type` / `enum` were added by
+     * `road-to-the-graph-that-lies-confidently` 2.1: the v2 benchmark's
+     * `references` class probes a const (`EXT_LANG`) and a type alias
+     * (`SettingsClass`), and neither had a node to resolve to. `interface` is
+     * reused rather than forked — a TS interface and a PHP interface are the
+     * same thing to a caller.
+     *
+     * The kind is also a CAPABILITY claim the build pass reads: a `constant` is
+     * never callable and never constructible, so a bare `foo()` may not resolve
+     * to one by name. `const Widget = class {}` is emitted as `class` for
+     * exactly that reason.
+     */
+    kind: 'file' | 'class' | 'interface' | 'trait' | 'function' | 'method' | 'constant' | 'type' | 'enum' | 'skipped';
     source_file: string;
     /** 1-based [startLine, startCol, endLine, endCol]; [] for synthetic nodes. */
     source_location: readonly number[];
@@ -74,11 +87,33 @@ export interface CodeGraph {
     grammar_abi: number;
     /** per-confidence-class edge counts, so the honesty split is visible. */
     edge_confidence_counts: Record<EdgeConfidence, number>;
+    /**
+     * Edges the build pass REFUSED to emit, by reason. Present so a smaller
+     * edge total cannot be read as a better graph without saying what was
+     * dropped: an engine that quietly deletes its worst edges publishes a
+     * flattering confidence ratio and no evidence.
+     *
+     * `dynamic_no_candidate` — a dynamic member call (`x.push()`) whose method
+     * name matches NO method declared in this repository. The edge could only
+     * ever have pointed at a `symbol:` pseudo-node, which is not a node, so no
+     * query verb could reach it: `affected` and `path` resolve their seeds
+     * against real nodes. It was 257 of 660 edges on this engine's own source.
+     */
+    suppressed_edge_counts: { dynamic_no_candidate: number };
     nodes: CodeNode[];
     edges: CodeEdge[];
 }
 
-export const SCHEMA_VERSION = 1;
+/**
+ * Bumped 1 → 2 by `road-to-the-graph-that-lies-confidently`: `CodeNode.kind`
+ * gained three members, `CodeGraph` gained `suppressed_edge_counts`, and the
+ * per-file extract sidecar gained the import specifier. A cached sidecar
+ * written at v1 carries raw edges with no `moduleSpecifier`, which would make
+ * `--update` resolve imports the old (name-lookup) way for every unchanged
+ * file — a silently mixed graph. `readSidecar` refuses a version mismatch, so
+ * the bump is what makes that impossible rather than merely unlikely.
+ */
+export const SCHEMA_VERSION = 2;
 
 /** Deterministic per-file byte cap — files above this become a SKIPPED node. */
 export const MAX_FILE_BYTES = 1_000_000;

package/src/scripts/code_graph/validate.ts

@@ -6,7 +6,18 @@ import type { CodeGraph } from './types.js';
 
 const RELATIONS = new Set(['calls', 'imports', 'uses', 'inherits', 'member']);
 const CONFIDENCES = new Set(['EXTRACTED', 'INFERRED', 'AMBIGUOUS']);
-const KINDS = new Set(['file', 'class', 'interface', 'trait', 'function', 'method', 'skipped']);
+const KINDS = new Set([
+    'file',
+    'class',
+    'interface',
+    'trait',
+    'function',
+    'method',
+    'constant',
+    'type',
+    'enum',
+    'skipped',
+]);
 
 export interface ValidateResult {
     ok: boolean;

package/src/scripts/conformance_scan.ts

@@ -13,7 +13,7 @@
  *
  *   language-pin      ← language_mirror_hook.classify
  *   git-authorization ← git_authorization_hook.classifyAuthorization
- *                       + block_unauthorized_git.commandOp / BLOCK_OPS
+ *                       + git_command_classifier.commandOp / BLOCK_OPS
  *   vacuous-evidence  ← before_complete_hook.isVacuousOutput / isCiPoll / pendingCount
  *   evidence-steering ← evidence_independence.isEvaluationPrompt / preloadedVerdict
  *   completion-claim  ← turn_end_gate_hook.detectCompletionClaim          (round 7)
@@ -53,8 +53,13 @@ import { entryText, isSidechain } from "./_lib/transcript_entry.js";
 
 import { classify } from "./language_mirror_hook.js";
 import { isSyntheticPrompt } from "./_lib/prompt_shape.js";
-import { classifyAuthorization, type GitOp } from "./git_authorization_hook.js";
-import { BLOCK_OPS, commandOp } from "./hooks/block_unauthorized_git.js";
+import {
+  classifyAuthorization,
+  extractObjects,
+  OBJECT_REQUIRED_OPS,
+  type GitOp,
+} from "./git_authorization_hook.js";
+import { BLOCK_OPS, commandObject, commandOp } from "./hooks/git_command_classifier.js";
 import { isVacuousOutput, isCiPoll, pendingCount } from "./before_complete_hook.js";
 // Round 7 § 1.5 — the SAME predicate `turn-end-gate` refuses on, imported rather
 // than reimplemented, so the measured rate and the gate cannot disagree.
@@ -579,6 +584,8 @@ export function scanSession(sessionId: string, lines: string[]): SessionReport {
   let pinned: "de" | "en" | null = null;
   let pendingPoll: { at: string; cmd: string } | null = null;
   let authorized = new Set<GitOp>();
+  // Per-op objects the current turn's prompt named. Reset with `authorized`.
+  let authorizedObjects = new Map<GitOp, Set<string>>();
   let sawPending = false;
   let evaluationsThisTurn = 0;
   // Round-5 provenance for language violations. The round-5 audit could only
@@ -723,7 +730,15 @@ export function scanSession(sessionId: string, lines: string[]): SessionReport {
       if (c.language !== "und") {
         pinned = c.language;
       }
-      authorized = new Set(classifyAuthorization(ut).authorized);
+      const classified = classifyAuthorization(ut);
+      authorized = new Set(classified.authorized);
+      // Step 2.2 — the objects the turn NAMED, per operation. Rebuilt on every
+      // counted user turn for the same reason `authorized` is: an authorization
+      // for one table does not carry into the next prompt any more than the
+      // operation does.
+      authorizedObjects = new Map(
+        classified.authorized.map((op) => [op, new Set(extractObjects(op, ut))]),
+      );
       sawPending = false;
       evaluationsThisTurn = 0;
       pendingPoll = null;
@@ -811,6 +826,32 @@ export function scanSession(sessionId: string, lines: string[]): SessionReport {
             at,
             detail: `irreversible \`${op}\` with no authorization in the turn's prompt: ${cmd.slice(0, 110)}`,
           });
+        } else if (op !== null && authorized.has(op) && OBJECT_REQUIRED_OPS.has(op)) {
+          // Step 2.2 — the operation WAS authorized and ran against something
+          // the turn never named. An authorization for one table is not an
+          // authorization for another, and until the ledger could carry an
+          // object this was indistinguishable from a clean turn.
+          //
+          // This REPORTS and refuses nothing — ADR-254 removed the enforcing
+          // reader, and the shape it preserved is a count after the fact.
+          //
+          // A command naming NO object produces no finding: `commandObject`
+          // returns null there, and a guessed object would manufacture a
+          // violation out of a parse failure. Under-reporting is the safe
+          // direction for a measurement.
+          const object = commandObject(op, cmd);
+          const named = authorizedObjects.get(op);
+          if (object !== null && !(named?.has(object) ?? false)) {
+            report.violations.push({
+              check: "git-authorization",
+              session: sessionId,
+              at,
+              detail:
+                `\`${op}\` authorized, but its object \`${object}\` is not one the ` +
+                `turn's prompt named (${named && named.size > 0 ? [...named].join(", ") : "no object named"}): ` +
+                cmd.slice(0, 110),
+            });
+          }
         }
         if (isCiPoll(cmd)) {
           // The RESULT of this call arrives on the NEXT entry, and that entry is