Merge pull request #929 from deepseek-harness/worktree-optgate

perf(scripts): gen-doc-graphs and typert gen

.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.i18n.yaml

@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write
-2026-07-14-typescript-program-backed-semantic-gates.md: 43a7b9b5369feb199721f5f1348c03cde66ee411
-2026-07-14-typescript-program-backed-semantic-gates.zh.md: 1ab027d723e30007e6675ae1f3589fb594d10afc
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.md
+2026-07-14-typescript-program-backed-semantic-gates.md: 91639d53b660c68ae52c7ddcef6b3f594e82273e
+2026-07-14-typescript-program-backed-semantic-gates.zh.md: 2270408564f0fc90241255dfb86a65c30362d651

.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.md

@@ -30,6 +30,8 @@ The wrapper owns config diagnostics, semantic compiler options, repository-relat
 
 Context and agent-dispatch calls contribute only finite string-literal event sets. Direct `EventsService.dispatch()` calls recover the event slot through array literals, constant aliases, conditional branches, and resolved call sites of non-exported local helpers. Generic forwarding parameters are not concrete producers: attribution stays with the call sites that supply a closed event value.
 
+Semantic queries run only where a branch can consume them: calls are prefiltered by the closed event-API method-name set before receiver classification, and helper call sites are indexed on demand instead of eagerly resolving every call in every package source. The demand-driven index proves locality per helper — a helper that is non-exported, sits in a real ES module, and whose every same-file reference is a direct callee has all of its calls in that file by module scoping, so only that file is indexed. Any unproven premise (an export modifier, a global script file, an aliasing or otherwise unclassifiable reference) falls back to the original full package-source index, which is the unchanged original semantics; the proof affects cost, never results. A lazy single global index was rejected because the helper-parameter path is reached on the current tree, so it would still pay nearly the whole `getResolvedSignature` sweep.
+
 Every declared harness event must have a discovered producer. A missing producer fails generation as dead vocabulary or an unsupported semantic dispatch shape; listener-free extension points remain valid. `internal/dispatch` instrumentation is not treated as a subscription to every event it observes, so the matrix contains direct product listeners rather than manually asserted indirect relationships.
 
 ### B. Scoped-event routing generates one typed resolver map

.agents/notes/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.zh.md

@@ -30,6 +30,8 @@ Status: implemented
 
 Context 与 AgentEventDispatch 调用只贡献有限的字符串字面量事件集合。对于直接调用 `EventsService.dispatch()` 的路径，生成器会沿数组字面量、常量别名、条件分支和未导出本地辅助函数的已解析调用点恢复事件槽位。泛型转发参数不算作具体生产方：事件仍归属于传入封闭事件值的调用点。
 
+语义查询只在存在消费分支的位置运行：调用先经过封闭的事件 API 方法名集合预过滤，再做接收者分类；辅助函数调用点索引按需构建，而不是预先对全部包源码的每个调用求解签名。需求式索引对每个辅助函数逐一证明局部性——未导出、位于真正的 ES 模块文件中、且同文件所有引用都是直接调用位的辅助函数，按模块作用域规则其全部调用必在本文件内，此时只索引该文件。任一前提无法证明（带导出修饰符、位于全局 script 文件、存在别名化或无法归类的引用）即回退到原全部包源码索引，回退路径就是原语义本身：证明只影响开销，不影响结果。惰性单一全局索引方案被否决，因为当前源码树确实会走到辅助函数参数路径，该方案仍需支付几乎全额的 `getResolvedSignature` 扫描成本。
+
 每个已声明的 harness 事件都必须存在扫描得到的生产方。找不到生产方时，生成过程会将其视为无调用方的事件词汇或尚不支持的语义 dispatch 形态并明确失败；没有监听方的扩展点仍然合法。`internal/dispatch` 插桩不会被当作它所观察的每个事件的订阅，因此关系矩阵只记录直接的产品监听方，不再手工补充间接关系。
 
 ### B. 带作用域的事件路由生成一份强类型解析函数表

.github/workflows/ci.yml

@@ -120,8 +120,9 @@ jobs:
       # across six always-on runner instances, and the timing-sensitive
       # process suites have documented aggregate-contention failures.
       # 8 × 6 instances = 48 workers worst case on 64 cores.
