fix(apollo-vertex)!: declare vs-core and react-db as peers, move Proteus to a subpath

[ruudandriessen]

Why

@tanstack/react-db, @uipath/vs-core and @uipath/proteus-client were declared only in peerDependenciesMeta, yet the root barrel imports all three. An app that imports only Button could still fail to resolve them, for example in Vite dev. check-dist.mjs treated a meta-only entry as declared, so CI didn't catch it.

@uipath/vs-core is now on public npm (4.5.1), so it and react-db can be normal peers. @uipath/proteus-client still isn't public, so it gets a workaround.

What

• @tanstack/react-db (^0.1.83) and @uipath/vs-core (^4.4.0) are now peerDependencies, and also dev dependencies. Their type stubs in types/optional-deps.d.ts are gone, so the package builds against the real types.
• createProteusProvider, FlagMapping and ProteusFeatureFlagValues move to a new @uipath/apollo-vertex/proteus subpath. @uipath/proteus-client stays an optional peer (meta only), and the root entry no longer reaches it.
• check-dist.mjs: the root entry may import only dependencies and peerDependencies. Meta-only peers are allowed only from subpaths.
• Fixes required by the real types:
  • useGroupId and useGroupMembers passed a row type to useLiveQuery, which the real API doesn't accept. The collections are now inferred.
  • vs-core types solutionTests from the app's registered entities, which this package can't see. A new getSolutionTestCollection helper looks a collection up by name.
• The dev dependencies are pinned to a matching set: react-db 0.1.83, query-db-collection 1.0.36 and db 0.6.5. Each TanStack DB package pins an exact @tanstack/db, and with open ranges pnpm picked two copies whose collections don't work together. The README, docs and setup skill now tell consumers to match these versions.
• README, docs pages (getting started, feature flags, solution tests), the setup skill and knip.jsonc are updated.

Breaking

createProteusProvider and its types are no longer exported from the root. Import them from @uipath/apollo-vertex/proteus.

Verification

All of these pass locally against the published @uipath/vs-core@4.5.1: package and docs-app typecheck, lint, vitest (46 tests), build including check-dist, knip and format:check. check-dist fails as expected (.: imports undeclared package @uipath/vs-core) when vs-core is put back as a meta-only peer. I haven't run a build in a separate consumer app.

[github-actions]

Dependency License Review

• ✅ 1957 package(s) scanned
• ✅ No license issues found
• ⚠️ 2 package(s) excluded (see details below)

License distribution

License	Packages
MIT	1721
ISC	91
Apache-2.0	57
BSD-3-Clause	28
BSD-2-Clause	23
BlueOak-1.0.0	8
MPL-2.0	4
CC0-1.0	4
MIT-0	3
MIT OR Apache-2.0	2
(MIT OR Apache-2.0)	2
Unlicense	2
LGPL-3.0-or-later	1
Python-2.0	1
CC-BY-4.0	1
(MPL-2.0 OR Apache-2.0)	1
Unknown	1
Artistic-2.0	1
(WTFPL OR MIT)	1
(BSD-2-Clause OR MIT OR Apache-2.0)	1
CC-BY-3.0	1
0BSD	1
(MIT OR CC0-1.0)	1
MIT AND ISC	1

Excluded packages

Package	Version	License	Reason
@img/sharp-libvips-linux-x64	1.3.4	LGPL-3.0-or-later	LGPL pre-built binary, not linked
khroma	2.1.0	Unknown	MIT per GitHub repo, missing license field in package.json

[Copilot]

🔵 Needs a closer look

The breaking export relocation and changed peer dependency graph need isolated consumer validation before approval.

2 open issues

• Update setup callout to supported @​uipath/vs-core 4.x range · New
• Align React Query and persist-client peer dependency versions · New

1 file not reviewed

• pnpm-lock.yaml: Generated file

What changed in this PR

This PR corrects Apollo Vertex’s peer declarations and isolates the private Proteus adapter from root imports.

Changes:

• Moves Proteus exports to /proteus.
• Replaces dependency stubs with real types and updates collection access.
• Tightens distribution checks and updates setup documentation.

