[antoinetoussaint-byte]

What was wrong

codefly generate client --services <S> narrowed only the facade. The library still carried every service of the contract (#1173):

• contract/contract.binpb;
• contract/catalog.codefly.json;
• library.codefly.yaml's sources[].services;
• every language's bindings.

So a library generated for one saas service carried all 36 of them. That blocks module-saas-starter#1217 (B2).

What changes

GenerateClientLibrary narrows its entries before anything is generated (pkg/generators/narrow.go, narrowEntries).

What the persisted contract keeps:

• the named services;
• the declarations those services reach: their methods' messages and, transitively, every message and enum those name (a nested type keeps the top-level message holding it);
• every extension of a kept message, wherever that extension is declared.

Files kept whole:

• any file defining a custom option that a kept declaration sets, with its imports. This covers options on any element, including extension ranges, and extensions set inside a message-valued option's value;
• any shared upstream file (google/protobuf, google/api, google/rpc, google/type, buf/validate), in its canonical shape.

How the result is built:

• No file declares a service that was not named.
• Imports are recomputed for each file, including chains of public imports.
• Source info is re-indexed, so each doc comment stays with its declaration.
• The narrowed set must resolve (protodesc.NewFiles) before it is used.
• Narrowing depends only on the contract bytes: options stay raw (no resolver) and marshalling is deterministic.

Digests. The digest that identifies a library's source stays the producer's contract digest:

• sources[].contract-digest and clients.codefly.json record that same digest.
• Editing the services list, or adding an entry, regenerates in place. Only a new producer contract needs --force.
• contract/catalog.codefly.json carries the digest of the narrowed contract.binpb written beside it.
• Libraries generated before this change keep the same producer digest, so they regenerate without --force.

Outputs:

• The catalog's services, the manifest's sources[].services, the bindings and the facade in Go, TypeScript and Python all come from the narrowed contract.
• A service name the contract does not declare is refused. The error names it and lists the services the contract does declare.
• A local --from module/service with --services now generates from the narrowed descriptor set, because the proto sources declare every service.

Aggregated libraries (sync solution-sdk):

• Each entry persists its own narrowed contract, which declares only its own selection and matches its catalog.
• Bindings are generated from the closure of all entries at once, so a file two entries share is generated identically for both.
• An entry naming no services keeps its whole contract.
• Two entries carrying different versions of one file are refused, naming the file and both entries.
• A library where no entry names services is untouched.
• sync solution-sdk gains the --force flag that its digest refusal tells you to use.

Reuse

• Reused:
  • checkContractDiamond, which still runs on the producer contracts;
  • the existing descriptor-set generation path (markUpstreamModulesAsImports, targetFilesForPackage);
  • the upstreamProtoModules table, through a language-independent matchUpstreamModule that upstreamModuleFor now calls.
• Not added: no second generation path and no per-language filtering.

Why not buf's --type filtering. The companion's buf (1.73.0) has buf build <image> --type <name>, which filters one image down to the closure of the named types. I did not use it, for three reasons:

1. It filters one image at a time. An aggregated library needs a closure computed across several contracts, so that a file shared by name is generated the same for every entry. Separate --type runs would cut a shared file differently for each entry, and the merged tree would keep whichever copy was written last. That is the conflict narrowEntries prevents.
2. It would tie the library to buf's version. The persisted contract and its digest would then depend on the companion's buf release, so a companion bump could move every committed library. In-process narrowing depends only on the contract bytes.
3. It needs Docker. Narrowing runs before generation and can be tested without Docker. pkg/generators has no plumbing for running buf in the companion; using it would mean adding a second Docker path.

Size. narrow.go is about 720 lines including comments and doc blocks, over the ~500-line guideline. Review r140's F3–F6 added the extension and nested-option handling.

Classification

Fix, made in the generator that owns what a library contains.

• Docs: docs/commands.md said --services does not work over a descriptor set. That limitation is gone, because the facade plugins now run with strategy: all, so the paragraph now describes what --services does. docs/cli-reference.md was regenerated.
• Stale comments: two code comments about a core facade bug, and one test comment, were stale and are removed.

Tests

pkg/generators/narrow_test.go (no Docker):

• one service keeps exactly what it needs, comments stay with their declarations, and the producer digest is kept;
• narrowing is stable and idempotent;
• an unknown service is refused;
• a library that names no services is untouched;
• in an aggregated library, each entry persists only its own selection, the shared file is generated once, and adding an entry leaves the other entry's contract unchanged;
• two versions of one file are refused;
• extension-range options, extensions of a kept message declared in another file, and extensions inside a message-valued option all keep their defining files (proto2 fixture). Each of these three fixes was mutation-checked: removing it makes the test fail.

cmd/generate/client_services_test.go (Docker-gated):

• TestGenerateClientServicesNarrowsTheWholeLibrary: generating one service of a real buf-compiled two-service contract in Go, TypeScript and Python carries only that service and what it needs. The manifest records the producer digest. go vet and a Python import both pass. This test fails without the narrowing.
• TestGenerateClientServicesIsStable: regenerating in place, and generating afresh into another directory, both reproduce the library byte for byte.
• TestGenerateClientServicesSelectionChangesRegenerateWithoutForce: editing an entry's services, then adding a second entry, both regenerate without --force. Each entry's persisted contract declares only its own service. Both record the producer digest. Regenerating is stable and the bindings import. With the old narrowed-digest behaviour, this test fails with the refusal. It uses Python because one Go package cannot hold two facades of different names; that limit of aggregated Go libraries predates this change.

Evidence

• CODEFLY_GENERATE_QUALIFY=1 go test -tags proto_companion_required ./cmd/generate/ ./cmd/publish/ ./cmd/sync/ ./pkg/generators/ -count=1 passed locally on proto companion 0.0.18 (ghcr.io/codefly-dev/proto:0.0.18).
• go test -race ./pkg/generators/ ./cmd/sync/ passed.
• golangci-lint reports 0 issues on the changed packages.
• I compiled the generated TypeScript library by hand (npm install && npm run build) at the first head. It built cleanly and mentioned no other service.

Not in this PR

The issue also asks for a --check mode on generate client. That flag is not here; the drift test above is the behaviour such a flag would gate on. sync solution-sdk --check already exists.

Refs #1173

🤖 Generated with Claude Code