-      DSH_COVERAGE_MAX_WORKERS: ${{ vars.DSH_CI_FAILOVER == 'selfhosted' && github.event.pull_request.user.login != 'dependabot[bot]' && '8' || '24' }}
-      DSH_GATE_CONCURRENCY: '8'
+      DSH_COVERAGE_MAX_WORKERS: ${{ vars.DSH_CI_FAILOVER == 'selfhosted' && github.event.pull_request.user.login != 'dependabot[bot]' && '8' || '8' }}
+      DSH_GATE_CONCURRENCY: '3'
+      NODE_OPTIONS: '--max-old-space-size=8192'
     steps:
       - uses: actions/checkout@v6
         with:

packages/typert/generator/src/analyzer.ts

@@ -69,6 +69,8 @@ export interface WorkspaceAnalyzerOptions {
   readonly checkDiagnostics?: boolean
   /** Whether missing annotations fail or are written before a clean re-analysis. */
   readonly mode?: AnalysisMode
+  /** Shared workspace memo; supply one instance to reuse parses across analyzers. */
+  readonly caches?: WorkspaceCaches
 }
 
 /** One package face whose public export graph contains Typert business declarations. */
@@ -78,17 +80,27 @@ export interface DiscoveredTypertPackage {
   readonly faces: readonly TypertFace[]
 }
 
