feat(group): bridge.lbug storage + contract matching expansion (1/4 of #606 split)

[ivkond]

Part 1 of 4 in the split of #606 per @magyargergo's request.

Closes #791.

What changed

Adds the LadybugDB-backed bridge storage infrastructure and extends the contract matching algorithm with wildcard support. All changes are additive — storage.ts, sync.ts, service.ts, cli/group.ts, and mcp/tools.ts are left on their current upstream `main` versions and will migrate to the new bridge in follow-up PRs.

New (844 LOC prod):

• `gitnexus/src/core/group/bridge-db.ts` — atomic write-to-temp with `retryRename` for Windows EBUSY/EPERM, per-item write tolerance via `WriteBridgeReport`, `findContractNode` with three-tier symbol lookup
• `gitnexus/src/core/group/bridge-schema.ts` — schema DDL
• `gitnexus/src/core/group/normalization.ts` — contract ID canonicalization + `dedupeContracts` / `dedupeCrossLinks` helpers

Modified (+137 LOC prod):

• `matching.ts` — adds `runWildcardMatch` for `grpc::Service/*` wildcard consumers, `buildProviderIndex`, canonical gRPC ID handling
• `types.ts` — `MatchType` gains `'wildcard'`; new `BridgeHandle` and `BridgeMeta` interfaces

New tests (658 LOC):

• `bridge-db.test.ts`, `bridge-db-edge.test.ts` — core write/read round trip, `WriteBridgeReport` shape, dropped-links counter, `retryRename` behavior on EBUSY/ENOENT/EPERM/EACCES, edge cases

Modified tests (+225 LOC):

• `matching.test.ts` — wildcard consumer matching, gRPC canonical ID handling, same-service guard

Self-review fixes folded in

Carried forward from the original #606 self-review (see commit body for full list):

• `writeBridge` try/finally handle lifecycle + `handleClosed` sentinel
• `openBridgeDbReadOnly` partial-handle cleanup
• `writeBridgeMeta` uses `retryRename`
• `retryRename` unit tests (was zero coverage)
• Per-item try/catch around every CREATE loop
• Dropped cross-link counter

How to verify

```bash
cd gitnexus
npx tsc --noEmit
npx vitest run test/unit/group/bridge-db.test.ts --pool=forks
npx vitest run test/unit/group/bridge-db-edge.test.ts --pool=forks
npx vitest run test/unit/group/matching.test.ts --pool=forks
```

Pre-commit hook should run clean.

Risk / rollback

Low. All new code sits under `src/core/group/` in new files plus a minimal `+16/-1` diff to `types.ts` and `+136/-0` diff to `matching.ts` (both purely additive). No existing callers reference the new APIs — the PRs that wire them in come later in the split chain. Rollback = `git revert`; no state introduced, no schema migration triggered.

Scope discipline (per `GUARDRAILS.md`)

• Only the 8 files listed above are touched; no drive-by refactors
• No CI/release/security config changes
• No secrets
• Content is lifted from the [group] Cross-repo impact analysis via repository groups #606 branch which passed CI 11/11 green on `d15b8cb` before the split

Dependencies

• Base: `main`
• Blocks: extractor expansion ([group] Service boundary detection and language contract extractors (split 3/5 of #606) #792), sync pipeline ([group] Sync pipeline (split 4/5 of #606) #793), cross-impact feature ([group] Cross-repo impact analysis, CLI and MCP tool (split 5/5 of #606) #794)
• Tracker issue: [group] Bridge storage and contract matching foundation (split 2/5 of #606) #791
• Parent PR: [group] Cross-repo impact analysis via repository groups #606 (will be closed once all 4 split PRs merge)

🤖 Co-authored with Claude Code — findings and fixes written by me, Claude ran the test/edit loop. I reviewed and signed off on every change before pushing.

[vercel]

@ivkond is attempting to deploy a commit to the NexusCore Team on Vercel.

A member of the Team first needs to authorize it.

[magyargergo]

@claude is this pr ready for production? Is this following clean code principles? Are there any performance bottlenecks? Is the code structured in a way that will unlock easy contributions in the future?

[github-actions]

Claude finished @magyargergo's task in 3m 4s —— View job

---

PR Review — feat(group): bridge.lbug storage + contract matching expansion

• Gather context and understand request
• Read changed files
• Analyze production readiness
• Analyze clean code principles
• Identify performance bottlenecks
• Evaluate contribution-friendliness

---

Overall Verdict

Conditionally ready for production. The architectural foundations are solid — atomic swap, backup recovery, per-item fault tolerance, and schema versioning are all correctly implemented. There are no blocking bugs, but two medium-severity issues should be fixed before this ships, and a handful of minor items worth tracking.

---

Production Readiness

Strengths:

• ✅ Atomic write-to-temp-then-rename pattern prevents partial bridge state
• ✅ .bak recovery path in openBridgeDbReadOnly handles interrupted swaps
• ✅ try/finally + handleClosed sentinel correctly prevents resource leaks even on mid-write exceptions
• ✅ WriteBridgeReport surfaces partial-success state without aborting the sync
• ✅ retryRename with exponential backoff correctly handles Windows EBUSY/EPERM/EACCES
• ✅ Schema version gate prevents incompatible reads with a clean fallback
• ✅ dedupeContracts / dedupeCrossLinks prevents duplicate inserts before DB write

Medium issue — openBridgeDbReadOnly bak recovery uses bare fsp.rename instead of retryRename (bridge-db.ts:416):

// Current — inconsistent with rest of file on Windows
await fsp.rename(bakPath, dbPath);

// Should be
await retryRename(bakPath, dbPath);

The very scenario this recovery path exists for (interrupted write on Windows) is also the scenario where the rename of the .bak file is most likely to get an EBUSY. Fix this →

Medium issue — ensureBridgeSchema detects existing-table errors by message substring (bridge-db.ts:34):

if (!msg.includes('already exists')) throw err;

This is fragile: a LadybugDB version bump that rephrases its error message would silently break idempotent schema creation (or worse, swallow real errors). If the DDL syntax supports IF NOT EXISTS, that's the clean fix. If not, at minimum the matched string should be a named constant or the LadybugDB error code (if one exists) should be used. Fix this →

Minor — queryBridge could panic if LadybugDB returns an empty array (bridge-db.ts:52):

const result = Array.isArray(queryResult) ? queryResult[0] : queryResult;
// queryResult[0] is `undefined` if array is empty → .getAll() throws

Worth adding a guard: const result = Array.isArray(queryResult) ? (queryResult[0] ?? queryResult) : queryResult; — or confirming with a LadybugDB test that the driver never returns an empty top-level array.

---

Clean Code

Strengths:

• ✅ Module boundaries are coherent and purposeful (bridge-db = I/O, bridge-schema = DDL, normalization = dedup logic, matching = algorithms)
• ✅ Function names are descriptive and idiomatic
• ✅ The contractRichness scoring approach in normalization.ts is elegant
• ✅ Comments on gRPC canonicalization (matching.ts:42–51) are genuinely helpful — rare and appreciated
• ✅ MAX_SAMPLE_ERRORS constant prevents unbounded report growth

Issue — findContractNode is a 35-line async closure buried inside writeBridge (bridge-db.ts:278-313):

This is the most significant clean code concern. A 200+ line function containing a 35-line inner function that does its own multi-step DB lookup is hard to read and impossible to test in isolation. Extracting it as a module-private function findContractNode(handle, repo, role, symbolUid, filePath, symbolName) would make the write loop much cleaner and unlock targeted unit tests. Fix this →

Minor — magic numbers in contractRichness (normalization.ts:19-26):
The weights (3, 2, 2, 2, 1, 1) carry implicit policy about what makes a contract "richer" but have no names or comments explaining the rationale. A brief comment or named constants would help contributors understand the priority ordering without reverse-engineering it.

Minor — BridgeHandle._db and ._conn are typed unknown but cast everywhere:
The underscore convention signals "internal" but TypeScript doesn't enforce it — any consumer can cast and use the raw DB handle. Consider a module-boundary approach (only bridge-db.ts imports from @ladybugdb/core, everyone else uses BridgeHandle), which the code already does in practice. The typing is fine for now.

---

Performance Bottlenecks

Medium — N+1 query pattern in findContractNode (bridge-db.ts:315-363):

For each cross-link, findContractNode is called twice (from + to), and each call issues up to 3 sequential DB round-trips (UID → filePath+symbolName → filePath-only). In the worst case with M cross-links: up to 6M database queries. For the current scale (hundreds of contracts) this is likely fine, but at thousands of cross-links across large groups it will be the bottleneck.

A caching layer (Map<string, string> keyed on lookup params, built once before the link loop) would reduce this to O(contracts) queries total instead of O(links × 3). This is worth a TODO comment if not fixing now. Fix this →

Minor — sequential per-item inserts without batching:
Each contract and snapshot is inserted with a separate queryBridge call (N round-trips for N contracts). If LadybugDB supports UNWIND or multi-row inserts, batching in groups of e.g. 100 would substantially speed up large syncs. Worth a // TODO: batch when LadybugDB supports UNWIND comment.

Minor — queryBridge creates a new prepared statement per parameterized call without explicit close:
Prepared statements may hold resources depending on LadybugDB internals. The current pattern (prepare → execute → discard) is common but worth verifying against the LadybugDB docs that statements are GC'd correctly.

---

Contribution-Friendliness

Strengths:

• ✅ Clear module boundaries make it easy to extend without touching unrelated code
• ✅ Adding a new contract type matcher = add a case in normalizeContractId + a match in findMatchingKeys
• ✅ WriteBridgeReport is extensible — new failure categories = new counter field
• ✅ BRIDGE_SCHEMA_VERSION establishes the right pattern for future migrations
• ✅ Tests are real integration tests with temp dirs, not brittle mocks (good model for contributors)

Issue — makeContract test helper is copy-pasted between bridge-db.test.ts and bridge-db-edge.test.ts (test files, lines 120–131 and 13–24):
Any change to the default contract shape requires updating two files. Extracting to a shared test/unit/group/fixtures.ts would fix this and serve future test files in the split chain. Fix this →

Minor — findContractNode is untestable in isolation (see clean code note above). Contributors who want to improve the three-tier symbol lookup logic have no unit test surface for it.

Minor — no migration guide in BRIDGE_SCHEMA_VERSION (bridge-schema.ts:6):
The version gate returns null on mismatch (triggering re-sync), which is a valid V1 strategy. But the next contributor who bumps this constant won't know that — a brief comment explaining the contract ("bumping this forces a full re-sync; add a migration path in a future PR if the data volume warrants it") would prevent confusion.

---

Summary Table

Area	Status	Blockers
Production readiness	✅ Near-ready	fsp.rename → retryRename in bak recovery path
Clean code	✅ Good	Extract findContractNode out of writeBridge
Performance	⚠️ Adequate for current scale	N+1 queries in findContractNode — needs cache or TODO for growth
Contribution-friendliness	✅ Good	Deduplicate makeContract test fixture

The two medium issues (bak recovery rename + findContractNode extraction) are the only items I'd want addressed before merge. The rest can land as follow-up issues.

[github-actions]

CI Report

✅ All checks passed

Pipeline Status

Stage	Status	Details
✅ Typecheck	success	tsc --noEmit
✅ Tests	success	unit tests, 3 platforms
✅ E2E	success	gitnexus-web changes only

Test Results

Tests	Passed	Failed	Skipped	Duration
6039	5942	0	97	221s

✅ All 5942 tests passed

97 test(s) skipped — expand for details

• Swift MethodExtractor > isTypeDeclaration > recognizes class_declaration
• Swift MethodExtractor > isTypeDeclaration > recognizes protocol_declaration
• Swift MethodExtractor > isTypeDeclaration > rejects import_declaration
• Swift MethodExtractor > visibility > extracts public method
• Swift MethodExtractor > visibility > extracts private method
• Swift MethodExtractor > visibility > defaults to internal when no modifier
• Swift MethodExtractor > protocol methods > marks protocol method as abstract
• Swift MethodExtractor > static and class methods > detects static func as isStatic
• Swift MethodExtractor > static and class methods > detects class func as isStatic
• Swift MethodExtractor > parameters > extracts parameters with types and default values
• Swift MethodExtractor > return type > extracts return type from -> annotation
• Swift MethodExtractor > annotations > extracts @objc attribute
• Swift MethodExtractor > isFinal > detects final func
• Swift MethodExtractor > isFinal > is false when not final
• Swift MethodExtractor > isAsync > detects async func
• Swift MethodExtractor > isOverride > detects override method
• buildTypeEnv > constructor inference (Tier 1 fallback) > lookupClassByName regression coverage > Swift lookupClassByName regression coverage > Swift cross-file constructor inference uses lookupClassByName
• buildTypeEnv > constructor inference (Tier 1 fallback) > lookupClassByName regression coverage > Swift lookupClassByName regression coverage > Swift explicit init inference uses lookupClassByName
• buildTypeEnv > constructor inference (Tier 1 fallback) > lookupClassByName regression coverage > Swift lookupClassByName regression coverage > Swift cross-file constructor inference does not bind plain functions
• buildTypeEnv > known limitations (documented skip tests) > Ruby block parameter: users.each { |user| } — closure param inference, different feature
• Swift constructor-inferred type resolution > detects User and Repo classes, both with save methods
• Swift constructor-inferred type resolution > resolves user.save() to Models/User.swift via constructor-inferred type
• Swift constructor-inferred type resolution > resolves repo.save() to Models/Repo.swift via constructor-inferred type
• Swift constructor-inferred type resolution > emits exactly 2 save() CALLS edges (one per receiver type)
• Swift self resolution > detects User and Repo classes, each with a save function
• Swift self resolution > resolves self.save() inside User.process to User.save, not Repo.save
• Swift parent resolution > detects BaseModel and User classes plus Serializable protocol
• Swift parent resolution > emits EXTENDS edge: User → BaseModel
• Swift parent resolution > emits IMPLEMENTS edge: User → Serializable (protocol conformance)
• Swift cross-file User.init() inference > resolves user.save() via User.init(name:) inference
• Swift cross-file User.init() inference > resolves user.greet() via User.init(name:) inference
• Swift return type inference > detects User class and getUser function
• Swift return type inference > detects save function on User (Swift class methods are Function nodes)
• Swift return type inference > resolves user.save() to User#save via return type of getUser() -> User
• Swift return-type inference via function return type > resolves user.save() to User#save via return type of getUser()
• Swift return-type inference via function return type > user.save() does NOT resolve to Repo#save
• Swift return-type inference via function return type > resolves repo.save() to Repo#save via return type of getRepo()
• Swift implicit imports (cross-file visibility) > detects UserService class in Models.swift
• Swift implicit imports (cross-file visibility) > resolves UserService() constructor call across files (no explicit import)
• Swift implicit imports (cross-file visibility) > resolves service.fetchUser() member call across files
• Swift implicit imports (cross-file visibility) > creates IMPORTS edges between files in the same module
• Swift extension deduplication > detects Product class
• Swift extension deduplication > resolves Product() constructor despite extension creating duplicate class node
• Swift extension deduplication > resolves product.save() to Product.swift (primary definition)
• Swift constructor call fallback (no new keyword) > resolves OCRService() as constructor call across files
• Swift constructor call fallback (no new keyword) > resolves ocr.recognize() member call via constructor-inferred type
• Swift export visibility (internal vs private) > resolves PublicService() constructor across files
• Swift export visibility (internal vs private) > resolves internalHelper() across files (internal = module-scoped)
• Swift if let / guard let binding resolution > detects User and Repo classes
• Swift if let / guard let binding resolution > resolves user.save() inside if-let to User#save
• Swift if let / guard let binding resolution > resolves repo.save() inside guard-let to Repo#save
• Swift if let / guard let binding resolution > user.save() in if-let does NOT resolve to Repo#save
• Swift await / try expression unwrapping > resolves user.save() via await fetchUser() return type
• Swift await / try expression unwrapping > resolves repo.save() via try parseRepo() return type
• Swift await / try expression unwrapping > detects fetchUser and parseRepo as functions
• Swift for-in loop element type inference > detects User and Repo classes
• Swift for-in loop element type inference > creates implicit import edges between files
• Swift field-type resolution > detects classes and their properties
• Swift field-type resolution > emits HAS_PROPERTY edges from class to field
• Swift field-type resolution > resolves field-chain call user.address.save() → Address#save
• Swift field-type resolution > emits ACCESSES edges for field reads in chains
• Swift field-type resolution > populates field metadata (visibility, declaredType) on Property nodes
• Swift call-result binding > resolves call-result-bound method call user.save() → User#save
• Swift call-result binding > getUser() is present as a defined function
• Swift call-result binding > emits processUser -> getUser CALLS edge for let-assigned free function call
• Swift method enrichment > detects Animal protocol and Dog class
• Swift method enrichment > emits IMPLEMENTS edge Dog -> Animal
• Swift method enrichment > emits HAS_METHOD edges for Dog methods
• Swift method enrichment > marks protocol Animal.speak as isAbstract
• Swift method enrichment > marks Dog.speak as NOT isAbstract
• Swift method enrichment > marks breathe as isFinal
• Swift method enrichment > marks classify as isStatic
• Swift method enrichment > captures @objc annotation on breathe
• Swift method enrichment > populates parameterTypes for classify(_ name: String)
• Swift method enrichment > records parameterCount for classify
• Swift method enrichment > records returnType for speak
• Swift method enrichment > resolves dog.speak() CALLS edge
• Swift method enrichment > resolves Dog.classify("dog") CALLS edge
• Swift abstract dispatch > detects Repository protocol and SqlRepository class
• Swift abstract dispatch > emits IMPLEMENTS edge SqlRepository -> Repository
• Swift abstract dispatch > emits HAS_METHOD edges for Repository.find and Repository.save
• Swift abstract dispatch > emits HAS_METHOD edges for SqlRepository.find and SqlRepository.save
• Swift abstract dispatch > marks base Repository.find as isAbstract
• Swift abstract dispatch > marks base Repository.save as isAbstract
• Swift abstract dispatch > marks concrete SqlRepository.find as NOT isAbstract
• Swift abstract dispatch > resolves repo.find(id: 42) CALLS edge
• Swift abstract dispatch > resolves repo.save(entity: user) CALLS edge
• Swift abstract dispatch > populates parameterTypes for Repository.find
• Swift abstract dispatch > populates parameterTypes for Repository.save
• Swift abstract dispatch > records returnType for SqlRepository.find
• Swift abstract dispatch > emits METHOD_IMPLEMENTS edges from SqlRepository methods → Repository protocol methods
• Swift overloaded method disambiguation > detects 2 distinct find Method nodes on SqlRepository
• Swift overloaded method disambiguation > emits METHOD_IMPLEMENTS edges for both find overloads
• Swift overloaded method disambiguation > emits METHOD_IMPLEMENTS edge for save
• Swift overloaded method disambiguation > emits exactly 3 METHOD_IMPLEMENTS edges total
• Swift Child extends Parent — inherited method resolution (SM-9) > detects Parent and Child classes
• Swift Child extends Parent — inherited method resolution (SM-9) > resolves c.parentMethod() to Parent.parentMethod via first-wins MRO walk

Code Coverage

Tests

Metric	Coverage	Covered	Base	Delta	Status
Statements	72.35%	15809/21849	72.18%	📈 +0.2	🟢 ██████████████░░░░░░
Branches	61.4%	10252/16695	61.31%	📈 +0.1	🟢 ████████████░░░░░░░░
Functions	77.27%	1472/1905	76.99%	📈 +0.3	🟢 ███████████████░░░░░
Lines	74.52%	14325/19223	74.35%	📈 +0.2	🟢 ██████████████░░░░░░

---

_{📋 View full run · Generated by CI}

[magyargergo]

@ivkond could you please look at the findings above?

[ivkond]

@magyargergo addressed all findings in `0e9fd78`.

Medium:

• `openBridgeDbReadOnly` bak recovery now uses `retryRename` for Windows EBUSY consistency.
• `ensureBridgeSchema` substring check lifted into a named `LBUG_ALREADY_EXISTS_MSG` constant (LadybugDB DDL doesn't support `IF NOT EXISTS` and its JS driver doesn't expose error codes).
• `findContractNode` extracted out of `writeBridge` into module-level pure functions.
• N+1 eliminated: an in-memory `ContractLookupIndex` is built incrementally during contract insert, so cross-link resolution is now O(1) per link with zero DB round-trips (was up to 6).

Minor: `queryBridge` empty-array guard, `contractRichness` weights documented, `BRIDGE_SCHEMA_VERSION` migration contract comment, `makeContract` extracted to shared `test/unit/group/fixtures.ts`.

New tests: 9 pure-function unit tests for `findContractNode` covering all three tiers + repo/role scope isolation + priority ordering. No DB, no temp dirs, <10ms total.

Deferred (per reviewer's "fine for now"): `BridgeHandle` typing, batch inserts via `UNWIND`, prepared-statement lifecycle audit.

Typecheck clean, pre-commit clean, CI run in progress.

[magyargergo]

@claude are we backward compatible with these changes?

[github-actions]

Claude finished @magyargergo's task in 1m 24s —— View job

---

Backward Compatibility Analysis

• Gather context
• Read modified files (types.ts, matching.ts)
• Inspect existing callers (sync.ts, cli/group.ts)
• Provide compatibility verdict

---

Short answer: Yes, backward compatible — with one intentional behavioral nuance worth knowing.

---

What changed in the two modified files

types.ts — MatchType gains 'wildcard'

- export type MatchType = 'exact' | 'manifest' | 'bm25' | 'embedding';
+ export type MatchType = 'exact' | 'manifest' | 'wildcard' | 'bm25' | 'embedding';

Additive — adding a new member to a union type doesn't break existing code that reads or stores matchType as a string. The only risk would be exhaustive switch statements with a TypeScript never guard on the default branch. A search across the codebase finds no such exhaustive switch on MatchType — cli/group.ts:178 filters with l.matchType === 'exact' (a simple equality check), which is unaffected. 'wildcard' links simply won't appear in that count until follow-up PRs wire them in, which is correct.

The two new interfaces BridgeHandle and BridgeMeta are purely additive.

matching.ts — runExactMatch signature + behavior

Signature change:

- export function runExactMatch(contracts: StoredContract[]): MatchResult
+ export function runExactMatch(contracts: StoredContract[], providerIndex?: Map<...>): MatchResult

The new parameter is optional. The sole existing caller at sync.ts:161 calls runExactMatch(autoContracts) — this continues to compile and run identically. ✅

Behavioral change — gRPC wildcard consumers:

The new code excludes grpc::Service/* wildcard consumers from the exact-match loop and pushes them directly to unmatched. The question is whether this is a regression. Tracing through the old code: a wildcard consumer normalized to e.g. grpc::userservice/* would be looked up via findMatchingKeys against provider keys like grpc::userservice/Login — no exact match is possible, so the wildcard consumer ended up in unmatched anyway. The end result is identical; the new code just short-circuits it explicitly rather than doing a no-op pass.

Effective behavioral change: none. Wildcard consumers were already silently unmatched in the old code.

---

One intentional nuance to be aware of

sync.ts:161–162 currently discards unmatched entirely:

const { matched, unmatched } = runExactMatch(autoContracts);
const crossLinks: CrossLink[] = matched; // unmatched is dropped

Now that gRPC wildcard consumers are explicitly routed through unmatched, they will be silently excluded from the registry output until the follow-up PR (#792/#793) wires in runWildcardMatch. This is the stated intent of the split, but it means: if any user today has grpc::Service/* style consumers, they will produce zero cross-links for that contract type until the follow-up lands. This is not a regression (it didn't work before either), but it is a gap window in the split chain.

---

All new files — zero breakage risk

bridge-db.ts, bridge-schema.ts, normalization.ts, and fixtures.ts are brand-new files with no existing callers. They contribute zero backward compatibility risk.

---

Summary

Area	Verdict
runExactMatch signature	✅ Backward compatible (optional param)
runExactMatch behavior	✅ Functionally equivalent for all existing inputs
MatchType union expansion	✅ Additive, no exhaustive switches to break
ContractRegistry / .group.json schema	✅ No format change
New files / new exports	✅ Purely additive
gRPC wildcard consumers during split window	⚠️ Silently unmatched — same as before, but explicitly intentional until #792/#793 land

This PR is backward compatible. The only thing worth tracking is the split-window gap for wildcard consumers, which is expected behavior per the PR description.

[magyargergo]

Nice one!