File	Description
pnpm-lock.yaml	Records new dependency resolutions.
packages/​apollo-vertex/​types/​optional-deps.d.ts	Removes React DB and vs-core stubs.
packages/​apollo-vertex/​skills/​setup/​SKILL.md	Updates peer installation guidance.
packages/​apollo-vertex/​scripts/​check-dist.mjs	Rejects meta-only root dependencies.
packages/​apollo-vertex/​registry/​solution-tests/​use-solution-tests.ts	Uses the collection lookup helper.
packages/​apollo-vertex/​registry/​solution-tests/​use-solution-test-collection.ts	Adds typed collection lookup.
packages/​apollo-vertex/​registry/​shell/​use-group-members.ts	Infers query types.
packages/​apollo-vertex/​registry/​shell/​use-group-id.ts	Infers query types.
packages/​apollo-vertex/​README.md	Documents peers and Proteus imports.
packages/​apollo-vertex/​package.json	Declares peers and Proteus subpath.
packages/​apollo-vertex/​entries/​proteus.ts	Exports the isolated adapter.
packages/​apollo-vertex/​entries/​index.ts	Removes root Proteus exports.
knip.jsonc	Narrows ignored dependencies.
apps/​apollo-vertex/​content/​docs/​templates/​solution-tests.mdx	Updates React DB installation guidance.
apps/​apollo-vertex/​content/​docs/​getting-started.mdx	Revises peer setup instructions.
apps/​apollo-vertex/​content/​docs/​components/​feature-flags.mdx	Uses Proteus subpath imports.

_{Review effort: Balanced}

[github-actions]

📊 Coverage + size by package

Per-package coverage and bundle size on this PR. New-line coverage = of the source lines this PR adds or changes, the % hit by tests.

Package	Coverage	New-line coverage	Packed (gzip)	Unpacked	vs main
@uipath/apollo-core	—	—	42.02 MB	50.17 MB	±0
@uipath/apollo-react	—	—	7.99 MB	31.45 MB	±0
@uipath/apollo-ui-icons	—	—	2.86 MB	6.97 MB	±0
@uipath/apollo-vertex	71.2%	— (39 untracked)	330.3 KB	1.86 MB	+286 B
@uipath/apollo-wind	—	—	785.2 KB	4.55 MB	±0
@uipath/ap-chat	—	—	40.37 MB	45.58 MB	±0

_{"Coverage" is each package's own coverage.include scope (e.g. apollo-core instruments only scripts/). "Packed"/"Unpacked" come from npm pack --dry-run and only cover built packages — "—" means not measured this run (package not affected / not built). "vs main" is the packed (gzipped) delta against the last successful main build (the package-sizes artifact from the Release workflow); "—" there means no main baseline was available this run. The baseline is main's latest build, not this PR's exact merge-base, so it includes any drift since the branch diverged. Packages with no vitest config are omitted.}

[Copilot]

🔵 Needs a closer look

The breaking export migration and newly required peer dependency graph still need validation in an independent consumer build.

1 open issue

• Document TanStack DB version matching in the installation section · New

2 resolved since last review

• Align React Query and persist-client peer dependency versions
• Update setup callout to supported @​uipath/vs-core 4.x range

1 file not reviewed

• pnpm-lock.yaml: Generated file

_{Review effort: Balanced}

[github-actions]

Storybook visual diff

✅ No stories are affected by this PR's changes; nothing to compare. Logs

Updated (PT): Oct 19, 2026, 06:03:52 AM

[Copilot]

🔵 Needs a closer look

The breaking export migration and newly required peer dependencies still need standalone consumer validation and human review.

1 open issue

• Document TanStack DB version matching in the installation section

1 file not reviewed

• pnpm-lock.yaml: Generated file

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

The breaking export migration and coupled peer dependencies still need validation in a clean consumer app before maintainer approval.

No open issues 🎉

1 resolved since last review

• Document TanStack DB version matching in the installation section

1 file not reviewed

• pnpm-lock.yaml: Generated file

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Registry validation replaces the shipped React DB constraint with an excluded version, leaving consumer compatibility unvalidated.

1 open issue

• Test replaces React DB with unsupported version · New

1 file not reviewed

• pnpm-lock.yaml: Generated file

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

The breaking export and dependency changes still need verification in a separate consumer application.

No open issues 🎉

1 resolved since last review

• Test replaces React DB with unsupported version

1 file not reviewed

• pnpm-lock.yaml: Generated file

_{Review effort: Balanced}