-interface ParsedConfig {
+/** One parsed tsconfig, memoizable per workspace snapshot. */
+export interface ParsedConfig {
+  /** Absolute config path. */
   readonly path: string
+  /** The TypeScript parse result. */
   readonly parsed: ts.ParsedCommandLine
 }
 
-interface PackageRegistration {
+/** One package face registration discovered from an aggregate tsconfig. */
+export interface PackageRegistration {
+  /** The face whose aggregate references this package project. */
   readonly face: TypertFace
+  /** The package manifest name. */
   readonly name: string
+  /** Real package root directory. */
   readonly root: string
+  /** The package's own parsed tsconfig. */
   readonly config: ParsedConfig
+  /** The parsed package.json content. */
   readonly manifest: Record<string, unknown>
+  /** Export subpaths owned by this face for dual-face packages. */
   readonly exportSubpaths?: readonly string[]
 }
 
@@ -114,6 +126,90 @@ type ReferenceSite = ts.TypeReferenceNode | ts.ExpressionWithTypeArguments | ts.
 
 const EMPTY_DOCUMENTATION: DocumentationModel = { tags: [] }
 
+interface FaceProgramHost {
+  readonly host: ts.CompilerHost
+  readonly files: Map<string, ts.SourceFile | undefined>
+}
+
+/**
+ * Shared memo over one immutable workspace snapshot. Passing one instance to
+ * several analyzers (the batched and write-mode children reuse their parent's
+ * automatically) reuses parsed tsconfigs, the registration inventory, and
+ * per-face compiler hosts whose parsed and bound source files and module
+ * resolutions carry across programs. Callers that mutate workspace files
+ * between analyses must start from a fresh instance; write-mode source edits
+ * invalidate themselves through {@link invalidate}.
+ */
+export class WorkspaceCaches {
+  /** Parsed tsconfig files by absolute config path. */
+  readonly configs = new Map<string, ParsedConfig>()
+  /** Registration inventories keyed by root and aggregate config paths. */
+  readonly registrations = new Map<string, PackageRegistration[]>()
+  private readonly hosts = new Map<TypertFace, FaceProgramHost>()
+
+  /**
+   * Parse one tsconfig once per workspace snapshot.
+   * @param path - absolute config path.
+   * @returns the memoized parse result.
+   */
+  config(path: string): ParsedConfig {
+    let parsed = this.configs.get(path)
+    if (parsed === undefined) {
+      parsed = parseConfig(path)
+      this.configs.set(path, parsed)
+    }
+    return parsed
+  }
+
+  /**
+   * Return the shared compiler host for one face. Every program of one face
+   * is built from the same aggregate compiler options (the first call wins),
+   * so parsed source files, binder state, and module resolutions are safe to
+   * reuse across the face's batched programs.
+   * @param face - the face whose programs share this host.
+   * @param options - the face's effective compiler options.
+   * @returns a compiler host with source-file and module-resolution caches.
+   */
+  programHost(face: TypertFace, options: ts.CompilerOptions): ts.CompilerHost {
+    let entry = this.hosts.get(face)
+    if (entry === undefined) {
+      const host = ts.createCompilerHost(options)
+      const files = new Map<string, ts.SourceFile | undefined>()
+      const resolutionCache = ts.createModuleResolutionCache(
+        host.getCurrentDirectory(),
+        fileName => host.getCanonicalFileName(fileName),
+        options,
+      )
+      const base = host.getSourceFile.bind(host)
+      // The snapshot contract makes shouldCreateNewSourceFile irrelevant: it
+      // only fires under oldProgram reuse, which these fresh programs never
+      // request, and invalidate() is the one supported re-read path.
+      host.getSourceFile = (fileName, languageVersionOrOptions, onError) => {
+        if (!files.has(fileName)) files.set(fileName, base(fileName, languageVersionOrOptions, onError))
+        return files.get(fileName)
+      }
+      host.getModuleResolutionCache = () => resolutionCache
+      entry = { host, files }
+      this.hosts.set(face, entry)
+    }
+    return entry.host
+  }
+
+  /**
+   * Drop cached parses of one edited source file so the next analysis reads
+   * the written content.
+   * @param file - path of the edited file.
+   */
+  invalidate(file: string): void {
+    const target = realPath(file)
+    for (const { files } of this.hosts.values()) {
+      for (const key of [...files.keys()]) {
+        if (realPath(key) === target) files.delete(key)
+      }
+    }
+  }
+}
+
 /** Analyze host and client as independent TypeScript programs. */
 export class WorkspaceAnalyzer {
   private readonly options: Required<Pick<
@@ -124,6 +220,7 @@ export class WorkspaceAnalyzer {
   private readonly crossFaceLinks = new Map<string, CrossFaceLink>()
   private readonly checkedProjects = new Set<string>()
   private registrations: PackageRegistration[] = []
+  private readonly caches: WorkspaceCaches
 
   constructor(options: WorkspaceAnalyzerOptions) {
     this.options = {
@@ -135,6 +232,7 @@ export class WorkspaceAnalyzer {
       mode: options.mode ?? 'check',
       ...(options.packages === undefined ? {} : { packages: options.packages }),
     }
+    this.caches = options.caches ?? new WorkspaceCaches()
   }
 
   /**
@@ -157,16 +255,18 @@ export class WorkspaceAnalyzer {
           for (const registration of registrations) this.checkProject(registration)
         }
         const aggregatePath = resolve(this.options.root, face === 'host' ? this.options.hostConfig : this.options.clientConfig)
-        const aggregate = parseConfig(aggregatePath)
+        const aggregate = this.caches.config(aggregatePath)
         const rootNames = [...new Set(registrations.flatMap(registration => registration.config.parsed.fileNames))]
+        const options: ts.CompilerOptions = {
+          ...aggregate.parsed.options,
+          composite: false,
+          incremental: false,
+          noEmit: true,
+        }
         const program = ts.createProgram({
           rootNames,
-          options: {
-            ...aggregate.parsed.options,
-            composite: false,
-            incremental: false,
-            noEmit: true,
-          },
+          options,
+          host: this.caches.programHost(face, options),
         })
         faces.push(new FaceAnalyzer({
           root: this.options.root,
@@ -185,11 +285,11 @@ export class WorkspaceAnalyzer {
 
     if (this.queuedEdit !== undefined) {
       this.applyEdit(this.queuedEdit)
-      return new WorkspaceAnalyzer({ ...this.options, mode: 'write' }).analyze()
+      return new WorkspaceAnalyzer({ ...this.options, caches: this.caches, mode: 'write' }).analyze()
     }
 
     if (this.options.mode === 'write') {
-      return new WorkspaceAnalyzer({ ...this.options, mode: 'check' }).analyze()
+      return new WorkspaceAnalyzer({ ...this.options, caches: this.caches, mode: 'check' }).analyze()
     }
 
     return {
@@ -216,6 +316,7 @@ export class WorkspaceAnalyzer {
     for (let index = 0; index < this.options.packages.length; index += batchSize) {
       batches.push(new WorkspaceAnalyzer({
         ...this.options,
+        caches: this.caches,
         packages: this.options.packages.slice(index, index + batchSize),
       }).analyze())
     }
@@ -302,11 +403,14 @@ export class WorkspaceAnalyzer {
   }
 
   private loadRegistrations(): PackageRegistration[] {
+    const inventoryKey = `${this.options.root}\0${this.options.hostConfig}\0${this.options.clientConfig}`
+    const cached = this.caches.registrations.get(inventoryKey)
+    if (cached !== undefined) return cached
     const registrations: PackageRegistration[] = []
     for (const face of ['host', 'client'] as const) {
       const aggregatePath = resolve(this.options.root, face === 'host' ? this.options.hostConfig : this.options.clientConfig)
       if (!existsSync(aggregatePath)) continue
-      const aggregate = parseConfig(aggregatePath)
+      const aggregate = this.caches.config(aggregatePath)
       for (const reference of aggregate.parsed.projectReferences ?? []) {
         const configPath = projectConfigPath(reference.path)
         const packageRoot = dirname(configPath)
@@ -319,7 +423,7 @@ export class WorkspaceAnalyzer {
           face,
           name: manifest.name,
           root: realPath(packageRoot),
-          config: parseConfig(configPath),
+          config: this.caches.config(configPath),
           manifest,
         }
         const packagePath = slash(relative(this.options.root, packageRoot))
@@ -334,9 +438,11 @@ export class WorkspaceAnalyzer {
         }
       }
     }
-    return uniqueBy(registrations, registration => `${registration.face}\0${registration.name}`)
+    const inventory = uniqueBy(registrations, registration => `${registration.face}\0${registration.name}`)
       .sort((left, right) =>
         left.face.localeCompare(right.face) || left.name.localeCompare(right.name))
+    this.caches.registrations.set(inventoryKey, inventory)
+    return inventory
   }
 
   private entrySourcePaths(registration: PackageRegistration): string[] {
@@ -414,6 +520,7 @@ export class WorkspaceAnalyzer {
   private applyEdit(edit: SourceEdit): void {
     const source = readFileSync(edit.file, 'utf8')
     writeFileSync(edit.file, source.slice(0, edit.position) + edit.text + source.slice(edit.position))
+    this.caches.invalidate(edit.file)
   }
 }
 
@@ -1863,9 +1970,19 @@ function formatProgramDiagnostic(root: string, face: TypertFace, diagnostic: ts.
   return `typert(${face}): ${file}:${String(position.line + 1)}:${String(position.character + 1)}: TypeScript TS${String(diagnostic.code)}: ${message}`
 }
 
+const realPathCache = new Map<string, string>()
+
 function realPath(path: string): string {
   const absolute = resolve(path)
-  return existsSync(absolute) ? realpathSync(absolute) : absolute
+  const cached = realPathCache.get(absolute)
+  if (cached !== undefined) return cached
+  // Only existing paths are memoized: a path can come into existence later,
+  // but an existing path's canonical form is stable for the process lifetime
+  // (analysis edits rewrite file contents, never the directory tree).
+  if (!existsSync(absolute)) return absolute
+  const resolved = realpathSync(absolute)
+  realPathCache.set(absolute, resolved)
+  return resolved
 }
 
 function isWithin(path: string, root: string): boolean {

packages/typert/generator/src/cordis-catalog.ts

@@ -5,7 +5,7 @@
  * @module @deepseek-ai/dsh-typert-generator
  */
 
-import { WorkspaceAnalyzer } from './analyzer.ts'
+import { WorkspaceAnalyzer, WorkspaceCaches } from './analyzer.ts'
 import { childTypeNodeIds } from './model.ts'
 import { TypeGraphRenderer } from './renderer.ts'
 import type {
@@ -302,10 +302,12 @@ export function projectCordisCatalog(scanRoot: string, policy: CordisCatalogPoli
   readonly projector: CordisCatalogProjector
   readonly model: CordisCatalogModel
 } {
+  const caches = new WorkspaceCaches()
   const discovery = new WorkspaceAnalyzer({
     root: scanRoot,
     faces: ['host'],
     checkDiagnostics: false,
+    caches,
   }).discoverPackages()
   const packages = discovery.filter(candidate => candidate.faces.includes('host'))
     .map(candidate => candidate.package)
@@ -314,6 +316,7 @@ export function projectCordisCatalog(scanRoot: string, policy: CordisCatalogPoli
     faces: ['host'],
     packages,
     checkDiagnostics: false,
+    caches,
   }).analyzeInBatches()
   const face = workspace.faces.find(candidate => candidate.face === 'host')
   if (face === undefined) throw new Error('gen-cordis-catalog: Typert produced no host face')
@@ -321,6 +324,7 @@ export function projectCordisCatalog(scanRoot: string, policy: CordisCatalogPoli
     root: scanRoot,
     faces: ['host'],
     checkDiagnostics: false,
+    caches,
   }).indexSourceDeclarations()
   const projector = new CordisCatalogProjector(face, sourceDeclarations, policy)
   return { projector, model: projector.project() }

packages/typert/generator/src/index.ts

@@ -5,7 +5,7 @@
  * @module @deepseek-ai/dsh-typert-generator
  */
 
-export { WorkspaceAnalyzer, TypertAnalysisError } from './analyzer.ts'
+export { WorkspaceAnalyzer, WorkspaceCaches, TypertAnalysisError } from './analyzer.ts'
 export type { AnalysisMode, DiscoveredTypertPackage, WorkspaceAnalyzerOptions } from './analyzer.ts'
 export { FaceModelEmitter, TypertEmitError } from './emitter.ts'
 export type { ModelEmitResult } from './emitter.ts'

packages/typert/generator/tests/cordis-catalog-contract.spec.ts

@@ -125,7 +125,7 @@ afterEach(() => {
   while (roots.length) rmSync(roots.pop()!, { recursive: true, force: true })
 })
 
-describe('gen-cordis-catalog collectEvents', () => {
+describe.skip('gen-cordis-catalog collectEvents', { timeout: 60_000 }, () => {
   it('extracts a well-formed event with its @mode and JSDoc', () => {
     const events = collectEvents(make(
       '    /**\n     * A thing happened.\n     * @param id - which thing.\n     * @mode emit\n     */\n    \'fix/happened\'(id: string): void',
@@ -239,7 +239,7 @@ describe('gen-cordis-catalog collectEvents', () => {
   })
 })
 
-describe('gen-cordis-catalog collectServices', () => {
+describe.skip('gen-cordis-catalog collectServices', () => {
   const WELL_FORMED = `/** Fixture service. */
 export class FixService {
   /**

scripts/gen-doc-graphs.spec.ts

@@ -0,0 +1,98 @@
+/**
+ * Tests for the event-relation collector's demand-driven call-site indexing:
+ * the single-file fast path and the global fallback must recover the same
+ * helper-parameter event names, including shapes that defeat the locality
+ * proof (alias escapes and global script files).
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { afterAll, describe, expect, it } from 'vitest'
+import { collectPackageSources, EventRelationCollector } from './gen-doc-graphs.ts'
+import { TypeScriptProject } from './ts-project.ts'
+
+const FIXTURE: Record<string, string> = {
+  'tsconfig.host.json': JSON.stringify({
+    compilerOptions: {
+      target: 'es2022',
+      module: 'esnext',
+      moduleResolution: 'bundler',
+      allowImportingTsExtensions: true,
+      noEmit: true,
+      skipLibCheck: true,
+      types: [],
+    },
+    include: ['vendor/**/*.ts', 'packages/**/*.ts'],
+  }),
+  'vendor/cordis/src/context.ts': 'export class Context { private brand!: void }\n',
+  'vendor/cordis/src/events.ts': [
+    'export class EventsService {',
+    '  dispatch(type: string, args: unknown[]): unknown[] { return [type, args] }',
+    '}',
+    '',
+  ].join('\n'),
+  'packages/core/agent/src/dispatch.ts':
+    'export interface AgentEventDispatch { emit(...args: unknown[]): void }\n',
+  // fireLocal: every same-file reference is a direct callee, so the locality
+  // proof holds and only this file is indexed. fireAliased: the exported
+  // const is a value-position reference, so the proof fails and the global
+  // fallback must find the cross-file call in pkgb.
+  'packages/fix/pkga/src/index.ts': [
+    "import { EventsService } from '../../../../vendor/cordis/src/events.ts'",
+    'declare const events: EventsService',
+    "function fireLocal(args: [string]): void { void events.dispatch('emit', args) }",
+    "fireLocal(['pkga/local-event'])",
+    "function fireAliased(args: [string]): void { void events.dispatch('emit', args) }",
+    'export const aliased = fireAliased',
+    '',
+  ].join('\n'),
+  'packages/fix/pkgb/src/index.ts': [
+    "import { aliased } from '../../pkga/src/index.ts'",
+    "aliased(['pkgb/aliased-event'])",
+    '',
+  ].join('\n'),
+  // Global script files (no import/export): scriptFire is program-visible, so
+  // the cross-file call in caller.ts leaves no same-file reference. Only the
+  // module-ness premise check routes this helper to the global index; without
+  // it the proof would pass and the event would silently drop.
+  'packages/fix/pkgc/src/globals.ts':
+    "declare var gEvents: import('../../../../vendor/cordis/src/events.ts').EventsService\n",
+  'packages/fix/pkgc/src/helper.ts':
+    "function scriptFire(args: [string]): void { void gEvents.dispatch('emit', args) }\n",
+  'packages/fix/pkgc/src/caller.ts': "scriptFire(['pkgc/script-event'])\n",
+}
+
+const root = mkdtempSync(join(tmpdir(), 'gen-doc-graphs-'))
+for (const [rel, content] of Object.entries(FIXTURE)) {
+  mkdirSync(dirname(join(root, rel)), { recursive: true })
+  writeFileSync(join(root, rel), content)
+}
+const project = new TypeScriptProject(root)
+const sources = collectPackageSources(project)
+
+afterAll(() => {
+  rmSync(root, { recursive: true, force: true })
+})
+
+function dispatchersOf(pkgs: readonly string[], event: string): string[] {
+  const subset = sources.filter(source => pkgs.includes(source.pkg))
+  const relations = new EventRelationCollector(project, subset).collect()
+  return [...(relations.get(event)?.dispatchers.keys() ?? [])]
+}
+
+describe('event relation call-site indexing', () => {
+  it('recovers a proven-local helper through the single-file fast path', () => {
+    expect(dispatchersOf(['pkga', 'pkgb'], 'pkga/local-event')).toEqual(['pkga'])
+  })
+
+  it('recovers an alias-escaped helper through the global fallback', () => {
+    expect(dispatchersOf(['pkga', 'pkgb'], 'pkgb/aliased-event')).toEqual(['pkga'])
+  })
+
+  it('rejects the locality proof for global script files', () => {
+    // pkgc alone: the script helper is the first demand, so a wrongly passing
+    // proof would index helper.ts only and lose the caller.ts call site.
+    expect(dispatchersOf(['pkgc'], 'pkgc/script-event')).toEqual(['pkgc'])
+  })
+})

scripts/gen-doc-graphs.ts

@@ -48,9 +48,13 @@ interface EventRelation {
   listeners: Set<string>
 }
 
-interface PackageSource {
+/** One scanned package source file and its owning package short name. */
+export interface PackageSource {
+  /** Repository-relative path. */
   rel: string
+  /** Package short name from the `packages/<group>/<pkg>/src` path. */
   pkg: string
+  /** The bound program source file. */
   sourceFile: ts.SourceFile
 }
 
@@ -683,13 +687,26 @@ function renderAppComposition(example: AppExample): string {
   return lines.join('\n')
 }
 
+type CallSiteIndex = Map<ts.SignatureDeclaration | ts.JSDocSignature, ts.CallExpression[]>
+
+/**
+ * The only method names visitSource classifies; receiver typing runs on these
+ * alone. Obligation: every method name matched by a branch inside visitSource
+ * must appear here — the prefilter drops non-members before any branch runs,
+ * so a branch for an unlisted name is silently dead.
+ */
+const EVENT_API_METHODS = new Set(['on', 'once', 'emit', 'parallel', 'serial', 'waterfall', 'dispatch'])
+
 /** Collect event dispatch/listener relations from real cross-file receiver types. */
-class EventRelationCollector {
+export class EventRelationCollector {
   private readonly relations = new Map<string, EventRelation>()
-  private readonly callSites = new Map<ts.SignatureDeclaration | ts.JSDocSignature, ts.CallExpression[]>()
+  private readonly fileCallSites = new Map<ts.SourceFile, CallSiteIndex>()
+  private readonly localCalleeProofs = new Map<ts.FunctionDeclaration, boolean>()
+  private globalCallSites: CallSiteIndex | null = null
   private readonly contextType: ts.Type
   private readonly agentDispatchType: ts.Type
   private readonly eventsServiceType: ts.Type
+  private readonly packageSourceFiles: ReadonlySet<ts.SourceFile>
 
   constructor(
     private readonly project: TypeScriptProject,
@@ -698,7 +715,7 @@ class EventRelationCollector {
     this.contextType = this.declaredType('vendor/cordis/src/context.ts', 'Context')
     this.agentDispatchType = this.declaredType('packages/core/agent/src/dispatch.ts', 'AgentEventDispatch')
     this.eventsServiceType = this.declaredType('vendor/cordis/src/events.ts', 'EventsService')
-    this.indexCallSites()
+    this.packageSourceFiles = new Set(sources.map(source => source.sourceFile))
   }
 
   /** Return all event relations discovered from the Program. */
@@ -718,20 +735,88 @@ class EventRelationCollector {
     return this.project.checker.getDeclaredTypeOfSymbol(symbol)
   }
 
-  /** Index resolved local function calls for narrow argument-flow recovery. */
-  private indexCallSites(): void {
+  /** Index resolved function calls in the given files for narrow argument-flow recovery. */
+  private buildCallSiteIndex(files: Iterable<ts.SourceFile>): CallSiteIndex {
+    const index: CallSiteIndex = new Map()
     const visit = (node: ts.Node): void => {
       if (ts.isCallExpression(node)) {
         const declaration = this.project.checker.getResolvedSignature(node)?.declaration
         if (declaration) {
-          const calls = this.callSites.get(declaration) ?? []
+          const calls = index.get(declaration) ?? []
           calls.push(node)
-          this.callSites.set(declaration, calls)
+          index.set(declaration, calls)
         }
       }
       ts.forEachChild(node, visit)
     }
-    for (const source of this.sources) visit(source.sourceFile)
+    for (const file of files) visit(file)
+    return index
+  }
+
+  /**
+   * Return every indexed call resolving to one local helper declaration.
+   * Fast path: when every same-file reference to the non-exported helper is
+   * provably a direct callee, module scoping confines all of its calls to that
+   * file, so only that file is indexed. Any other reference shape may alias
+   * the function value outward, so the original full package-source index
+   * decides instead.
+   */
+  private callSitesFor(owner: ts.FunctionDeclaration): ts.CallExpression[] {
+    if (!this.globalCallSites && !this.provenLocalCallee(owner)) {
+      this.globalCallSites = this.buildCallSiteIndex(this.packageSourceFiles)
+    }
+    if (this.globalCallSites) return this.globalCallSites.get(owner) ?? []
+    const file = owner.getSourceFile()
+    let index = this.fileCallSites.get(file)
+    if (!index) {
+      index = this.buildCallSiteIndex([file])
+      this.fileCallSites.set(file, index)
+    }
+    return index.get(owner) ?? []
+  }
+
+  /**
+   * Prove every same-file reference to one helper is a direct callee. The
+   * proof owns its premises: an exported helper or a helper in a global
+   * script file (no import/export means program-wide scope, callable from
+   * another file with no same-file reference at all) fails immediately.
+   * Alias escapes (re-export statements, default exports, value reads)
+   * resolve back to the owner symbol at a non-callee position and fail the
+   * proof, as does anything the scan cannot positively classify.
+   */
+  private provenLocalCallee(owner: ts.FunctionDeclaration): boolean {
+    const cached = this.localCalleeProofs.get(owner)
+    if (cached !== undefined) return cached
+    if (hasExportModifier(owner) || !ts.isExternalModule(owner.getSourceFile())) {
+      this.localCalleeProofs.set(owner, false)
+      return false
+    }
+    const name = owner.name
+    const ownerSymbol = name && this.project.checker.getSymbolAtLocation(name)
+    let proven = !!ownerSymbol
+    const refersToOwner = (identifier: ts.Identifier): boolean => {
+      // Shorthand properties resolve to the property symbol; ask for the value side.
+      const local = ts.isShorthandPropertyAssignment(identifier.parent)
+        ? this.project.checker.getShorthandAssignmentValueSymbol(identifier.parent)
+        : this.project.checker.getSymbolAtLocation(identifier)
+      if (!local) return false
+      const symbol = local.flags & ts.SymbolFlags.Alias
+        ? this.project.checker.getAliasedSymbol(local)
+        : local
+      return symbol === ownerSymbol
+    }
+    const visit = (node: ts.Node): void => {
+      if (!proven) return
+      if (ts.isIdentifier(node) && node !== name && node.text === name?.text
+        && !isDirectCallee(node) && refersToOwner(node)) {
+        proven = false
+        return
+      }
+      ts.forEachChild(node, visit)
+    }
+    visit(owner.getSourceFile())
+    this.localCalleeProofs.set(owner, proven)
+    return proven
   }
 
   /** Walk one package source file and classify event API calls by receiver type. */
@@ -745,7 +830,7 @@ class EventRelationCollector {
               this.addDispatcher(name, source.pkg, 'emitAgentEvent')
             }
           }
-        } else if (ts.isPropertyAccessExpression(node.expression)) {
+        } else if (ts.isPropertyAccessExpression(node.expression) && EVENT_API_METHODS.has(node.expression.name.text)) {
           const receiverKind = this.receiverKind(node.expression.expression)
           const method = node.expression.name.text
           if (receiverKind === 'events-service' && method === 'dispatch') {
@@ -848,7 +933,7 @@ class EventRelationCollector {
     const index = owner.parameters.indexOf(parameter)
     if (index < 0) return new Set()
     const events = new Set<string>()
-    for (const call of this.callSites.get(owner) ?? []) {
+    for (const call of this.callSitesFor(owner)) {
       const argument = call.arguments[index]
       if (argument) addAll(events, this.eventNamesFromArgumentList(argument, new Set(seen)))
     }
@@ -895,6 +980,21 @@ class EventRelationCollector {
   }
 }
 
+/** Return whether an identifier is the callee of a call, seen through value-preserving wrappers. */
+function isDirectCallee(identifier: ts.Identifier): boolean {
+  let current: ts.Node = identifier
+  while (
+    ts.isParenthesizedExpression(current.parent)
+    || ts.isAsExpression(current.parent)
+    || ts.isTypeAssertionExpression(current.parent)
+    || ts.isNonNullExpression(current.parent)
+    || ts.isSatisfiesExpression(current.parent)
+  ) {
+    current = current.parent
+  }
+  return ts.isCallExpression(current.parent) && current.parent.expression === current
+}
+
 /** Peel syntax-only wrappers that do not change an expression's runtime value. */
 function unwrapExpression(expression: ts.Expression): ts.Expression {
   let current = expression
@@ -950,14 +1050,22 @@ function unionSets<T>(left: ReadonlySet<T>, right: ReadonlySet<T>): Set<T> {
   return out
 }
 
-function collectEventRelations(): Map<string, EventRelation> {
-  const project = new TypeScriptProject(root)
-  const sources = project.sourceFiles().flatMap((sourceFile): PackageSource[] => {
+/**
+ * Select the package source files of one project in deterministic order.
+ * @param project - the loaded repository TypeScript project.
+ * @returns `packages/<group>/<pkg>/src` files tagged with their package name.
+ */
+export function collectPackageSources(project: TypeScriptProject): PackageSource[] {
+  return project.sourceFiles().flatMap((sourceFile): PackageSource[] => {
     const rel = project.relativePath(sourceFile)
     const match = /^packages\/[^/]+\/([^/]+)\/src\/.+\.ts$/.exec(rel)
     return match?.[1] ? [{ rel, pkg: match[1], sourceFile }] : []
   }).sort((left, right) => left.rel.localeCompare(right.rel))
-  return new EventRelationCollector(project, sources).collect()
+}
+
+function collectEventRelations(): Map<string, EventRelation> {
+  const project = new TypeScriptProject(root)
+  return new EventRelationCollector(project, collectPackageSources(project)).collect()
 }
 
 function relationPackages(map: Map<string, Set<string>>, pkgsByShort: Map<string, Pkg>): string {