@astrale-os/cli 1.0.0-beta.1 → 1.0.0-beta.2

package/studio/server/introspect/overlay-tsmorph.ts

@@ -1,1307 +1,9 @@
-import { existsSync, readFileSync, realpathSync } from 'node:fs'
-import { dirname, isAbsolute, relative, resolve as resolvePath } from 'node:path'
 /**
- * ts-morph overlay for IR gaps: handler links, source spans, and annotations.
- * It is tolerant by contract; unresolved files or handlers produce empty/unlinked output.
+ * Compatibility facade for the ts-morph source overlay.
+ *
+ * Keep this path stable for the overlay composer and focused tests. The
+ * implementation lives under source-overlay, split by responsibility.
  */
-import { Node, Project, SyntaxKind, type CallExpression, type SourceFile } from 'ts-morph'
-
-import type { HandlerLink, SchemaAnnotation, SchemaIR, SourceSpan } from '../../shared/types'
-
-// ───────────────────────────── shared helpers ─────────────────────────────
-
-/** A fresh, in-memory-ish ts-morph project: no tsconfig, tolerant of errors. */
-function newProject(): Project {
-  return new Project({
-    useInMemoryFileSystem: false,
-    skipFileDependencyResolution: true,
-    skipLoadingLibFiles: true,
-    compilerOptions: {
-      allowJs: true,
-      // `allowImportingTsExtensions` keeps `.ts`-suffixed imports from blowing up.
-      allowImportingTsExtensions: true,
-    },
-  })
-}
-
-/** Add a file to the project if it exists; returns undefined otherwise. */
-function tryAddFile(project: Project, file: string): SourceFile | undefined {
-  try {
-    if (!existsSync(file)) return undefined
-    return project.getSourceFile(file) ?? project.addSourceFileAtPath(file)
-  } catch {
-    return undefined
-  }
-}
-
-/** Path relative to `root`, POSIX-style ('schema/monitor.ts'), never absolute. */
-function relToRoot(root: string, file: string): string {
-  const abs = isAbsolute(file) ? file : resolvePath(root, file)
-  const canonical = (value: string) => {
-    try {
-      return realpathSync(value)
-    } catch {
-      return value
-    }
-  }
-  return relative(canonical(root), canonical(abs)).split('\\').join('/')
-}
-
-/** 1-based start line of a node. */
-function startLine(node: Node): number {
-  return node.getStartLineNumber()
-}
-
-/**
- * Harvest the leading JSDoc / line-comment block immediately above `node`,
- * stripped of comment markers, collapsed to a single trimmed string.
- */
-function leadingDoc(node: Node): string | undefined {
-  // Prefer real JSDoc nodes when present (ts-morph exposes them on many decls).
-  const anyNode = node as unknown as { getJsDocs?: () => Array<{ getText: () => string }> }
-  if (typeof anyNode.getJsDocs === 'function') {
-    const docs = anyNode.getJsDocs()
-    if (docs.length > 0) {
-      const text = docs.map((d) => d.getText()).join('\n')
-      const cleaned = cleanComment(text)
-      if (cleaned) return cleaned
-    }
-  }
-  // Fall back to raw leading comment ranges (covers `//` line comments too).
-  const ranges = node.getLeadingCommentRanges()
-  if (ranges.length === 0) return undefined
-  const raw = ranges.map((r) => r.getText()).join('\n')
-  const cleaned = cleanComment(raw)
-  return cleaned || undefined
-}
-
-/** Strip `/** *​/`, `//`, leading `*` gutters; collapse to a tidy single line. */
-function cleanComment(raw: string): string {
-  const lines = raw
-    .replace(/\/\*\*?/g, '')
-    .replace(/\*\//g, '')
-    .split('\n')
-    .map((l) =>
-      l
-        .replace(/^\s*\*\s?/, '')
-        .replace(/^\s*\/\/\s?/, '')
-        .trim(),
-    )
-    .filter((l) => l.length > 0)
-  return lines.join(' ').replace(/\s+/g, ' ').trim()
-}
-
-/** The call's callee identifier name, e.g. `method` / `classMethods` / `todo`. */
-function calleeName(call: CallExpression): string | undefined {
-  const expr = call.getExpression()
-  if (Node.isIdentifier(expr)) return expr.getText()
-  if (Node.isPropertyAccessExpression(expr)) return expr.getName()
-  return undefined
-}
-
-/** Unwrap a string literal argument to its value. */
-function stringArg(call: CallExpression, index: number): string | undefined {
-  const arg = call.getArguments()[index]
-  if (!arg) return undefined
-  if (Node.isStringLiteral(arg) || Node.isNoSubstitutionTemplateLiteral(arg)) {
-    return arg.getLiteralText()
-  }
-  return undefined
-}
-
-// ───────────────────────────── handler links ─────────────────────────────
-
-/** Recognized method-wiring calls after normalizing single-method and grouped helpers. */
-interface WiredMethod {
-  owner: string
-  method: string
-  /** the object literal / call expression carrying the handler config */
-  config: Node
-  wiringLine: number
-  wiringFile: string
-  ownerKind?: 'class' | 'interface' | 'function'
-  style?: 'legacy-config' | 'direct-handler'
-}
-
-const SINGLE_METHOD_HELPERS = new Set(['method', 'remoteMethod'])
-const GROUP_HELPERS = new Set([
-  'classMethods',
-  'interfaceMethods',
-  'remoteClassMethods',
-  'remoteInterfaceMethods',
-])
-
-type KernelToken = { token: string; label?: string }
-
-/** Kernel-op idioms surfaced as `kernelCalls`; entries are longest-first. */
-const KERNEL_TOKENS: KernelToken[] = [
-  { token: 'graph.createEdge' },
-  { token: 'graph.removeEdge' },
-  { token: 'function.mutate' },
-  { token: 'graph.children' },
-  { token: 'function.get' },
-  { token: 'graph.create' },
-  { token: 'graph.update' },
-  { token: 'graph.remove' },
-  { token: 'graph.mutate' },
-  { token: 'auth.revoke' },
-  { token: 'graph.links' },
-  { token: 'auth.grant' },
-  { token: 'auth.check' },
-  { token: 'graph.tree' },
-  { token: 'graph.node' },
-  { token: 'revokePerm', label: 'revokePerm (legacy)' },
-  { token: 'checkPerm', label: 'checkPerm (legacy)' },
-  { token: 'graph.get' },
-  { token: 'grantPerm', label: 'grantPerm (legacy)' },
-]
-
-/**
- * Resolve a method-config node (object literal `{ authorize, execute }` or a
- * call like `todo('…')`) down to: the symbol that carries the real logic, plus
- * whether it is a NotImplemented stub and the authorize flavour.
- */
-interface ConfigResolution {
-  /** the node whose `execute` body we follow to a handler file */
-  executeNode?: Node
-  implemented: boolean
-  /** declared auth policy; defaults to 'required' when the prop is absent. */
-  auth?: 'public' | 'optional' | 'required'
-  /** authorize hook shape: 'absent' | 'noop' | 'custom'. */
-  authorize?: 'absent' | 'noop' | 'custom'
-  authorizeSnippet?: string
-  unlinkedReason?: 'no-config'
-}
-
-function resolveConfigObject(configNode: Node, seen = new Set<string>()): ConfigResolution {
-  const node = unwrapExpression(configNode)
-  const key = `${node.getSourceFile().getFilePath()}:${node.getStart()}`
-  if (seen.has(key)) return { implemented: false, unlinkedReason: 'no-config' }
-  seen.add(key)
-
-  if (Node.isCallExpression(node)) {
-    // Curried SDK helpers carry the handler config in their final argument:
-    // `remoteMethod()(schema, 'Issue', 'delete', { authorize, execute })`.
-    const lastArg = node.getArguments().at(-1)
-    if (lastArg) {
-      const candidate = unwrapExpression(lastArg)
-      if (Node.isObjectLiteralExpression(candidate) || Node.isIdentifier(candidate)) {
-        return resolveConfigObject(candidate, seen)
-      }
-    }
-
-    // Local factories such as `todo('Owner.name')` return the config object themselves.
-    const obj = followFactoryToObject(node)
-    if (obj) return classifyObjectLiteral(obj)
-    return { implemented: false, unlinkedReason: 'no-config' }
-  }
-  if (Node.isObjectLiteralExpression(node)) {
-    return classifyObjectLiteral(node)
-  }
-  // Handler maps normally reference a local or imported `remoteMethod` value.
-  if (Node.isIdentifier(node)) {
-    const value = valueOfIdentifier(node)
-    if (value) return resolveConfigObject(value, seen)
-  }
-  return { implemented: false, unlinkedReason: 'no-config' }
-}
-
-/** Remove syntax-only wrappers around a runtime value. */
-function unwrapExpression(node: Node): Node {
-  let current = node
-  while (
-    Node.isParenthesizedExpression(current) ||
-    Node.isAsExpression(current) ||
-    Node.isSatisfiesExpression(current) ||
-    Node.isTypeAssertion(current)
-  ) {
-    current = current.getExpression()
-  }
-  return current
-}
-
-/** Resolve a local or relatively imported identifier to its runtime value. */
-function valueOfIdentifier(id: Node): Node | undefined {
-  if (!Node.isIdentifier(id)) return undefined
-  const decl = firstValueDeclaration(id)
-  if (decl && Node.isVariableDeclaration(decl)) return decl.getInitializer()
-  return resolveImportedValue(id)
-}
-
-/** Follow a named relative import to the exported value that defines it. */
-function resolveImportedValue(id: Node): Node | undefined {
-  if (!Node.isIdentifier(id)) return undefined
-  const localName = id.getText()
-  const sourceFile = id.getSourceFile()
-
-  for (const imp of sourceFile.getImportDeclarations()) {
-    for (const named of imp.getNamedImports()) {
-      const local = named.getAliasNode()?.getText() ?? named.getName()
-      if (local !== localName) continue
-      const target = resolveModuleFile(sourceFile, imp.getModuleSpecifierValue())
-      if (!target) return undefined
-      return findExportedValue(id.getProject(), target, named.getName(), new Set<string>())
-    }
-  }
-  return undefined
-}
-
-/** Find an exported variable/function value, following local and barrel exports. */
-function findExportedValue(
-  project: Project,
-  file: string,
-  exportName: string,
-  seen: Set<string>,
-): Node | undefined {
-  const key = `${file}:${exportName}`
-  if (seen.has(key)) return undefined
-  seen.add(key)
-  const sf = tryAddFile(project, file)
-  if (!sf) return undefined
-
-  const localValue = (name: string, exportedOnly: boolean): Node | undefined => {
-    const variable = sf
-      .getVariableDeclarations()
-      .find(
-        (candidate) => candidate.getName() === name && (!exportedOnly || candidate.isExported()),
-      )
-    if (variable) return variable.getInitializer()
-    return sf
-      .getFunctions()
-      .find(
-        (candidate) => candidate.getName() === name && (!exportedOnly || candidate.isExported()),
-      )
-  }
-
-  const direct = localValue(exportName, true)
-  if (direct) return direct
-
-  for (const ex of sf.getExportDeclarations()) {
-    const modSpec = ex.getModuleSpecifierValue()
-    const target = modSpec ? resolveModuleFile(sf, modSpec) : undefined
-    const named = ex.getNamedExports()
-    if (named.length > 0) {
-      for (const specifier of named) {
-        const exposed = specifier.getAliasNode()?.getText() ?? specifier.getName()
-        if (exposed !== exportName) continue
-        const original = specifier.getName()
-        if (target) return findExportedValue(project, target, original, seen)
-        return localValue(original, false)
-      }
-    } else if (target) {
-      const found = findExportedValue(project, target, exportName, seen)
-      if (found) return found
-    }
-  }
-  return undefined
-}
-
-/** Given `todo('x')`, find the factory's `return { … }` object literal. */
-function followFactoryToObject(call: CallExpression): Node | undefined {
-  const expr = call.getExpression()
-  if (!Node.isIdentifier(expr)) return undefined
-  const decl = firstValueDeclaration(expr)
-  if (!decl) return undefined
-  let body: Node | undefined
-  if (Node.isVariableDeclaration(decl)) {
-    body = decl.getInitializer()
-  } else if (Node.isFunctionDeclaration(decl)) {
-    body = decl
-  }
-  if (!body) return undefined
-  // Arrow returning an object literal directly: `(name) => ({ … })`.
-  if (Node.isArrowFunction(body)) {
-    const arrowBody = body.getBody()
-    if (Node.isParenthesizedExpression(arrowBody)) {
-      const inner = arrowBody.getExpression()
-      if (Node.isObjectLiteralExpression(inner)) return inner
-    }
-    if (Node.isObjectLiteralExpression(arrowBody)) return arrowBody
-    // Block body with a `return { … }`.
-    const ret = arrowBody.getFirstDescendantByKind?.(SyntaxKind.ReturnStatement)
-    const retExpr = ret?.getExpression()
-    if (retExpr && Node.isObjectLiteralExpression(retExpr)) return retExpr
-  }
-  if (Node.isFunctionDeclaration(body) || Node.isFunctionExpression(body)) {
-    const ret = body.getFirstDescendantByKind(SyntaxKind.ReturnStatement)
-    const retExpr = ret?.getExpression()
-    if (retExpr && Node.isObjectLiteralExpression(retExpr)) return retExpr
-  }
-  return undefined
-}
-
-/** Inspect `{ auth, authorize, execute }` for the auth policy, authorize shape,
- *  parsed permission checks, source snippets, and execute stub-ness. */
-function classifyObjectLiteral(obj: Node): ConfigResolution {
-  if (!Node.isObjectLiteralExpression(obj)) {
-    return { implemented: false, unlinkedReason: 'no-config' }
-  }
-  const executeProp = getProp(obj, 'execute')
-  const authorizeProp = getProp(obj, 'authorize')
-
-  const auth = authPolicy(obj)
-  const authorize = authorizeProp ? authorizeFlavour(authorizeProp) : 'absent'
-  const authorizeSnippet = authorizeProp ? snippetOf(authorizeProp) : undefined
-  const common = { auth, authorize, authorizeSnippet } as const
-
-  if (!executeProp) {
-    return { implemented: false, ...common, unlinkedReason: 'no-config' }
-  }
-  const implemented = !isStubFunction(executeProp)
-  return { executeNode: executeProp, implemented, ...common }
-}
-
-/** The declared `auth` policy on a method config; defaults to 'required'. */
-function authPolicy(obj: Node): 'public' | 'optional' | 'required' {
-  const v = stringLiteralOfProp(obj, 'auth')
-  return v === 'public' || v === 'optional' ? v : 'required'
-}
-
-const SNIPPET_CAP = 1200
-
-/** Source text of a node, capped for a hover preview. */
-function snippetOf(node: Node): string {
-  const t = node.getText()
-  return t.length > SNIPPET_CAP ? `${t.slice(0, SNIPPET_CAP)}\n/* … */` : t
-}
-
-/** Get the value node of an object-literal property (handles shorthand). */
-function getProp(obj: Node, name: string): Node | undefined {
-  if (!Node.isObjectLiteralExpression(obj)) return undefined
-  const prop = obj.getProperty(name)
-  if (!prop) return undefined
-  if (Node.isPropertyAssignment(prop)) return prop.getInitializer()
-  if (Node.isShorthandPropertyAssignment(prop)) return prop.getNameNode()
-  if (Node.isMethodDeclaration(prop)) return prop
-  return prop
-}
-
-/** 'noop' when the authorize body just returns undefined/void, else 'custom'.
- *  Follows identifier references (e.g. `authorize: allow` → `const allow = …`). */
-function authorizeFlavour(node: Node): 'noop' | 'custom' {
-  const fnBody = functionBodyOf(node)
-  if (fnBody === undefined) return 'custom' // opaque (unresolved identifier) → assume real
-  if (fnBody === null) return 'noop' // expression arrow returning `undefined`
-  const text = fnBody.getText().replace(/[{}]/g, '').trim()
-  // Empty block, or a single `return;` / `return undefined;`.
-  if (text === '' || /^return\s*(undefined)?\s*;?$/.test(text)) return 'noop'
-  return 'custom'
-}
-
-/**
- * For a function-like node return its block body (Node), or `null` if it is an
- * expression-bodied arrow whose expression is `undefined`/void, or `undefined`
- * if it is not function-like.
- */
-function functionBodyOf(node: Node): Node | null | undefined {
-  let fn: Node | undefined
-  if (Node.isArrowFunction(node) || Node.isFunctionExpression(node)) fn = node
-  else if (Node.isMethodDeclaration(node)) fn = node
-  else if (Node.isIdentifier(node)) {
-    const value = valueOfIdentifier(node)
-    if (value) return functionBodyOf(value)
-    return undefined
-  }
-  if (!fn) return undefined
-  const body = (fn as unknown as { getBody?: () => Node | undefined }).getBody?.()
-  if (!body) return undefined
-  if (Node.isBlock(body)) return body
-  // Expression body: `async () => undefined`.
-  if (body.getKind() === SyntaxKind.UndefinedKeyword || body.getText() === 'undefined') {
-    return null
-  }
-  return body
-}
-
-/** A handler body that is a NotImplemented stub: only throws / `todo()`. */
-function isStubFunction(node: Node): boolean {
-  const body = functionBodyOf(node)
-  if (!body || body === null) return false
-  if (!Node.isBlock(body)) return false
-  const statements = body.getStatements()
-  if (statements.length === 0) return false
-  // Stub iff every statement is a throw, and there is at least one throw.
-  let throws = 0
-  for (const st of statements) {
-    if (Node.isThrowStatement(st)) {
-      throws++
-      continue
-    }
-    return false
-  }
-  return throws > 0
-}
-
-/** First value/declaration node a name resolves to (definition, not reference). */
-function firstValueDeclaration(node: Node): Node | undefined {
-  const idNode = Node.isIdentifier(node)
-    ? node
-    : node.getFirstDescendantByKind(SyntaxKind.Identifier)
-  if (!idNode || !Node.isIdentifier(idNode)) return undefined
-  const symbol = idNode.getSymbol()
-  if (!symbol) return undefined
-  const decls = symbol.getDeclarations()
-  return decls[0]
-}
-
-/**
- * Follow an `execute` arrow → the delegated logic function it calls → that
- * function's defining file:line, chasing through barrel re-exports.
- */
-function resolveExecuteTarget(executeNode: Node): { file: string; line: number } | undefined {
-  // Find the call inside the execute body that targets an imported symbol.
-  const body = functionBodyOf(executeNode)
-  const searchRoot = body && Node.isBlock(body) ? body : executeNode
-  const calls = searchRoot.getDescendantsOfKind(SyntaxKind.CallExpression)
-  for (const call of calls) {
-    const expr = call.getExpression()
-    if (!Node.isIdentifier(expr)) continue
-    const resolved = resolveImportedFunction(expr)
-    if (resolved) return resolved
-  }
-  return undefined
-}
-
-/** Resolve an identifier (a delegated logic fn) to its defining file:line. */
-function resolveImportedFunction(id: Node): { file: string; line: number } | undefined {
-  if (!Node.isIdentifier(id)) return undefined
-  const symbol = id.getSymbol()
-  if (!symbol) return undefined
-  // Walk through alias chains (import { x as y } / barrel re-export `export { x }`).
-  let current = symbol
-  const seen = new Set<string>()
-  for (let i = 0; i < 12; i++) {
-    const decls = current.getDeclarations()
-    for (const decl of decls) {
-      // A concrete function/variable declaration in a real file → done.
-      if (Node.isFunctionDeclaration(decl)) {
-        return { file: decl.getSourceFile().getFilePath(), line: decl.getStartLineNumber() }
-      }
-      if (Node.isVariableDeclaration(decl)) {
-        const init = decl.getInitializer()
-        if (init && (Node.isArrowFunction(init) || Node.isFunctionExpression(init))) {
-          return { file: decl.getSourceFile().getFilePath(), line: decl.getStartLineNumber() }
-        }
-      }
-    }
-    // Try to hop to the aliased symbol (import specifier / export specifier).
-    const aliased = trySymbolHop(current)
-    if (!aliased) break
-    const key = aliased
-      .getDeclarations()
-      .map((d) => d.getSourceFile().getFilePath() + ':' + d.getStartLineNumber())
-      .join(',')
-    if (seen.has(key)) break
-    seen.add(key)
-    current = aliased
-  }
-  // Last resort: resolve the module specifier of the import and grep the file.
-  return resolveViaModuleSpecifier(id)
-}
-
-/** Hop one alias link via ts-morph's getAliasedSymbol, if any. */
-function trySymbolHop(symbol: import('ts-morph').Symbol): import('ts-morph').Symbol | undefined {
-  try {
-    const aliased = symbol.getAliasedSymbol?.()
-    if (aliased && aliased !== symbol) return aliased
-  } catch {
-    /* not an alias */
-  }
-  return undefined
-}
-
-/**
- * Fallback resolution: find the import declaration that brought `id` in, load
- * the target module (and barrel re-exports), and locate the exported function.
- */
-function resolveViaModuleSpecifier(id: Node): { file: string; line: number } | undefined {
-  if (!Node.isIdentifier(id)) return undefined
-  const sourceFile = id.getSourceFile()
-  const name = id.getText()
-  for (const imp of sourceFile.getImportDeclarations()) {
-    // Match the local binding name, capturing the original export name.
-    let exportName: string | undefined
-    for (const named of imp.getNamedImports()) {
-      const local = named.getAliasNode()?.getText() ?? named.getName()
-      if (local === name) {
-        exportName = named.getName()
-        break
-      }
-    }
-    if (!exportName) continue
-    const modPath = resolveModuleFile(sourceFile, imp.getModuleSpecifierValue())
-    if (!modPath) continue
-    const found = findExportInFile(modPath, exportName, new Set())
-    if (found) return found
-  }
-  return undefined
-}
-
-/** Resolve a relative module specifier to a concrete .ts file path on disk. */
-function resolveModuleFile(from: SourceFile, spec: string): string | undefined {
-  if (!spec.startsWith('.')) {
-    // Current SDK projects use package `imports` aliases such as
-    // `#actions/risk`. Resolve them from the authored file's directory through
-    // Bun so the overlay follows the same project-local map as runtime imports.
-    if (!spec.startsWith('#')) return undefined
-    try {
-      const resolved = Bun.resolveSync(spec, dirname(from.getFilePath()))
-      if (existsSync(resolved)) return resolved
-    } catch {
-      return undefined
-    }
-    return undefined
-  }
-  const baseDir = dirname(from.getFilePath())
-  const base = resolvePath(baseDir, spec)
-  const sourceBase = base.replace(/\.(?:[cm]?js|jsx)$/, '')
-  const candidates = [
-    base,
-    sourceBase.endsWith('.ts') ? sourceBase : `${sourceBase}.ts`,
-    sourceBase.endsWith('.tsx') ? sourceBase : `${sourceBase}.tsx`,
-    `${base}/index.ts`,
-    `${base}/index.tsx`,
-  ]
-  for (const c of candidates) if (existsSync(c)) return c
-  return undefined
-}
-
-/**
- * Find where `exportName` is *defined* within `file`, following barrel
- * `export { x } from './y'` / `export * from './y'` re-exports.
- */
-function findExportInFile(
-  file: string,
-  exportName: string,
-  seen: Set<string>,
-): { file: string; line: number } | undefined {
-  if (seen.has(file)) return undefined
-  seen.add(file)
-  const project = newProject()
-  const sf = tryAddFile(project, file)
-  if (!sf) return undefined
-
-  // 1) A local function declaration with that name.
-  for (const fn of sf.getFunctions()) {
-    if (fn.getName() === exportName && fn.isExported()) {
-      return { file, line: fn.getStartLineNumber() }
-    }
-  }
-  // 2) A local exported variable bound to a function.
-  for (const v of sf.getVariableDeclarations()) {
-    if (v.getName() === exportName && v.isExported()) {
-      return { file, line: v.getStartLineNumber() }
-    }
-  }
-  // 3) Re-export: `export { a, b as exportName } from './mod'`.
-  for (const ex of sf.getExportDeclarations()) {
-    const modSpec = ex.getModuleSpecifierValue()
-    const target = modSpec ? resolveModuleFile(sf, modSpec) : undefined
-    const named = ex.getNamedExports()
-    if (named.length > 0) {
-      for (const ne of named) {
-        const exposed = ne.getAliasNode()?.getText() ?? ne.getName()
-        if (exposed !== exportName) continue
-        const original = ne.getName()
-        if (target) {
-          const found = findExportInFile(target, original, seen)
-          if (found) return found
-        }
-      }
-    } else if (target) {
-      // `export * from './mod'` — search the target for the same name.
-      const found = findExportInFile(target, exportName, seen)
-      if (found) return found
-    }
-  }
-  return undefined
-}
-
-/** Scan handler file text for kernel-op tokens. */
-function scanKernelCalls(file: string): string[] {
-  let text: string
-  try {
-    text = readFileSync(file, 'utf8')
-  } catch {
-    return []
-  }
-  const found: string[] = []
-  let work = text
-  for (const entry of KERNEL_TOKENS) {
-    if (work.includes(entry.token)) {
-      found.push(entry.label ?? entry.token)
-      // Blank out matches so `::getLinks` doesn't also count as `::getLink`.
-      work = work.split(entry.token).join(' '.repeat(entry.token.length))
-    }
-  }
-  return found
-}
-
-/**
- * Collect every (owner, method, config) wiring from runtime/index.ts, across
- * both fixture styles, then build a HandlerLink per method.
- */
-export function buildHandlerLinks(args: {
-  ir: SchemaIR | null
-  domainRoot: string
-}): HandlerLink[] {
-  const { ir, domainRoot } = args
-  if (!domainRoot) return []
-  const project = newProject()
-  const legacyWiringRel = 'runtime/index.ts'
-  const legacySf = tryAddFile(project, resolvePath(domainRoot, legacyWiringRel))
-
-  const interfaceNames = new Set(ir ? Object.keys(ir.interfaces ?? {}) : [])
-
-  const wired: WiredMethod[] = []
-
-  if (legacySf) {
-    for (const call of legacySf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
-      const name = calleeName(call)
-      if (!name) continue
-
-      // Style A: single-method helper — method(schema, 'Owner', 'name', { … }).
-      if (SINGLE_METHOD_HELPERS.has(name)) {
-        const owner = stringArg(call, 1)
-        const method = stringArg(call, 2)
-        const config = call.getArguments()[3]
-        if (owner && method && config) {
-          wired.push({
-            owner,
-            method,
-            config,
-            wiringLine: call.getStartLineNumber(),
-            wiringFile: legacyWiringRel,
-            style: 'legacy-config',
-          })
-        }
-        continue
-      }
-
-      // Style B: group helper — classMethods(schema, 'Owner', { name: cfg, … }).
-      if (GROUP_HELPERS.has(name)) {
-        const owner = stringArg(call, 1)
-        const mapArg = call.getArguments()[2]
-        if (!owner || !mapArg || !Node.isObjectLiteralExpression(mapArg)) continue
-        for (const prop of mapArg.getProperties()) {
-          const valueNode = objectPropertyValue(prop)
-          const methodName = propertyKey(prop)
-          if (!methodName || !valueNode) continue
-          wired.push({
-            owner,
-            method: methodName,
-            config: valueNode,
-            wiringLine: prop.getStartLineNumber(),
-            wiringFile: legacyWiringRel,
-            style: 'legacy-config',
-          })
-        }
-        continue
-      }
-    }
-  }
-
-  // Current SDK layout: `implementation.ts` owns a plain
-  // `handlers: { classes, interfaces, functions }` object passed to
-  // `defineDomain` / `defineDomain.public`. Start from that call so inline
-  // handler maps and arbitrarily named handler variables are both visible.
-  // Class/interface entries point directly at handler functions; there is no
-  // legacy `{ authorize, execute }` wrapper.
-  for (const wiringRel of ['implementation.ts', 'domain.ts']) {
-    const sf = tryAddFile(project, resolvePath(domainRoot, wiringRel))
-    if (!sf) continue
-
-    const handlerObjects: import('ts-morph').ObjectLiteralExpression[] = []
-    const seenHandlerObjects = new Set<string>()
-    const addHandlerObject = (candidate: Node | undefined) => {
-      const handlersObject = candidate ? resolveObjectLiteral(candidate) : undefined
-      if (!handlersObject) return
-      const key = `${handlersObject.getSourceFile().getFilePath()}:${handlersObject.getStart()}`
-      if (seenHandlerObjects.has(key)) return
-      seenHandlerObjects.add(key)
-      handlerObjects.push(handlersObject)
-    }
-
-    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
-      if (!isDefineDomainCall(call)) continue
-      const input = call.getArguments()[0]
-      const inputObject = input ? resolveObjectLiteral(input) : undefined
-      addHandlerObject(inputObject ? getProp(inputObject, 'handlers') : undefined)
-    }
-
-    // Tolerate pre-composition fixtures that expose a conventional `handlers`
-    // variable without a parseable defineDomain call.
-    const handlersDecl = sf.getVariableDeclaration('handlers')
-    addHandlerObject(handlersDecl?.getInitializer())
-
-    for (const handlersObject of handlerObjects) {
-      const handlersFile = relToRoot(domainRoot, handlersObject.getSourceFile().getFilePath())
-      collectDirectHandlerSection(wired, handlersObject, 'classes', 'class', handlersFile)
-      collectDirectHandlerSection(wired, handlersObject, 'interfaces', 'interface', handlersFile)
-      collectDirectFunctionHandlers(wired, handlersObject, ir?.domain ?? 'domain', handlersFile)
-    }
-  }
-
-  // Deduplicate (owner, method): the group helper restates entries the single
-  // helper already produced (e.g. my-domain wires each method, then groups them).
-  // Prefer the entry whose config resolves to a real object (the single helper),
-  // falling back to the group entry (which references a variable / todo()).
-  const byKey = new Map<string, WiredMethod>()
-  for (const w of wired) {
-    const key = `${w.ownerKind ?? 'legacy'}:${w.owner}.${w.method}`
-    const existing = byKey.get(key)
-    if (!existing) {
-      byKey.set(key, w)
-      continue
-    }
-    // Prefer the one whose config is an object literal (richer info).
-    const existingIsObj = Node.isObjectLiteralExpression(existing.config)
-    const candidateIsObj = Node.isObjectLiteralExpression(w.config)
-    if (candidateIsObj && !existingIsObj) byKey.set(key, w)
-  }
-
-  const links: HandlerLink[] = []
-  for (const w of byKey.values()) {
-    const ownerKind: 'class' | 'interface' | 'function' =
-      w.ownerKind ?? (interfaceNames.has(w.owner) ? 'interface' : 'class')
-    const isStatic = irMethodStatic(ir, w.owner, w.method, ownerKind)
-
-    const link: HandlerLink = {
-      owner: w.owner,
-      ownerKind,
-      method: w.method,
-      static: isStatic,
-      wiringFile: w.wiringFile,
-      wiringLine: w.wiringLine,
-      implemented: true,
-    }
-
-    let target: { file: string; line: number } | undefined
-    if (w.style === 'direct-handler') {
-      const direct = resolveDirectHandler(w.config)
-      link.implemented = direct.implemented
-      target = direct.target
-      applyCanonicalMethodAuth(link, ir, w.owner, w.method, ownerKind)
-    } else {
-      const resolution = resolveConfigObject(w.config)
-      link.implemented = resolution.implemented
-      if (resolution.auth) link.auth = resolution.auth
-      if (resolution.authorize) link.authorize = resolution.authorize
-      if (resolution.authorizeSnippet) link.authorizeSnippet = resolution.authorizeSnippet
-      if (resolution.executeNode) target = resolveExecuteTarget(resolution.executeNode)
-    }
-
-    if (target) {
-      link.handlerFile = relToRoot(domainRoot, target.file)
-      link.handlerLine = target.line
-      const kernelCalls = scanKernelCalls(target.file)
-      if (kernelCalls.length > 0) link.kernelCalls = kernelCalls
-    } else {
-      link.unlinked = true
-    }
-
-    links.push(link)
-  }
-
-  // Stable order: by owner, then method.
-  links.sort((a, b) =>
-    a.owner === b.owner ? a.method.localeCompare(b.method) : a.owner.localeCompare(b.owner),
-  )
-  return links
-}
-
-/** Whether a call is the current SDK composition entrypoint. */
-function isDefineDomainCall(call: CallExpression): boolean {
-  const expression = unwrapExpression(call.getExpression())
-  if (Node.isIdentifier(expression)) return expression.getText() === 'defineDomain'
-  if (!Node.isPropertyAccessExpression(expression) || expression.getName() !== 'public') {
-    return false
-  }
-  const receiver = unwrapExpression(expression.getExpression())
-  return Node.isIdentifier(receiver) && receiver.getText() === 'defineDomain'
-}
-
-/** Resolve a value to an object literal, following local/imported identifiers. */
-function resolveObjectLiteral(
-  node: Node,
-  seen = new Set<string>(),
-): import('ts-morph').ObjectLiteralExpression | undefined {
-  const value = unwrapExpression(node)
-  const key = `${value.getSourceFile().getFilePath()}:${value.getStart()}`
-  if (seen.has(key)) return undefined
-  seen.add(key)
-  if (Node.isObjectLiteralExpression(value)) return value
-  if (Node.isIdentifier(value)) {
-    const resolved = valueOfIdentifier(value)
-    if (resolved) return resolveObjectLiteral(resolved, seen)
-  }
-  return undefined
-}
-
-/** Value carried by an object-literal property, including shorthand/method syntax. */
-function objectPropertyValue(prop: Node): Node | undefined {
-  if (Node.isPropertyAssignment(prop)) return prop.getInitializer()
-  if (Node.isShorthandPropertyAssignment(prop)) return prop.getNameNode()
-  if (Node.isMethodDeclaration(prop)) return prop
-  return undefined
-}
-
-/** Collect current `handlers.classes/interfaces.Owner.method = fn` bindings. */
-function collectDirectHandlerSection(
-  out: WiredMethod[],
-  handlers: import('ts-morph').ObjectLiteralExpression,
-  section: 'classes' | 'interfaces',
-  ownerKind: 'class' | 'interface',
-  wiringFile: string,
-): void {
-  const sectionValue = getProp(handlers, section)
-  const sectionObject = sectionValue ? resolveObjectLiteral(sectionValue) : undefined
-  if (!sectionObject) return
-  for (const ownerProp of sectionObject.getProperties()) {
-    const owner = propertyKey(ownerProp)
-    const ownerValue = objectPropertyValue(ownerProp)
-    const ownerObject = ownerValue ? resolveObjectLiteral(ownerValue) : undefined
-    if (!owner || !ownerObject) continue
-    for (const methodProp of ownerObject.getProperties()) {
-      const method = propertyKey(methodProp)
-      const handler = objectPropertyValue(methodProp)
-      if (!method || !handler) continue
-      out.push({
-        owner,
-        ownerKind,
-        method,
-        config: handler,
-        wiringLine: methodProp.getStartLineNumber(),
-        wiringFile,
-        style: 'direct-handler',
-      })
-    }
-  }
-}
-
-/** Collect current standalone `handlers.functions.name = fn` bindings. */
-function collectDirectFunctionHandlers(
-  out: WiredMethod[],
-  handlers: import('ts-morph').ObjectLiteralExpression,
-  owner: string,
-  wiringFile: string,
-): void {
-  const functionsValue = getProp(handlers, 'functions')
-  const functions = functionsValue ? resolveObjectLiteral(functionsValue) : undefined
-  if (!functions) return
-  for (const functionProp of functions.getProperties()) {
-    const method = propertyKey(functionProp)
-    const handler = objectPropertyValue(functionProp)
-    if (!method || !handler) continue
-    out.push({
-      owner,
-      ownerKind: 'function',
-      method,
-      config: handler,
-      wiringLine: functionProp.getStartLineNumber(),
-      wiringFile,
-      style: 'direct-handler',
-    })
-  }
-}
-
-/** Follow a direct SDK handler to its defining source node. */
-function resolveDirectHandler(config: Node): {
-  implemented: boolean
-  target?: { file: string; line: number }
-} {
-  let value = unwrapExpression(config)
-  if (Node.isIdentifier(value)) value = valueOfIdentifier(value) ?? value
-  value = unwrapExpression(value)
-  const concrete =
-    Node.isArrowFunction(value) ||
-    Node.isFunctionExpression(value) ||
-    Node.isFunctionDeclaration(value) ||
-    Node.isMethodDeclaration(value) ||
-    Node.isCallExpression(value)
-  if (!concrete) return { implemented: false }
-  return {
-    implemented: Node.isCallExpression(value) ? true : !isStubFunction(value),
-    target: { file: value.getSourceFile().getFilePath(), line: value.getStartLineNumber() },
-  }
-}
-
-/** Map the canonical callable auth declaration onto the existing Studio badge model. */
-function applyCanonicalMethodAuth(
-  link: HandlerLink,
-  ir: SchemaIR | null,
-  owner: string,
-  method: string,
-  ownerKind: 'class' | 'interface' | 'function',
-): void {
-  const callable =
-    ownerKind === 'function'
-      ? ir?.functions?.[method]
-      : ownerKind === 'interface'
-        ? ir?.interfaces?.[owner]?.methods?.[method]
-        : ir?.classes?.[owner]?.methods?.[method]
-  const auth = callable?.auth
-  if (auth) link.callableAuth = auth
-  if (auth === 'anonymous') {
-    link.auth = 'public'
-    link.authorize = 'absent'
-  } else if (auth === 'authorized') {
-    link.auth = 'required'
-    link.authorize = 'custom'
-  } else if (auth === 'authenticated') {
-    link.auth = 'required'
-    link.authorize = 'absent'
-  }
-}
-
-/** Look up a method's `static` flag from the IR (class or interface bucket). */
-function irMethodStatic(
-  ir: SchemaIR | null,
-  owner: string,
-  method: string,
-  ownerKind: 'class' | 'interface' | 'function',
-): boolean {
-  if (!ir) return false
-  if (ownerKind === 'function') return true
-  const bucket = ownerKind === 'interface' ? ir.interfaces?.[owner] : ir.classes?.[owner]
-  const m = bucket?.methods?.[method]
-  return m ? m.static === true : false
-}
-
-// ───────────────────────────── source spans ─────────────────────────────
-
-const DECL_HELPERS: Record<string, 'node' | 'interface' | 'edge' | 'function'> = {
-  nodeClass: 'node',
-  nodeInterface: 'interface',
-  edgeClass: 'edge',
-  fn: 'function',
-}
-
-/** Recognize both legacy `edgeClass(...)` and current
- * `edgeClass.directed/undirected({...})` authoring forms. */
-function declarationHelper(
-  call: CallExpression,
-): 'node' | 'interface' | 'edge' | 'function' | undefined {
-  const direct = calleeName(call)
-  if (direct && direct in DECL_HELPERS) return DECL_HELPERS[direct]
-  const expression = call.getExpression()
-  if (
-    Node.isPropertyAccessExpression(expression) &&
-    (expression.getName() === 'directed' || expression.getName() === 'undirected') &&
-    expression.getExpression().getText() === 'edgeClass'
-  ) {
-    return 'edge'
-  }
-  return undefined
-}
-
-/**
- * A schema member's true NAME + section, resolved from the `defineSchema` map.
- * The declaration helpers (nodeClass/nodeInterface/edgeClass) carry no name — a
- * member is named by the KEY it is registered under, not by its variable — and a
- * domain may register a class and an interface under the SAME name (the
- * intentional same-name pattern: the `iUser` interface alongside the `User`
- * class). So the map is the sole authority for both the anchor name and the
- * interface-vs-class distinction; the variable identifier alone tells us neither.
- */
-interface MemberName {
-  schemaName: string
-  section: 'interface' | 'class' | 'function' // the `classes` map also holds edge classes
-}
-
-interface MemberNameMap {
-  /** Exact declaration initializer, robust to imported/local aliases. */
-  byValue: Map<string, MemberName>
-  /** Legacy fallback when a symbol cannot be resolved. */
-  byIdentifier: Map<string, MemberName>
-}
-
-/** Stable source coordinate for the value behind a local/imported alias. */
-function memberValueKey(node: Node, seen = new Set<string>()): string | undefined {
-  const value = unwrapExpression(node)
-  const key = `${value.getSourceFile().getFilePath()}:${value.getStart()}`
-  if (seen.has(key)) return undefined
-  seen.add(key)
-  if (Node.isIdentifier(value)) {
-    const resolved = valueOfIdentifier(value)
-    if (resolved) return memberValueKey(resolved, seen)
-  }
-  return key
-}
-
-/** Map each registered member VARIABLE (as referenced in `defineSchema`) to its
- *  schema name + section, from the domain's own schema files — never node_modules
- *  (a dependency's `defineSchema` is not this domain's). */
-function buildMemberNameMap(files: SourceFile[]): MemberNameMap {
-  const map: MemberNameMap = {
-    byValue: new Map<string, MemberName>(),
-    byIdentifier: new Map<string, MemberName>(),
-  }
-  for (const sf of files) {
-    if (sf.getFilePath().includes('/node_modules/')) continue
-    for (const call of sf.getDescendantsOfKind(SyntaxKind.CallExpression)) {
-      if (calleeName(call) !== 'defineSchema') continue
-      const input = call.getArguments()[1]
-      const cfg = input ? resolveObjectLiteral(input) : undefined
-      if (!cfg) continue
-      collectSchemaSection(map, cfg, 'interfaces', 'interface')
-      collectSchemaSection(map, cfg, 'classes', 'class')
-      collectSchemaSection(map, cfg, 'functions', 'function')
-    }
-  }
-  return map
-}
-
-/** Record `variable → { schemaName, section }` for one `defineSchema` section,
- *  handling both `Key: alias` and shorthand `Key`. */
-function collectSchemaSection(
-  map: MemberNameMap,
-  cfg: Node,
-  prop: 'interfaces' | 'classes' | 'functions',
-  section: 'interface' | 'class' | 'function',
-): void {
-  const obj = getObjectProp(cfg, prop)
-  if (!obj) return
-  for (const p of obj.getProperties()) {
-    const schemaName = propertyKey(p)
-    const memberValue = objectPropertyValue(p)
-    if (!schemaName || !memberValue) continue
-    const member = { schemaName, section } satisfies MemberName
-    const valueKey = memberValueKey(memberValue)
-    if (valueKey) map.byValue.set(valueKey, member)
-    const unwrapped = unwrapExpression(memberValue)
-    if (Node.isIdentifier(unwrapped)) map.byIdentifier.set(unwrapped.getText(), member)
-  }
-}
-
-/**
- * The anchor namespace ('class' | 'interface' | 'edge') for a declared member.
- * The `defineSchema` SECTION is authoritative for interface-vs-class — a
- * `nodeClass` whose name collides with a same-named interface must still anchor
- * as a class. Within the class section, an `edgeClass` (or an IR edge type)
- * anchors as 'edge'. Falls back to the declaration helper when the member isn't
- * in a parseable `defineSchema` map (e.g. an imported kernel member).
- */
-function resolveMemberKind(
-  ir: SchemaIR | null,
-  name: string,
-  section: 'interface' | 'class' | 'function' | undefined,
-  helperKind: 'node' | 'interface' | 'edge' | 'function',
-): 'class' | 'interface' | 'edge' | 'function' {
-  if (section === 'function' || helperKind === 'function') return 'function'
-  if (section === 'interface') return 'interface'
-  const isEdge = helperKind === 'edge' || ir?.classes?.[name]?.type === 'edge'
-  if (section === 'class') return isEdge ? 'edge' : 'class'
-  if (helperKind === 'interface') return 'interface'
-  return isEdge ? 'edge' : 'class'
-}
-
-export function buildSourceSpans(args: {
-  ir: SchemaIR | null
-  schemaDir: string
-}): Record<string, SourceSpan> {
-  const { ir, schemaDir } = args
-  if (!schemaDir || !existsSync(schemaDir)) return {}
-
-  // The domain root is the parent of the schema dir (spans are relative to it).
-  const domainRoot = dirname(schemaDir.replace(/\/$/, ''))
-
-  const project = newProject()
-  let files: string[] = []
-  try {
-    const added = project.addSourceFilesAtPaths(`${schemaDir.replace(/\/$/, '')}/**/*.ts`)
-    files = added.map((f) => f.getFilePath())
-  } catch {
-    return {}
-  }
-
-  const spans: Record<string, SourceSpan> = {}
-
-  const sourceFiles = files.map((f) => project.getSourceFile(f)).filter((f): f is SourceFile => !!f)
-  // The domain's `defineSchema` map is authoritative for each member's name +
-  // interface-vs-class kind, so an aliased interface (`iUser`→`User`) and a class
-  // sharing its name (`User`) each anchor correctly instead of colliding.
-  const memberNames = buildMemberNameMap(sourceFiles)
-
-  for (const sf of sourceFiles) {
-    const fileRel = relToRoot(domainRoot, sf.getFilePath())
-
-    for (const v of sf.getVariableDeclarations()) {
-      if (!v.isExported()) continue
-      const init = v.getInitializer()
-      if (!init || !Node.isCallExpression(init)) continue
-      const helperKind = declarationHelper(init)
-      if (!helperKind) continue
-      const valueKey = memberValueKey(init)
-      const member =
-        (valueKey ? memberNames.byValue.get(valueKey) : undefined) ??
-        memberNames.byIdentifier.get(v.getName())
-      const name = member?.schemaName ?? v.getName()
-      const ns = resolveMemberKind(ir, name, member?.section, helperKind)
-
-      const stmt = v.getVariableStatement() ?? v
-      spans[`${ns}.${name}`] = makeSpan(domainRoot, fileRel, stmt, v)
-
-      // The single object-literal argument: nodeClass({ properties, methods })
-      // and current edgeClass.directed({ source, target, properties }).
-      const cfgArg = init.getArguments()[0]
-      if (ns !== 'function' && cfgArg && Node.isObjectLiteralExpression(cfgArg)) {
-        collectPropsAndMethods(spans, ns, name, cfgArg, domainRoot, fileRel)
-      }
-
-      // Edges: endpoints are the first two args; props live in the third.
-      if (ns === 'edge') {
-        collectEdge(spans, name, init, domainRoot, fileRel)
-      }
-    }
-  }
-
-  return spans
-}
-
-/** Build a SourceSpan, harvesting leading doc from the declaration `docNode`. */
-function makeSpan(domainRoot: string, fileRel: string, spanNode: Node, docNode: Node): SourceSpan {
-  const span: SourceSpan = {
-    file: fileRel,
-    startLine: spanNode.getStartLineNumber(),
-    endLine: spanNode.getEndLineNumber(),
-  }
-  const doc = leadingDoc(docNode) ?? leadingDoc(spanNode)
-  if (doc) span.doc = doc
-  return span
-}
-
-/** Record `<ns>.<Name>.property.<p>` and `.method.<m>` from a config object. */
-function collectPropsAndMethods(
-  spans: Record<string, SourceSpan>,
-  ns: string,
-  name: string,
-  cfg: Node,
-  domainRoot: string,
-  fileRel: string,
-): void {
-  if (!Node.isObjectLiteralExpression(cfg)) return
-  const propsObj = getObjectProp(cfg, 'properties') ?? getObjectProp(cfg, 'props')
-  if (propsObj) {
-    for (const p of propsObj.getProperties()) {
-      const pName = propertyKey(p)
-      if (!pName) continue
-      spans[`${ns}.${name}.property.${pName}`] = makeSpan(domainRoot, fileRel, p, p)
-    }
-  }
-  const methodsObj = getObjectProp(cfg, 'methods')
-  if (methodsObj) {
-    for (const m of methodsObj.getProperties()) {
-      const mName = propertyKey(m)
-      if (!mName) continue
-      spans[`${ns}.${name}.method.${mName}`] = makeSpan(domainRoot, fileRel, m, m)
-    }
-  }
-}
-
-/** Record edge endpoint spans `edge.<Name>.endpoint.<role>` from the two args. */
-function collectEdge(
-  spans: Record<string, SourceSpan>,
-  name: string,
-  init: CallExpression,
-  domainRoot: string,
-  fileRel: string,
-): void {
-  const argsList = init.getArguments()
-  const expression = init.getExpression()
-  const currentObjectForm =
-    Node.isPropertyAccessExpression(expression) &&
-    (expression.getName() === 'directed' || expression.getName() === 'undirected') &&
-    argsList[0] &&
-    Node.isObjectLiteralExpression(argsList[0])
-
-  if (currentObjectForm) {
-    const config = argsList[0]
-    if (Node.isObjectLiteralExpression(config)) {
-      for (const endpointName of ['source', 'target'] as const) {
-        const ep = getObjectProp(config, endpointName)
-        if (!ep) continue
-        const role = stringLiteralOfProp(ep, 'as') ?? stringLiteralOfProp(ep, 'role')
-        if (role) spans[`edge.${name}.endpoint.${role}`] = makeSpan(domainRoot, fileRel, ep, ep)
-      }
-      const properties = getObjectProp(config, 'properties') ?? getObjectProp(config, 'props')
-      if (properties) {
-        for (const p of properties.getProperties()) {
-          const pName = propertyKey(p)
-          if (!pName) continue
-          spans[`edge.${name}.property.${pName}`] = makeSpan(domainRoot, fileRel, p, p)
-        }
-      }
-    }
-    return
-  }
-
-  for (let i = 0; i < Math.min(2, argsList.length); i++) {
-    const ep = argsList[i]
-    if (!Node.isObjectLiteralExpression(ep)) continue
-    const role = stringLiteralOfProp(ep, 'as')
-    if (!role) continue
-    spans[`edge.${name}.endpoint.${role}`] = makeSpan(domainRoot, fileRel, ep, ep)
-  }
-  // Legacy edge props live in the third (config) arg.
-  const cfgArg = argsList[2]
-  if (cfgArg && Node.isObjectLiteralExpression(cfgArg)) {
-    const propsObj = getObjectProp(cfgArg, 'properties') ?? getObjectProp(cfgArg, 'props')
-    if (propsObj) {
-      for (const p of propsObj.getProperties()) {
-        const pName = propertyKey(p)
-        if (!pName) continue
-        spans[`edge.${name}.property.${pName}`] = makeSpan(domainRoot, fileRel, p, p)
-      }
-    }
-  }
-}
-
-/** The object-literal value of a named property, if it is itself an object. */
-function getObjectProp(
-  obj: Node,
-  name: string,
-): import('ts-morph').ObjectLiteralExpression | undefined {
-  if (!Node.isObjectLiteralExpression(obj)) return undefined
-  const prop = obj.getProperty(name)
-  if (!prop) return undefined
-  let value: Node | undefined
-  if (Node.isPropertyAssignment(prop)) value = prop.getInitializer()
-  else if (Node.isShorthandPropertyAssignment(prop)) value = prop.getNameNode()
-  return value ? resolveObjectLiteral(value) : undefined
-}
-
-/** A string-literal property value, e.g. `as: 'page'` → 'page'. */
-function stringLiteralOfProp(obj: Node, name: string): string | undefined {
-  if (!Node.isObjectLiteralExpression(obj)) return undefined
-  const prop = obj.getProperty(name)
-  if (!prop || !Node.isPropertyAssignment(prop)) return undefined
-  const v = prop.getInitializer()
-  if (v && (Node.isStringLiteral(v) || Node.isNoSubstitutionTemplateLiteral(v)))
-    return v.getLiteralText()
-  return undefined
-}
-
-/** The key name of an object-literal property (assignment / shorthand / method). */
-function propertyKey(prop: Node): string | undefined {
-  if (
-    Node.isPropertyAssignment(prop) ||
-    Node.isShorthandPropertyAssignment(prop) ||
-    Node.isMethodDeclaration(prop)
-  ) {
-    const nameNode = prop.getNameNode()
-    if (Node.isStringLiteral(nameNode)) return nameNode.getLiteralText()
-    if (Node.isComputedPropertyName(nameNode)) return undefined // skip `[expr]: …`
-    return nameNode.getText()
-  }
-  // Spread (`...knobs`) — no single key.
-  return undefined
-}
-
-// ───────────────────────────── annotations ─────────────────────────────
-
-export function buildSchemaAnnotations(_args: { ir: SchemaIR | null }): SchemaAnnotation[] {
-  // The current Kernel admits updated values against their exact Value Schema;
-  // enum properties therefore need no Studio-specific compatibility warning.
-  return []
-}
+export { buildSchemaAnnotations } from './source-overlay/annotations'
+export { buildHandlerLinks } from './source-overlay/handlers'
+export { buildSourceSpans } from './source-overlay/spans'