feat(group): extractor expansion + manifest extractor (2/4 of #606 split)

[ivkond]

Part 2 of 4 in the split of #606 per @magyargergo's request. Follows #795 (already merged) but has no code-level dependency on it — both PRs could have been reviewed in parallel.

Closes #792.

What changed

Expands the 3 existing contract extractors with substantially more language/framework coverage, and adds a new `manifest-extractor` that resolves `group.yaml`-declared cross-links against the per-repo graph via exact-name lookups.

New (228 LOC prod + 308 LOC tests):

• `extractors/manifest-extractor.ts` — exact graph lookup for `group.yaml` cross-links. HTTP paths canonicalized; gRPC resolved by service/method name (NO `.proto`-filename fallback); topic and lib use exact-name match. Falls back to a synthetic `manifest::::` uid when unresolved, so cross-impact still has a stable anchor.

Modified (+794 LOC prod + 956 LOC tests):

• `extractors/grpc-extractor.ts` (+522) — `.proto` parser with string/comment-aware brace counting; canonical service/method IDs; Go / Java / Python / TS server + client detection
• `extractors/http-route-extractor.ts` (+174) — Go gin/echo/stdlib, NestJS decorators, Python FastAPI, Spring, Java consumers (restTemplate / WebClient / OkHttp)
• `extractors/topic-extractor.ts` (+98) — sarama `ProducerMessage{}` struct literal detection, kafka-go Writer/Reader, Python NATS, JetStream

Self-review fixes folded in

Carried forward from the original #606 self-review on `d15b8cb`:

• HIGH — `manifest-extractor.resolveSymbol` was too fuzzy. `CONTAINS` match + unconditional `.proto`-filename fallback meant manifest "/orders" matched "/suborders" and gRPC entries returned a random proto symbol from any repo with any `.proto` file. Replaced with exact equality + deterministic `ORDER BY` + synthetic-uid fallback. Regression tests included.
• MED — proto parser brace-depth now sanitizes strings and comments first. A valid proto with `option deprecated_reason = "use NewService { instead"` used to have its service body closed early by the `"{"` inside the literal. Regression tests for string and comment variants.
• MED — sarama Kafka regex changed from `sarama.NewSyncProducer[\s\S]{0,300}?Topic:` (anchored on constructor, caught only first topic in a loop) to `sarama.ProducerMessage{...Topic:}` (matches every struct literal). Regression test with a for-loop producing multiple messages.
• MED — `resolveSymbol` no longer has a silent `catch { /* fall through */ }`; logs the error via `console.warn` with link type, contract name, repo key, and error message before falling through to the synthetic-uid path.

How to verify

```bash
cd gitnexus
npx tsc --noEmit
npx vitest run test/unit/group/grpc-extractor.test.ts --pool=forks
npx vitest run test/unit/group/http-route-extractor.test.ts --pool=forks
npx vitest run test/unit/group/topic-extractor.test.ts --pool=forks
npx vitest run test/unit/group/manifest-extractor.test.ts --pool=forks
```

Local: typecheck clean; 99/99 extractor tests pass (grpc 43, http 18, topic 30, manifest 8).

Risk / rollback

Low. Extractors have no user-facing surface in this PR — they produce `ExtractedContract[]` consumed by `sync.ts` in the next split (#793). No existing behavior changes for users who don't run `group sync`. Rollback is a clean `git revert`; the three modified extractors revert to their pre-PR versions which are subsets of the new functionality.

Scope discipline (per `GUARDRAILS.md`)

• Only the 8 files above are touched; no drive-by refactors
• No CI/release/security config changes
• No secrets or machine-specific paths
• Content lifted from [group] Cross-repo impact analysis via repository groups #606 which already passed CI 11/11 green

Dependencies

• Base: `main` (upstream already includes feat(group): bridge.lbug storage + contract matching expansion (1/4 of #606 split) #795 as `1ff324c`)
• Blocks: sync pipeline ([group] Sync pipeline (split 4/5 of #606) #793) and cross-impact feature ([group] Cross-repo impact analysis, CLI and MCP tool (split 5/5 of #606) #794)
• Tracker issue: [group] Service boundary detection and language contract extractors (split 3/5 of #606) #792
• Parent PR: [group] Cross-repo impact analysis via repository groups #606

🤖 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.

[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
6194	6097	0	97	226s

✅ All 6097 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.56%	16509/22750	72.44%	📈 +0.1	🟢 ██████████████░░░░░░
Branches	61.49%	10576/17197	61.4%	📈 +0.1	🟢 ████████████░░░░░░░░
Functions	77.47%	1531/1976	77.16%	📈 +0.3	🟢 ███████████████░░░░░
Lines	74.99%	14988/19986	74.59%	📈 +0.4	🟢 ██████████████░░░░░░

---

_{📋 View full run · Generated by CI}

[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 encountered an error —— View job

---

PR Review

• Gather context
• Read production source files
• Analyze: production readiness, clean code, performance, extensibility
• Post findings

---

Verdict: Approve with notes

CI is green, 99/99 extractor tests pass, self-review fixes are solid, and rollback risk is low. The code is mergeable. That said, there are a few things worth flagging now before the codebase grows further.

---

Production Readiness ✅

The PR is production-ready given its current scope. Extractors produce ExtractedContract[] that isn't yet consumed by a user-facing surface, the synthetic-uid fallback ensures cross-impact stability for unresolved manifest entries, and the console.warn logging provides enough signal for debugging without breaking on errors.

The self-review fixes carried in from #606 are exactly the right things to have caught: the CONTAINS-fuzzy match false positive was a latent correctness bug and the sarama regex fix changes semantics meaningfully in loop-heavy producer code.

---

Clean Code Issues

1. readSafe is copy-pasted three times — grpc-extractor.ts:7-17, http-route-extractor.ts:48-58, topic-extractor.ts:12-22. The path-traversal guard (the relToBase.startsWith('..') check) is security-sensitive logic. If it ever needs a fix, the next contributor has to know to update three files. This should live in a shared fs-utils.ts.

Fix this →

2. dedupe is duplicated with inconsistent behavior — grpc-extractor.ts:715-729 keeps the highest-confidence entry (useful!), but http-route-extractor.ts:248-258 and topic-extractor.ts:364-374 both just take the first seen. Inconsistent behavior for the same operation makes it hard for contributors to know what to copy when adding a new extractor.

3. mapNames is defined twice in http-route-extractor.ts — once in pickJavaHandlerName (line 66) and again in inferMethodFromFileScan (line 211). These are identical Record<string, string> objects; one module-level constant would suffice.

4. ManifestExtractor is a stateless class — it holds no instance fields, so class ManifestExtractor is just a namespace. This is a common antipattern in functional TypeScript: plain exported functions would be clearer and easier to test in isolation, since callers don't need to new anything.

5. Magic confidence numbers — values like 0.85, 0.8, 0.75, 0.65, 0.55 are scattered across grpc-extractor.ts without named constants. A const CONFIDENCE = { PROTO_PARSE: 0.85, GO_REGISTER_WITH_PROTO: 0.8, ... } block would make the scoring rationale legible and consistent for future language additions.

---

Performance Bottlenecks

1. Double glob + double parse for .proto files — GrpcExtractor.extract() calls buildProtoContext(repoPath) (which does glob('**/*.proto', ...) and reads every file) and then immediately does its own glob('**/*.proto', ...) again to call parseProtoFile on each one (grpc-extractor.ts:341-357). That's two full filesystem traversals and two full parses of every proto file in the repo. The fix is straightforward: buildProtoContext should return provider contracts alongside the service map, or extract() should reuse the contents map that buildProtoContext already built internally.

Fix this →

2. Regex objects recreated per file in TopicExtractor.scanFile — topic-extractor.ts:333 does new RegExp(pattern.regex.source, pattern.regex.flags) for all 13 patterns on every single file. This is needed to reset lastIndex, but allocating 13 new RegExp objects per file is wasteful. The standard fix is to reset re.lastIndex = 0 before each file instead of constructing a new object.

3. Proto file reads are serial — buildProtoContext reads files in a for loop with fs.readFileSync. For repos with many proto files, switching to Promise.all over async reads would help. Same applies to source-file scanning in all three extractors.

4. longestSharedSegmentRun is O(n²) in segment count — called on every proto service candidate lookup (resolveProtoConflict). For repos with deep directory structures and many services of the same name this could be slow. In practice it's fine for most repos, but worth documenting the complexity assumption (e.g. // O(n²) in path depth — acceptable for typical repo structures).

---

Extensibility

The overall structure unlocks contributions well. The PatternDef[] approach in topic-extractor.ts is genuinely excellent — adding a new broker or language is literally just appending to a constant array. The grpc language-specific scan* methods are cleanly separated and easy to extend.

Two things that could trip up future contributors:

1. The manifest resolver's topic/lib queries are label-unaware — manifest-extractor.ts:144-149 and 183-188 both run MATCH (n) WHERE n.name = $contract with no label filter. Any node in the graph named "payments" would match a topic called "payments", including a Java class, a file, or a variable. Adding WHERE n:Topic (or whatever label the indexer uses) would make this robust. Same concern applies to the gRPC method lookup at line 160: n.name = 'Create' would match any graph node named Create, not necessarily a gRPC method.

Fix this →

2. buildContractId in manifest-extractor.ts has no default case — if ContractType gains a new member in the future, TypeScript will not produce an error here (since the switch exhausts all current variants but has no explicit exhaustiveness guard). Adding a default: link.type satisfies never assertion would make future extension safe.

---

Minor Nits

• _role parameter in inferMethodFromFileScan (http-route-extractor.ts:207) is unused and could be removed.
• scanPythonConsumers in grpc-extractor.ts:617 filters ['Mock', 'Test', 'Fake', 'Stub'].includes(name) — TestStub, FakeStub, etc. would slip through. Low risk but worth noting for future expansion.
• The NestJS regex @(Get|Post|...)\s*\(\s*['"\]?([^'"\`)])['"`]?\s)(line 321) will match unquoted decorator arguments like@get(myPathVar), producing myPathVar` as a literal path. Probably fine for now but fragile.

---

Summary: Merge-ready. The double proto glob is the most actionable fix before the next split PR lands, since sync.ts (#793) will call these extractors on real repos and the redundant I/O will show up in profiling. The label-unaware Cypher queries in manifest-extractor.ts are the most correctness-relevant issue. The readSafe deduplication is a hygiene item that will get worse with each new extractor added in the remaining splits.

[magyargergo]

@ivkond I don't think it's ready to be merged! I think, we should work on this a little more and try to find a better approach. Right now, we are doing regex based lookups, would it be possible to utilise tree-sitter nodes?

[magyargergo]

Can we make them language agnostic? The rule of thumb is we dont want in the top level processors/extractors to have langauge dependencies.

[magyargergo]

Plerase make sure we use tree-sitters appropriately over regexp 🙏

[magyargergo]

Could we add https://github.com/coder3101/tree-sitter-proto instead of manual parsing?

[ivkond]

@magyargergo, checked tree-sitter-proto — the grammar peers on tree-sitter ^0.21 while we run 0.25, so the native binary won't load (ABI mismatch). The .proto parser we have is already sanitizing comments + strings and handles nested braces correctly (43 tests cover it including the braces-in-strings and braces-in-comments regressions).

Happy to revisit once the grammar is updated to the 0.25 ABI, or if you'd prefer we fork + rebuild it ourselves — let us know.

In the meantime, all three extractor source-scan paths (topic, http, grpc) have been migrated to the language-agnostic plugin architecture per your earlier feedback — the .proto in-tree parser is the only remaining non-tree-sitter code path and is documented as an explicit exception.

[magyargergo]

I'm just concious about performance and that's why I'm pushing for it. Could we maybe spend today with looking for an alternatice fork that may have sorted this? 🙏

[ivkond]

@magyargergo, summary of changes on this branch after the review feedback:

New: manifest-extractor for group.yaml cross-link resolution via exact-match Cypher queries.

Refactored: all three extractors (topic, http, grpc) migrated from regex to tree-sitter with a plugin architecture — top-level orchestrators import zero grammars, each *-patterns/<lang>.ts plugin owns its grammar + queries. Adding a new language = one file, zero orchestrator edits.

Added: tree-sitter-proto (vendored, ABI 14) for .proto parsing — replaces the manual comment/string stripper + brace-depth counter. Graceful fallback if native build fails.

No test changes (99/99 pass as-is), no MCP/pipeline/CI changes.

[Copilot]

Pull request overview

This PR expands the group contract extraction layer by moving topic/http/grpc source scanning to tree-sitter-driven, language-plugin registries, adds a new manifest-based extractor for group.yaml cross-links, and vendors an optional tree-sitter-proto grammar to improve .proto parsing when available.

Changes:

• Introduce shared tree-sitter scanning utilities and plugin registries for topic/http/gRPC extractors.
• Add ManifestExtractor to convert manifest links into provider/consumer contracts + cross-links with deterministic synthetic uids when unresolved.
• Add optional tree-sitter-proto (vendored) and extend gRPC extraction with improved .proto parsing/canonicalization and broader client/server detection.

Reviewed changes

Copilot reviewed 30 out of 42 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
gitnexus/vendor/tree-sitter-proto/src/tree_sitter/parser.h	Vendored tree-sitter C header for proto grammar build.
gitnexus/vendor/tree-sitter-proto/src/tree_sitter/array.h	Vendored tree-sitter array utilities.
gitnexus/vendor/tree-sitter-proto/src/tree_sitter/alloc.h	Vendored tree-sitter allocation utilities.
gitnexus/vendor/tree-sitter-proto/package.json	Vendored tree-sitter-proto package metadata for local optional dependency.
gitnexus/vendor/tree-sitter-proto/bindings/node/index.js	Node binding entrypoint for the vendored proto grammar.
gitnexus/vendor/tree-sitter-proto/bindings/node/index.d.ts	Type definitions for the vendored proto grammar module.
gitnexus/vendor/tree-sitter-proto/bindings/node/binding.cc	Native addon binding that exposes the proto grammar to tree-sitter.
gitnexus/vendor/tree-sitter-proto/binding.gyp	node-gyp build config for compiling the proto grammar addon.
gitnexus/vendor/tree-sitter-proto/.gitignore	Ignores build artifacts for vendored grammar.
gitnexus/test/unit/group/topic-extractor.test.ts	Adds/updates topic extraction tests for KafkaJS run, JetStream, Python NATS, Sarama producer literals, kafka-go, and Go test-file ignore.
gitnexus/test/unit/group/manifest-extractor.test.ts	New unit tests for manifest extraction, exact-match resolution, and synthetic uid fallback behavior.
gitnexus/test/unit/group/http-route-extractor.test.ts	Expands HTTP route extraction tests (Go frameworks/stdlib, NestJS, Python requests, Java consumers, Go consumers) and removes old interface-anchoring cases.
gitnexus/test/unit/group/grpc-extractor.test.ts	Expands gRPC extraction tests (proto brace sanitization, TS/Node patterns, proto map conflict resolution) and adjusts confidence expectations.
gitnexus/src/core/group/extractors/tree-sitter-scanner.ts	New shared utilities to compile/run tree-sitter queries and unquote literals for multiple languages.
gitnexus/src/core/group/extractors/topic-patterns/types.ts	New shared types for topic plugin metadata.
gitnexus/src/core/group/extractors/topic-patterns/python.ts	Python topic patterns (Kafka, RabbitMQ, NATS) via tree-sitter.
gitnexus/src/core/group/extractors/topic-patterns/node.ts	JS/TS/TSX topic patterns (KafkaJS, amqplib, NATS/JetStream) via tree-sitter.
gitnexus/src/core/group/extractors/topic-patterns/java.ts	Java topic patterns (Spring Kafka/Rabbit) via tree-sitter.
gitnexus/src/core/group/extractors/topic-patterns/index.ts	Plugin registry and glob for topic extraction.
gitnexus/src/core/group/extractors/topic-patterns/go.ts	Go topic patterns (Sarama, kafka-go, NATS/JetStream) via tree-sitter.
gitnexus/src/core/group/extractors/topic-extractor.ts	Refactors topic extractor to tree-sitter plugin orchestration and literal extraction.
gitnexus/src/core/group/extractors/manifest-extractor.ts	New manifest extractor that resolves manifest links against per-repo graphs with exact matches and synthetic uid fallback.
gitnexus/src/core/group/extractors/http-route-extractor.ts	Refactors HTTP extractor to use graph-assisted extraction with tree-sitter fallback plugins for providers/consumers.
gitnexus/src/core/group/extractors/http-patterns/types.ts	New shared types for HTTP plugin detections and plugin interface.
gitnexus/src/core/group/extractors/http-patterns/python.ts	Python HTTP plugin (FastAPI providers, requests consumers).
gitnexus/src/core/group/extractors/http-patterns/php.ts	PHP HTTP plugin (Laravel route declarations).
gitnexus/src/core/group/extractors/http-patterns/node.ts	Node/TS HTTP plugin (NestJS/Express providers, fetch/axios consumers).
gitnexus/src/core/group/extractors/http-patterns/java.ts	Java HTTP plugin (Spring providers, RestTemplate/WebClient/OkHttp consumers).
gitnexus/src/core/group/extractors/http-patterns/index.ts	HTTP plugin registry and glob for source-scan fallback.
gitnexus/src/core/group/extractors/http-patterns/go.ts	Go HTTP plugin (gin/echo/chi + stdlib providers, stdlib/resty consumers).
gitnexus/src/core/group/extractors/grpc-patterns/types.ts	New shared types for gRPC plugin detections and plugin interface.
gitnexus/src/core/group/extractors/grpc-patterns/python.ts	Python gRPC plugin (servicer registration + stub construction).
gitnexus/src/core/group/extractors/grpc-patterns/proto.ts	Optional tree-sitter-proto plugin for extracting package/service/rpc pairs from .proto.
gitnexus/src/core/group/extractors/grpc-patterns/node.ts	Node/TS gRPC plugin (Nest decorators, getService, generated clients, dynamic loader pattern).
gitnexus/src/core/group/extractors/grpc-patterns/java.ts	Java gRPC plugin (ImplBase providers + stub factory consumers).
gitnexus/src/core/group/extractors/grpc-patterns/index.ts	gRPC plugin registry and glob (optionally includes .proto).
gitnexus/src/core/group/extractors/grpc-patterns/go.ts	Go gRPC plugin (Register/Unimplemented server + NewClient patterns).
gitnexus/src/core/group/extractors/grpc-extractor.ts	Refactors gRPC extractor to plugin orchestration + improved proto parsing/canonicalization and conflict resolution.
gitnexus/package.json	Adds optional dependency on the vendored tree-sitter-proto.
gitnexus/package-lock.json	Locks the local-link optional dependency for tree-sitter-proto.

Files not reviewed (1)

• gitnexus/package-lock.json: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

normalizeHttpPath turns the root path '/' into an empty string because it strips all trailing slashes. This can produce malformed contract IDs like http::GET:: (missing path) for root handlers/fetches. Consider special-casing empty result to '/' (or avoid stripping when the path is exactly /).

[Copilot]

extract() calls scanFiles(repoPath) twice (once for providers fallback and once for consumers fallback). This duplicates the glob work and file list allocation. Consider calling scanFiles once, storing the result, and reusing it for both provider and consumer fallback paths.

[Copilot]

scanFiles doesn't exclude **/vendor/** even though other extractors (e.g. topic/grpc) ignore vendored code. Scanning vendored sources can add noise and cost. Consider adding **/vendor/** to the ignore list for consistency and to avoid false positives.

Suggested change

	ignore: ['**/node_modules/**', '**/.git/**', '**/dist/**', '**/build/**'],
	ignore: ['**/node_modules/**', '**/.git/**', '**/dist/**', '**/build/**', '**/vendor/**'],

[Copilot]

Using tree.rootNode.text.includes('loadPackageDefinition') forces materializing the entire file contents from the parse tree, which can be expensive for large files. Prefer checking the original source text before parsing, or add a dedicated query/capture for loadPackageDefinition so the scan stays structural without allocating the full text.

[Copilot]

This comment is now inaccurate: when resolveSymbol returns null, the extractor does not create an empty symbolUid — it falls back to a deterministic manifest::... synthetic uid (and a non-empty symbolRef.name). Please update the comment to match the current behavior so future changes/tests aren't misled.

Suggested change

	// If resolveSymbol returns null, the extractor creates a contract with
	// an empty symbolUid/ref — cross-impact still works via name-based
	// matching through the `hint` path in runGroupImpact.
	// If resolveSymbol returns null, the extractor falls back to a
	// deterministic synthetic `manifest::...` symbol uid and preserves a
	// non-empty symbolRef.name derived from the manifest contract.

[Copilot]

The header comment says .proto parsing is not tree-sitter-based because no tree-sitter-proto grammar is installed, but this PR adds tree-sitter-proto as an optional dependency and registers a .proto plugin when available. Please update this docstring to reflect the new behavior (tree-sitter when available, manual fallback otherwise).

Suggested change

	* 1. **`.proto` parsing** — done in-process by a small string-sanitizing
	* parser (see `stripProtoCommentsAndStrings` + `extractServiceBlocks`
	* below). NOT tree-sitter-based because no `tree-sitter-proto`
	* grammar is installed in the repo. The parser preserves offsets so
	* downstream regex scans run against a sanitized copy without
	* affecting the line numbers of the original. Kept as a pragmatic
	* exception to the "no regex in extractors" rule until / unless
	* maintainers want to add a proto grammar.
	*
	* 2. **Source-scan providers / consumers** — delegated to per-language
	* plugins in `./grpc-patterns/`. The orchestrator imports NO
	* tree-sitter grammars or query strings — each plugin owns its own.
	*/
	// ─── .proto parsing (not tree-sitter) ────────────────────────────────
	* 1. **`.proto` parsing** — uses tree-sitter when the optional
	* `tree-sitter-proto` plugin is available. Otherwise, it falls back to
	* an in-process string-sanitizing parser (see
	* `stripProtoCommentsAndStrings` + `extractServiceBlocks` below).
	* The fallback parser preserves offsets so downstream regex scans run
	* against a sanitized copy without affecting the line numbers of the
	* original.
	*
	* 2. **Source-scan providers / consumers** — delegated to per-language
	* plugins in `./grpc-patterns/`. The orchestrator imports NO
	* tree-sitter grammars or query strings — each plugin owns its own.
	*/
	// ─── .proto parsing fallback ─────────────────────────────────────────

[Copilot]

buildProtoContext(repoPath) already globs and parses all .proto files to build the proto map; on the !hasProtoPlugin path, the extractor globs/reads/parses the .proto files again to emit provider contracts. This doubles IO/CPU on platforms where the proto plugin isn't available. Consider reusing the proto file contents/service blocks from buildProtoContext (or have it also return the provider contracts) to avoid the second pass.

[magyargergo]

@claude ultra-think while reviewing this PR. This needs to be review from its architectural fit and it doesnt violate cross boundaries. We want per-language for this multi-repo support via http/grpc etc calls. Read previous comments and include them in your evaluation. We are also looking for potential bugs and performance bottlenecks. Finally, we want to follow clean code principles and highlight any violations.

[github-actions]

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

---

PR Review: feat(group): extractor expansion + manifest extractor

• Gather context and read prior review comments
• Read core source files (extractors, patterns, manifest)
• Analyze architectural fit and boundary violations
• Analyze per-language plugin design
• Analyze bugs and correctness
• Analyze performance bottlenecks
• Analyze clean code principles
• Post full review

---

Overall Verdict

The architectural direction is correct and the plugin boundary enforcement is solid. However there are 3 bugs that will produce silent wrong results in production, 2 performance issues that Copilot already flagged but need emphasis, and 1 architectural seam that will cause confusion as the codebase grows. Details below.

---

Architectural Fit ✅ with one gap

What works well: The orchestrator/plugin boundary is properly enforced. All three orchestrators (topic-extractor.ts, http-route-extractor.ts, grpc-extractor.ts) import zero tree-sitter grammars. Language-specific knowledge is isolated in *-patterns/<lang>.ts. tree-sitter-scanner.ts is a clean shared abstraction. The PatternDef[] / CompiledPatterns<TMeta> generics decouple the scanner from the domain types — adding a language is a one-file edit with no orchestrator changes required. This fully resolves @magyargergo's earlier concern.

One structural gap — ManifestExtractor is not a ContractExtractor:
ManifestExtractor does not implement the ContractExtractor interface (gitnexus/src/core/group/contract-extractor.ts). It takes GroupManifestLink[] instead of (dbExecutor, repoPath, repo), and returns { contracts, crossLinks } instead of ExtractedContract[]. This is a different pipeline — deliberate, given that manifests are group-level not repo-level — but it means whoever wires sync.ts (#793) needs to know to call it differently. The type distinction should be explicit: either define a GroupExtractor interface or add a JSDoc comment on the class declaring why it doesn't conform. Without that, the next contributor adding an extractor will look at this as a reference and produce an incompatible shape.

GrpcLanguagePlugin.scan() only receives tree, not source:
grpc-patterns/node.ts:259 works around this with tree.rootNode.text.includes('loadPackageDefinition'), which reconstructs the full file text from the AST. This is a design limitation: the plugin interface forces plugins to use tree.rootNode.text any time they need raw text checks. HttpLanguagePlugin.scan(tree) and TopicMeta-based plugins have the same constraint. Consider changing all plugin scan(tree) signatures to scan(tree, source: string) — all three orchestrators already have the content string at the call site. Fix this →

---

Bugs 🐛

Bug 1 — normalizeHttpPath('/') returns '' (malformed contract IDs)
http-route-extractor.ts:62:

let s = p.trim().split('?')[0].toLowerCase().replace(/\/+$/, '');

For input '/': the replace(/\/+$/, '') strips the trailing slash, producing an empty string. Provider contracts for root handlers become http::GET:: (missing path segment). normalizeConsumerPath has || '/' protection at the end but normalizeHttpPath itself (used for all provider paths) does not. Any framework that registers GET / will emit a broken contract ID. Fix this →

Bug 2 — Tautological !handlerName in extractProvidersGraph
http-route-extractor.ts:247:

let handlerName: string | null = null;
if (!method || !handlerName) {   // !handlerName is ALWAYS true here

handlerName is declared and initialized to null one line above with no intervening assignment. The condition !handlerName is tautologically true, so the block runs on every row regardless of whether method was already determined by methodFromRouteReason. If method is already set, the plugin scan still runs and may overwrite it with a possibly weaker match. This is likely a leftover from a refactor where handlerName was previously set by some other code path. The condition should be if (!method) or if (!method || true) (if the intent is to always resolve the handler name). Fix this →

Bug 3 — Manifest HTTP contracts produce http::*::path, never matching extractor contracts
manifest-extractor.ts:215:

case 'http': {
  if (/^[A-Za-z]+::/.test(contract)) return `http::${contract}`;
  return `http::*::${contract}`;   // method is unknown → wildcard
}

Provider contracts from HttpRouteExtractor are keyed as http::GET::/api/orders. Manifest contracts become http::*::/api/orders. If sync.ts (#793) matches by exact contractId equality, these will never collide — manifest cross-links will always fall through to the synthetic uid path. If the * is intended as a wildcard, matching logic in sync.ts must explicitly handle it. Either the format needs to be documented as "wildcard" and sync.ts must handle it, or the buildContractId method should leave the HTTP method out and use a format that sync.ts knows how to match. The current state is unresolved and will silently produce unresolved manifest contracts for all HTTP links. Fix this →

Bug 4 — Cypher queries in resolveSymbol have no label filter (false positive matches)
manifest-extractor.ts:144-149, 160-163, 183-188:

MATCH (n) WHERE n.name = $contract   -- matches ANY node type

A topic named "orders" will match a Java class, a file node, or a variable named "orders". The gRPC method lookup WHERE n.name = $methodName with methodName = 'Create' will match any graph node named Create. For lib type, n.name = 'react' would match non-package nodes. Add label filters: (n:Topic), (n:Function|Method), (n:Package), etc. to scope each query to its expected node type. Fix this →

---

Performance Bottlenecks ⚡

Double glob + double parse of .proto files (confirmed)
grpc-extractor.ts:369-393: buildProtoContext(repoPath) globs all .proto files and calls extractServiceBlocks on each one to build the service map. When !hasProtoPlugin, extract() then globs .proto files again (line 377) and calls parseProtoFile on each, which calls extractServiceBlocks a second time on the same files. This is 2× filesystem traversal + 2× full parse of every proto file on environments without the tree-sitter-proto grammar (i.e., most CI environments until the grammar is stable). Fix: buildProtoContext should accept an optional providerContracts: ExtractedContract[] accumulator or return provider contracts alongside the service map. Fix this →

scanFiles() called twice in http-route-extractor.ts
http-route-extractor.ts:200,207: In the worst case (both graph paths return empty), this.scanFiles(repoPath) is awaited twice — two full glob traversals on the same directory. The fix is a single const files = await this.scanFiles(repoPath) hoisted before the provider/consumer branches, used for both. The cachedDetections optimization already prevents re-parsing files — only the glob is duplicated. Fix this →

Missing **/vendor/** in HTTP extractor glob
http-route-extractor.ts:215: The scanFiles ignore list omits **/vendor/** while both grpc-extractor.ts:399 and topic-extractor.ts:74 include it. HTTP scans will parse vendored Go and PHP sources, producing false positive route contracts from dependencies. Fix this →

---

Clean Code Violations

1. readSafe is copy-pasted in all three orchestrators
grpc-extractor.ts:36-46, http-route-extractor.ts:99-109, topic-extractor.ts:31-41 are byte-for-byte identical. The path-traversal guard (relToBase.startsWith('..')) is security-sensitive logic. A single extractors/fs-utils.ts should own it. Fix this →

2. dedupe strategies are inconsistent across extractors
grpc-extractor.ts:477-492 keeps the highest-confidence entry (semantically correct). http-route-extractor.ts:426-436 and topic-extractor.ts:105-114 both keep the first-seen entry without considering confidence. When two plugins detect the same route at different confidence levels, the result depends on plugin registration order — arbitrary and fragile. One canonical dedupe function parameterized by key-extractor and merge strategy would make the behavior uniform and visible.

3. _test.go skip is language-specific in a language-agnostic orchestrator
topic-extractor.ts:84: if (rel.endsWith('_test.go')) continue; is Go-specific knowledge in the orchestrator. Java test files (*Test.java), Python test files (test_*.py), etc. are not filtered. This should be pushed into the Go plugin (by widening the plugin's glob to exclude *_test.go) or applied uniformly via an ignore glob entry. Currently only Go test files are excluded from topic extraction.

4. ManifestExtractor is a stateless class
manifest-extractor.ts:49: The class holds no instance fields. new ManifestExtractor().extractFromManifest(links, executors) is just a namespace. In functional TypeScript, plain exported functions are clearer and don't require callers to new anything. manifestSymbolUid is already correctly exported as a plain function — extractFromManifest and resolveSymbol (currently private) should follow suit.

5. Stale comment at manifest-extractor.ts:126
The comment says "creates a contract with an empty symbolUid/ref" but the code creates a synthetic uid via manifestSymbolUid(...). Already flagged by Copilot with a suggested fix. Fix this →

6. buildContractId has no exhaustiveness guard
manifest-extractor.ts:212: The switch(type) covers all five current ContractType variants but has no default: type satisfies never. When ContractType gains a new member, TypeScript will silently fall through to returning undefined. Add a default: const _: never = type; return custom::${_}; or equivalent exhaustiveness assertion.

---

Minor Notes

• grpc-patterns/node.ts:28: SERVICE_CLIENT_RE = /^(\w+Service)Client$/ — a class named NewService would not match (intentional), but BackgroundServiceWorkerClient would match as service BackgroundServiceWorker. Acceptable for now but worth a comment explaining why the suffix is Client not ServiceClient.
• grpc-patterns/proto.ts:44: Uses a bare _require('tree-sitter') import inside the module-init block, bypassing the ESM import chain. This works because it's createRequire-based, but it means the smoke-test parser is a different instance than the one the orchestrator uses — a subtle state isolation that could cause issues if tree-sitter is stateful per-instance in future versions.
• The vendored tree-sitter-proto in vendor/ is an appropriate intermediate solution while upstream ABI compatibility is sorted. The graceful fallback design is correct.

---

Priority Summary

#	Severity	File	Issue
1	🔴 Bug	manifest-extractor.ts:215	HTTP manifest contracts http::*::path never match extractor contracts
2	🔴 Bug	manifest-extractor.ts:144,160,183	Cypher queries lack label filters — any node can match
3	🔴 Bug	http-route-extractor.ts:62	normalizeHttpPath('/') returns '' → malformed contract IDs
4	🟡 Perf	grpc-extractor.ts:369-393	Double glob + double parse of .proto files
5	🟡 Perf	http-route-extractor.ts:200,207	scanFiles() called twice
6	🟡 Perf	http-route-extractor.ts:215	Missing **/vendor/** in glob ignore
7	🟡 Design	All orchestrators	readSafe copied 3× — security-sensitive code
8	🟡 Design	http-route-extractor.ts:247	Tautological !handlerName condition
9	🟡 Design	Plugin interfaces	scan(tree) forces tree.rootNode.text for source text checks
10	🔵 Style	topic-extractor.ts:84	Go-specific _test.go skip in language-agnostic orchestrator

Items 1–3 should be fixed before merge. Items 4–6 are the most actionable performance wins before sync.ts (#793) lands. Items 7–9 are hygiene that will compound with each new extractor in the remaining splits.

[magyargergo]

@claude are we ready for production?

[github-actions]

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

---

Production Readiness Assessment

• Read prior review comments and bug reports
• Read current state of key source files
• Check if previously identified bugs are fixed
• Assess performance bottlenecks
• Final verdict

---

Verdict: Almost — one correctness bug blocks a clean merge

The branch has made substantial progress since the last two reviews. The tree-sitter plugin architecture is solid, nearly all previously reported bugs are fixed, and all performance issues are resolved. One correctness bug remains that will silently cause all HTTP manifest links to fall through to the synthetic uid path.

---

What Was Fixed ✅

Issue	Status
normalizeHttpPath('/') returning '' (malformed contract IDs)	✅ Fixed — http-route-extractor.ts:69 now returns '/'
Tautological !handlerName condition	✅ Fixed — entire block was cleanly refactored
Double glob + double parse of .proto files	✅ Fixed — buildProtoContext result reused; no second glob when !hasProtoPlugin
scanFiles() called twice for provider/consumer paths	✅ Fixed — lazy getScannedFiles() cache (line 186–191)
Missing **/vendor/** in HTTP extractor glob	✅ Fixed — line 213
readSafe copy-pasted 3× (security-sensitive)	✅ Fixed — fs-utils.ts created; all three orchestrators import from it
Cypher queries with no label filters	✅ Fixed — topic uses Function|Method|Class|Interface, grpc method → Function|Method, service → Class|Interface, lib → Package|Module
Go-specific _test.go skip in language-agnostic orchestrator	✅ Fixed — moved to glob ignore in topic-extractor.ts:73, with explanatory comment
Stale grpc-extractor.ts header comment	✅ Fixed — now accurately documents tree-sitter + fallback

---

Remaining Issue 🔴

manifest-extractor.ts:226 — HTTP contract ID format mismatch (silent, will affect all HTTP manifest links)

// manifest-extractor.ts:225-226
if (/^[A-Za-z]+::/.test(contract)) return `http::${contract}`;
return `http::*::${contract}`;   // ← wildcard method

HttpRouteExtractor produces contract IDs like http::GET::/api/orders. ManifestExtractor.buildContractId produces http::*::/api/orders. When sync.ts (#793) joins these by contractId equality, they will never match. Every HTTP manifest link that doesn't include an explicit method prefix (e.g. GET::/orders) will silently fall through to the synthetic uid path — not an error, but cross-repo HTTP impact will be incomplete.

The fix is a design decision for sync.ts: either (a) store the wildcard format and have sync.ts match http::*::path against any http::<method>::path, or (b) change buildContractId to omit the method entirely (e.g. http::/api/orders) and align HttpRouteExtractor to a method-agnostic secondary key. The current state leaves this implicit and unresolved.

Fix this →

---

Minor Outstanding Items 🟡

1. Stale comment at manifest-extractor.ts:124–126
Still says "creates a contract with an empty symbolUid/ref" but the code now uses manifestSymbolUid(). Copilot suggested a fix and it wasn't applied.

2. buildContractId has no exhaustiveness guard
manifest-extractor.ts:222–237: the switch(type) covers all five current ContractType members but has no default: type satisfies never. When ContractType gains a new member, TypeScript will silently return undefined. One line fix.

3. grpc-patterns/node.ts — tree.rootNode.text for raw text checks
Line 259 uses tree.rootNode.text.includes('loadPackageDefinition') to work around the plugin interface not receiving source. Copilot flagged this and it's still present. Not a bug, but materializes the full file text from the AST on every file scan. Adding source: string to the plugin scan() signature would clean this up — low priority but worth tracking.

---

Summary

The PR is well-structured and the architecture is sound. The tree-sitter plugin boundary is properly enforced — orchestrators import zero grammars, each language plugin owns its own. Performance and security issues from prior reviews are all addressed.

The one blocker before merge: resolve the http::*::path contract ID format — either by making sync.ts handle wildcard matching explicitly, or by aligning the manifest format to what HttpRouteExtractor emits. Without this, group.yaml HTTP cross-links will appear to resolve (no crash, no error) but will never actually connect to real extractor contracts.

[magyargergo]

@ivkond could you please include a flow chart of the analysis pipeline? 🙏

[magyargergo]

Nice and impressive work @ivkond ! Thank you for your contribution! 🙏

[ivkond]

Nice and impressive work @ivkond ! Thank you for your contribution! 🙏

Thank you, @magyargergo! 🙏 Really appreciate the thorough reviews — they pushed the plugin architecture into much better shape than my initial pass. If nothing else is blocking on your side, can we move on to step 3 (#792)?

[magyargergo]

@ivkond could you also include a follow up PR sorting out the bundled tree-sitter in the release process?

[magyargergo]

@claude can you check what's being included in this PR? we already uncovered that there's work from #793. I didn't prepare for that and we need to either revert it or review it properly

[github-actions]

Claude finished @magyargergo's task in 5m 47s —— View job

---

Scope audit: PR #796 vs issue #793

• Post initial comment
• Examine git diff and file contents
• Read manifest-extractor.ts in full
• Cross-reference with other extractors and PR boundaries
• Report findings

---

Findings

What is in this PR (confirmed against file SHAs)

Category	Files
Extractor orchestrators	grpc-extractor.ts, http-route-extractor.ts, topic-extractor.ts
New extractor	manifest-extractor.ts (228 LOC)
Plugin system	grpc-patterns/*, http-patterns/*, topic-patterns/*, tree-sitter-scanner.ts
Shared utility	fs-utils.ts
Vendor	vendor/tree-sitter-proto/*
Pipeline docs	PIPELINE.md (added)
Tests	*-extractor.test.ts updates, manifest-extractor.test.ts

The cross-boundary issue: ManifestExtractor does sync pipeline work

The three refactored extractors (GrpcExtractor, HttpRouteExtractor, TopicExtractor) all implement the standard ContractExtractor interface and return ExtractedContract[]. That is the extraction boundary.

ManifestExtractor breaks that boundary. It returns:

// manifest-extractor.ts:5-7
export interface ManifestExtractResult {
  contracts: StoredContract[];   // ← bridge-storage format, NOT ExtractedContract
  crossLinks: CrossLink[];       // ← produced here, not in sync.ts
}

In the main pipeline, sync.ts (#793) is supposed to:

1. Call each extractor → get ExtractedContract[]
2. Match provider/consumer contracts across repos → produce CrossLink[]
3. Write StoredContract[] to the bridge

ManifestExtractor does all three of those steps itself:

• Assigns role: 'provider' and role: 'consumer' per link (step 2)
• Populates the full StoredContract shape with repo, symbolUid, symbolRef, etc. (step 3)
• Produces crossLinks ready to write (step 3)

This is concrete evidence of #793 work included here — the role-assignment + cross-link generation + StoredContract formatting that belongs in sync.ts.

Why it happened

group.yaml manifests explicitly declare roles (role: 'provider'/'consumer'), so the author reasoned the role-assignment could be done in the extractor. That logic is understandable. But the consequence is:

• ManifestExtractor is not a ContractExtractor — it has a completely different call signature and return type
• sync.ts ([group] Sync pipeline (split 4/5 of #606) #793) cannot call it uniformly with the other extractors
• The bridge-formatting concern leaks into the extraction layer

What exactly needs review or reverting

There are two clean options:

Option A — Revert ManifestExtractor to ExtractedContract[]:
Change ManifestExtractor to return ExtractedContract[] per link (one per role side), with no CrossLink generation and no StoredContract format. Implement ContractExtractor fully. Move role-pairing and cross-link generation into sync.ts (#793), where it belongs alongside the equivalent logic for the three code-based extractors.

Option B — Keep it and explicitly design the dual-interface:
Define a GroupLevelExtractor interface (separate from ContractExtractor) for sources that produce fully-resolved bridge-ready contracts. Document that sync.ts must handle both interfaces. This is architecturally defensible given that manifest sources are semantically different (roles are declared, not inferred), but it must be a conscious design decision, not an accident.

Other #793-adjacent concerns

• PIPELINE.md (gitnexus/src/core/group/PIPELINE.md) was added in this PR. It flowcharts the full pipeline including the sync step (Contract matching → bridge.lbug). This is documentation, not code, but it does describe [group] Sync pipeline (split 4/5 of #606) #793's contract matching behavior — worth reviewing to make sure it matches what [group] Sync pipeline (split 4/5 of #606) #793 will actually implement.
• The http::*::path wildcard format in buildContractId (noted in prior reviews) requires [group] Sync pipeline (split 4/5 of #606) #793 to implement wildcard matching. If [group] Sync pipeline (split 4/5 of #606) #793 doesn't know about this format, HTTP manifest links will silently never match. This is a cross-PR protocol that must be agreed on before [group] Sync pipeline (split 4/5 of #606) #793 starts.

Verdict

The ManifestExtractor as written has genuinely crossed the #793 boundary. The scope question for @magyargergo and @ivkond is whether to go with Option A (revert to ExtractedContract[], push bridge-formatting to sync.ts) or Option B (accept the dual-interface and explicitly design sync.ts around it). Option A is cleaner and keeps the extraction layer uniform. Option B is faster since the code already works.