fix(sync): a member reference through an import binding links its module when the module changes

[colbymchenry]

Problem

A member reference through an import binding is linked by a fresh index through the import (calls, resolvedBy: import):

• NODE_PATH_EXCLUDELIST.includes(p) after import { NODE_PATH_EXCLUDELIST } from './constants', to the constant;
• store.get(k) through a default import, to the store;
• useStore.setState() through an aliased import;
• api.get() through a namespace import, to the module's export.

When the module was missing, or lacked the export, when the importing file was indexed, the reference failed. It was parked under its tail (#1240), which for a member is the member's name: includes, get, setState, map. A sync that later restored the module or gave it the export never relinked it:

• the module seldom declares a symbol named includes or get, so the name lookup never matched;
• and getRetryableFailedReferences skips any name with more than 500 failed references. On real repos, includes, map, get, forEach and setState all have that many.

Evidence (2026-10-07, on main ed199e6 and #2450): every 7th source file was held out or emptied, the rest indexed, the files restored, synced, and compared with a fresh index. That left 194 such residues across 45 runs. Examples: infrahub NODE_PATH_EXCLUDELIST.includes and store.set (63), ghostfolio SCOPES_OF_WRITE_ACCESS.includes, milo-ui REGISTERED_FLAGS.get and COLUMNS.map, folo useEntryStore.setState (19).

Re-checked on current main (3be906f)

Main has changed since then. #2512 now re-opens an importer's failed references through the bindings of an added module, member reads included, so the held-out runs above are fixed on main. What is left, measured with this PR's tests against main's source:

• an edit that gives an existing module its export (the emptied-module runs, most of the residues above): 7 of 7 member links stay unlinked;
• an edit that gives the export to a file a barrel forwards (export * from './shared/flags'): unlinked;
• a module added later or restored in a project that uses Vue, imported through a tsconfig alias (@/flags/registry, a SFC's @/table): 2 of 7 stay unlinked. Vue's resolver links the import's module specifier to the constant the file declares, not to the file. fix(sync): imports through a re-exporting module follow it when it is deleted or added #2512 finds importers through imports edges into the file node, so it never finds this one.

Fix

A direct member reference (R.m) through an import binding of a project module is parked under the module's key, the way #2450 parks a whole name through a binding (importBindingTail, ES-module family; Python is unchanged). #2450 showed that re-keying a parked reference must keep every trigger it had, so it now waits for three names:

trigger	why it matters	how sync finds it
its module (module:constants)	the file that appears or gains the export	name_tail IN (moduleReferenceKeys), the existing lookup under #2507's module-key ceiling; #2560's barrel walk also re-opens it under a barrel's key
its member (includes, make)	a namespace import's barrel forwards the member from a file of another name; a guess by name (instance-method) links a receiver whose module never resolves	new idx_unresolved_failed_module_member (schema v16), an expression index on the tail the name gives. It shares one ceiling with the references still under that tail, so main's decision for every member name is unchanged
its receiver (FLAGS of FLAGS.includes)	a barrel's import of the declaring file that no walk finds (the Vue case above)	new prefix range FLAGS. to FLAGS/ on #2450's idx_unresolved_failed_module_name

The two other readers of a failed call's tail still find these:

• the router navigation retry (getFailedCallsByTail): router.push parked under module:router;
• the dead-code check (getUnresolvedNamesAmong).

Both read module-parked rows by member through the new index.

Not chains or longer paths. URI.file(p).toString() and vscode.window.showErrorMessage keep their member's tail. Their last member hangs off what another member returns or holds, seldom a type the module declares. Parking them too tripled the refs an edit of vscode's uri.ts retries (+2,497 refs, +363 ms), and none of them resolved. Across 19 repos the only cost of leaving them out is two .vue chains in vue3-element-admin.

Rows parked before v16 keep their member tails, which the tail lookup still finds; a re-index parks them under their modules. The v16 migration only creates the partial index (155 ms on vscode's index).

Validation

Tests. __tests__/sync-import-member-retry.test.ts has 16 tests. Each integration test compares the synced graph with a fresh index of the final tree in a second folder.

• Fail on main, missing links (5): module added after its importers (5 of 7 linked), restored after a delete (5 of 7), an edit giving the module its exports (0 of 7), a barrel's source file gaining the declaration (0 of 1), and the same through an alias barrel in a Vue project (0 of 1).
• Pass on main (1): a barrel's source file added later, which fix(sync): imports through a re-exporting module follow it when it is deleted or added #2512 already covers.
• Non-regression (3): a namespace member forwarded by a barrel from another folder, a by-name guess, and router.push relinked by the navigation retry. Each asserts the module-parked tail first, which is where they fail on main; without that line they pass on main too.
• Tails (1): what is parked where. Chains, paths, package bindings and unbound receivers keep their tails.
• Schema v16 (6): the lookups, the shared ceiling, the plans (each new lookup uses its index), the migration replay, and schema.sql spelling the expression MEMBER_TAIL_SQL defines.
• Mutations: dropping the member lookup, the receiver lookup, the navigation arm or the dead-code arm each fails its own tests.
• sync-import-binding-retry.test.ts (fix(sync): a reference through an import binding links its module when the module appears later #2450) now expects NS.make under module:ns: a namespace member waits for its module too, and its member name is still a key.
• The retry suites of fix(sync): a reference through an import binding links its module when the module appears later #2450, fix(sync): a Python import alias links its module when the module appears later #2501/fix(sync): a Python import of a name a package re-exports links when the package appears later #2507 (Python), fix(sync): a route links the module it lazily loads when the module appears later #2422 and fix(sync): a lazy route relinks a page that appears below its barrel #2560, plus this one: 51 passed on the final commit. Full suite on the final commit: 7,247 passed, 0 failed, 82 skipped (Windows).

A/B on the 19-repo kit from #2450, main 3be906f against this PR, with the same kernel. Each arm's synced graph is compared with its own fresh index. Cells are differing graph lines.

emptied every 7th file, then restored	main	this PR	what went
infrahub	146	0	store.set ×63, store.get ×5, NODE_PATH_EXCLUDELIST / OBJECT_PERMISSION_* .includes
milo-ui	924	854	CRYSTAL_BALL_ROUTES.DASHBOARD_DETAIL ×8, HISTORY_TIME_RANGE_OPTIONS.*, *_ERROR_CODES.includes, mocked hooks (useTasks.mockReturnValue …)
folo	216	198	i18n.t, kv.get, useUserStore.setState, PROVIDER_OPTIONS.filter, …
ghostfolio	80	72	SCOPES_OF_WRITE_ACCESS.includes
vue-realworld	10	4	a navigation call through an imported router
vue3-element-admin, vue-element-admin	182, 18	182, 18	—
10 other JS repos	0	0	—

• Every changed residue bucket went down; none went up.
• Held-out files and held-out route modules are unchanged on every repo: fix(sync): imports through a re-exporting module follow it when it is deleted or added #2512 already relinks those.
• vben fails codegraph sync with FOREIGN KEY constraint failed on both arms in all three scenarios: that is codegraph sync fails with "FOREIGN KEY constraint failed" after d0bb9be5 when a file lazy-loads a workspace package #2565, with fix PR fix(sync): record only indexed files as synthesis inputs (#2565) #2574 open.
• What is left: same-edge metadata differences, retargets, whole-name imports through barrels, and member calls on locals typed by an imported class (const cache = new LRUCache(); cache.get(k)).
• Fresh indexes: nodes, edges and files byte-identical on all 19 repos. unresolved_refs differ only in name_tail, every one calls failed: <member> -> module:*.

Cost on vscode's index (816K failed refs; the shared copy opened read-only, lookups on a private copy; interleaved rounds, medians):

	main	this PR
parking decisions, per full index	919 ms	1,296 ms
references parked under a module key	1,236	6,333 (5,097 member refs; 3 keys over 500, none over 5,000)
retry lookup: uri.ts / 10 files / 100 / 1,000 changed TS files	5.4 / 15.5 / 377 / 2,807 ms	7.0 / 19.4 / 438 / 3,023 ms
refs re-resolved: uri.ts / lifecycle.ts / dom.ts edit	1,219 / 1,877 / 4,423	1,226 / 1,883 / 5,060
their resolution: uri.ts / dom.ts / 100 files	499 / 2,910 / 7,084 ms	499 / 3,104 / 7,197 ms
navigation retry lookup, dead-code names (5,421)	60 ms, 2,720 ms	64 ms, 2,649 ms
failed module keys (#2560's barrel pre-check)	1.3 ms	4.7 ms

dom.ts retries 637 more refs: vscode's dom.* calls go through an import whose module never resolves, so they now wait under module:dom. That is the trigger this PR adds, and an edit of dom.ts is what can resolve them.

Notes

• Vue's module specifiers. Vue's resolver links an imports ref named by a module path (@/flags/registry) to a symbol of the module rather than its file node (resolvedBy: framework). That hides the importer from fix(sync): imports through a re-exporting module follow it when it is deleted or added #2512's and fix(sync): a lazy route relinks a page that appears below its barrel #2560's walks, which follow edges into file nodes. This PR doesn't depend on that edge. The resolver behavior itself could be a separate fix.
• Follow-ups: member calls on locals typed by an imported class (cache.get above); Python member calls through aliases.

🤖 Generated with Claude Code