refactor: trim internal-only exports from the public barrels (#203) (#206)

Remove four internal-only re-exports from the package root and /alliance entry
to shrink the public surface and blast radius: trimOptional,
createUnconfiguredAllianceContext (core), and the concrete URL generators
generatorMailing, generatorSlackCpplang (alliance). The symbols stay in their
modules; only the barrel re-exports are dropped, and no in-repo importer used
them via the barrel. Deprecated-in-window legacy facades are kept.

Add a snapshot guard test that pins the runtime value-export allow-list for both
barrels, so a future internal symbol leaking into a barrel fails CI.

Document the removal in CHANGELOG (Breaking, library) and MIGRATION.

Author: timon0305

CHANGELOG.md

@@ -19,6 +19,10 @@ Tagged releases are published to npm from GitHub Actions when a **GitHub Release
 - **Breaking (library API):** `PineconeClient.listNamespacesWithMetadata()` now returns `{ namespaces, warnings }` instead of a bare array. Migration: [MIGRATION.md § Unreleased PineconeClient.listNamespacesWithMetadata](docs/MIGRATION.md#unreleased-pineconeclientlistnamespaceswithmetadata-return-shape).
 - **Instructions:** Trimmed operator/install/deploy content (env-var setup, misconfiguration note, Alliance CLI index/rerank defaults, stderr logging config) from `CORE_SERVER_INSTRUCTIONS` and `ALLIANCE_INSTRUCTIONS_APPENDIX` — reduces per-session token cost; no behavior change. Replaced colliding Alliance appendix steps 4–5 with unnumbered "Manual Alliance flow" bullets (includes `PINECONE_DISABLE_SUGGEST_FLOW=true` escape clause). Full detail remains in [docs/CONFIGURATION.md](docs/CONFIGURATION.md).
 
+### Removed
+
+- **Breaking (library):** Trimmed internal-only re-exports from the package root and `/alliance` entry to shrink the public surface and blast radius: `trimOptional`, `createUnconfiguredAllianceContext` (core), and the concrete URL generators `generatorMailing`, `generatorSlackCpplang` (alliance). These were internal helpers, not part of the documented API; register built-ins via `registerBuiltinUrlGenerators` and build contexts via `createServer` / `createIsolatedContext`. A snapshot test now guards the runtime export surface so internal symbols cannot leak back in. See [MIGRATION.md](docs/MIGRATION.md#internal-only-re-exports-removed-203). (#203)
+
 ## [0.4.0] - 2026-06-24
 
 ### Added

docs/MIGRATION.md

@@ -252,6 +252,16 @@ import { buildQueryExperimental } from '@will-cppa/pinecone-read-only-mcp';
 
 `PineconeClient.query()` return types (`HybridQueryResult`, etc.) and all Zod response schemas remain on the public surface.
 
+### Internal-only re-exports removed (#203)
+
+**Who is affected:** Library embedders that imported any of these internal helpers from the package root or `/alliance`:
+
+- `trimOptional` (a string-trim helper)
+- `createUnconfiguredAllianceContext` (an internal context factory used by setup guards)
+- `generatorMailing`, `generatorSlackCpplang` (the concrete Alliance URL generators)
+
+**After:** none of these are part of the supported surface. Trim whitespace yourself, build contexts with `createServer` / `createIsolatedContext`, and register the built-in URL generators with `registerBuiltinUrlGenerators` (the documented entry point) instead of importing the individual generators. The public runtime export surface is now guarded by a snapshot test so internal symbols cannot leak back in.
+
 ## Unreleased: `ServerContext` instance APIs (initial)
 
 **Rationale:** Process-global singletons (Pinecone client slot, config, URL registry, suggest-flow gate, namespaces cache) complicate testing and multi-tenant embedding. The initial milestone introduces an opt-in **`ServerContext`**; legacy module facades are deprecated since **0.3.0** (see [Legacy module-facade deprecations](#030-legacy-module-facade-deprecations)).

src/alliance/index.ts

@@ -13,9 +13,5 @@ export {
 export type { AllianceServerConfig } from './config.js';
 export type { AllianceServerContext } from '../core/server/server-context.js';
 export { setupAllianceServer, type SetupAllianceServerOptions } from './setup.js';
-export {
-  registerBuiltinUrlGenerators,
-  generatorMailing,
-  generatorSlackCpplang,
-} from './url-builtins.js';
+export { registerBuiltinUrlGenerators } from './url-builtins.js';
 export type { RegisterBuiltinUrlGeneratorsOptions } from './url-builtins.js';

src/core/__tests__/public-exports.test.ts

@@ -1,9 +1,77 @@
 import { describe, expect, it } from 'vitest';
 import * as core from '../index.js';
+import * as alliance from '../../alliance/index.js';
+
+/**
+ * Guards the public runtime export surface of both barrels (#203). Types are
+ * erased at runtime, so only value exports appear here; this catches an internal
+ * symbol accidentally leaking into a barrel and growing the blast radius. When a
+ * genuinely public symbol is added, add it to the allow-list in the same change.
+ */
+const CORE_PUBLIC_EXPORTS = [
+  'PineconeClient',
+  'ServerContext',
+  'SourceRegistry',
+  'buildSourceRegistry',
+  'countResponseSchema',
+  'createIsolatedContext',
+  'createServer',
+  'generateUrlForNamespace',
+  'generateUrlsResponseSchema',
+  'getDefaultServerContext',
+  'guidedQueryResponseSchema',
+  'hasUrlGenerator',
+  'keywordSearchResponseSchema',
+  'keywordSearchSuccessResponseSchema',
+  'listNamespacesResponseSchema',
+  'namespaceRouterResponseSchema',
+  'queryDocumentsResponseSchema',
+  'queryResponseSchema',
+  'queryResultRowSchema',
+  'querySuccessResponseSchema',
+  'registerUrlGenerator',
+  'resolveConfig',
+  'setPineconeClient',
+  'setupCoreServer',
+  'suggestQueryParams',
+  'suggestQueryParamsResponseSchema',
+  'teardownServer',
+  'toolErrorSchema',
+  'unregisterUrlGenerator',
+  'validateMetadataFilter',
+  'validateMetadataFilterDetailed',
+];
+
+const ALLIANCE_PUBLIC_EXPORTS = [
+  ...CORE_PUBLIC_EXPORTS,
+  'ALLIANCE_DEFAULT_INDEX_NAME',
+  'ALLIANCE_DEFAULT_RERANK_MODEL',
+  'DEFAULT_ALLIANCE_RERANK_MODEL',
+  'registerBuiltinUrlGenerators',
+  'resolveAllianceConfig',
+  'setupAllianceServer',
+].sort();
 
 describe('public export surface', () => {
   it('does not export internal experimental block builders', () => {
     expect('buildQueryExperimental' in core).toBe(false);
     expect('buildGuidedQueryExperimental' in core).toBe(false);
   });
+
+  it('does not export the internal-only symbols trimmed in #203', () => {
+    for (const name of ['trimOptional', 'createUnconfiguredAllianceContext']) {
+      expect(name in core).toBe(false);
+    }
+    for (const name of ['generatorMailing', 'generatorSlackCpplang']) {
+      expect(name in alliance).toBe(false);
+    }
+  });
+
+  it('core barrel value exports match the allow-list', () => {
+    expect(Object.keys(core).sort()).toEqual([...CORE_PUBLIC_EXPORTS].sort());
+  });
+
+  it('alliance barrel value exports match the allow-list', () => {
+    expect(Object.keys(alliance).sort()).toEqual(ALLIANCE_PUBLIC_EXPORTS);
+  });
 });

src/core/index.ts

@@ -11,7 +11,6 @@ export {
   ServerContext,
   createServer,
   createIsolatedContext,
-  createUnconfiguredAllianceContext,
   getDefaultServerContext,
 } from './server/server-context.js';
 export type {
@@ -65,7 +64,7 @@ export {
   hasUrlGenerator,
 } from './server/url-registry.js';
 export type { UrlGenerationResult, UrlGenerator, UrlGeneratorFn } from './server/url-registry.js';
-export { resolveConfig, trimOptional } from './config.js';
+export { resolveConfig } from './config.js';
 export type { SourceDefinition } from './server/source-config.js';
 export { SourceRegistry, buildSourceRegistry } from './server/source-registry.js';
 export type { AggregatedCacheResult, PerSourceCacheResult } from './server/source-registry.js';