Bugfix/legacy facade dual state and v0.3.0 (cppalliance#175)

* fix(server-context): prevent legacy facade dual-state with explicit setup context

Add facadeSupersededBy tracking and installExplicitServerContext so mixing
legacy facades with setupCoreServer({ context }) throws instead of silent
dual-state. Keep client migration in resolveSetupContext.

Co-authored-by: Cursor <cursoragent@cursor.com>

* chore(release): pin facade deprecation at v0.3.0, opt-in runtime warnings

Update deprecation policy and MIGRATION anchors, bump to 0.3.0, move CHANGELOG
Unreleased content, and add PINECONE_DEPRECATION_WARNINGS-gated warn helper.

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: zho <jornathanm910923@gmail.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 3 people

CHANGELOG.md

@@ -8,6 +8,8 @@ Tagged releases are published to npm from GitHub Actions when a **GitHub Release
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-06-23
+
 ### Added
 
 - `guided_query` tool registered by `setupCoreServer` / package-root import (core-layer handler; no Alliance URL generators or index defaults required).
@@ -29,19 +31,17 @@ Tagged releases are published to npm from GitHub Actions when a **GitHub Release
 
 ### Deprecated
 
-- Module-level singleton facades — use `ServerContext` instance methods via `createServer(config)` and `{ context: ctx }` at setup instead. Deprecated in the **next minor release** (see `[Unreleased]` until version is tagged); earliest removal **two minor releases later** per [deprecation-policy.md](docs/deprecation-policy.md#deprecation-window). Affected symbols: `getPineconeClient`, `setPineconeClient`, `clearPineconeClient`, `getServerConfig`, `setServerConfig`, `resetServerConfig`, `registerUrlGenerator`, `unregisterUrlGenerator`, `generateUrlForNamespace`, `hasUrlGenerator`, `resetUrlGenerationRegistry`, `markSuggested`, `requireSuggested`, `resetSuggestionFlow`, `getNamespacesWithCache`, `invalidateNamespacesCache`, `getDefaultServerContext`. See [MIGRATION.md § Legacy module-facade deprecations](docs/MIGRATION.md#unreleased-legacy-module-facade-deprecations) and [deprecation-policy.md](docs/deprecation-policy.md#active-deprecations-legacy-module-facades).
-
-### Added
-
-- Zod schemas for all nine MCP tool success responses (`queryResponseSchema`, `guidedQueryResponseSchema`, etc.) exported from the package root for client-side validation. Success payloads are runtime-validated before return.
-- Stable vs experimental response field taxonomy documented in [docs/TOOLS.md](docs/TOOLS.md) and [docs/deprecation-policy.md](docs/deprecation-policy.md#stable-vs-experimental-mcp-response-fields).
-- Formal deprecation policy ([docs/deprecation-policy.md](docs/deprecation-policy.md)) and breaking-change release notes template ([docs/templates/breaking-change-release-notes.md](docs/templates/breaking-change-release-notes.md)).
+- Module-level singleton facades — use `ServerContext` instance methods via `createServer(config)` and `{ context: ctx }` at setup instead. Deprecated in **0.3.0**; earliest removal **0.5.0** per [deprecation-policy.md](docs/deprecation-policy.md#deprecation-window). Affected symbols: `getPineconeClient`, `setPineconeClient`, `clearPineconeClient`, `getServerConfig`, `setServerConfig`, `resetServerConfig`, `registerUrlGenerator`, `unregisterUrlGenerator`, `generateUrlForNamespace`, `hasUrlGenerator`, `resetUrlGenerationRegistry`, `markSuggested`, `requireSuggested`, `resetSuggestionFlow`, `getNamespacesWithCache`, `invalidateNamespacesCache`, `getDefaultServerContext`. Opt-in runtime warnings when `PINECONE_DEPRECATION_WARNINGS=1` or log level is `DEBUG`. See [MIGRATION.md § Legacy module-facade deprecations](docs/MIGRATION.md#030-legacy-module-facade-deprecations) and [deprecation-policy.md](docs/deprecation-policy.md#active-deprecations-legacy-module-facades).
 
 ### Removed
 
 - **Breaking (library):** `buildQueryExperimental` and `buildGuidedQueryExperimental` are no longer re-exported from `@will-cppa/pinecone-read-only-mcp` or `@will-cppa/pinecone-read-only-mcp/alliance`. They were internal helpers used to assemble the `experimental` block on `query` / `query_documents` / `guided_query` success payloads. The assembled fields and Zod schemas (`queryResponseSchema`, `QueryExperimental`, etc.) are unchanged — see [Unreleased stable vs experimental](docs/MIGRATION.md#unreleased-stable-vs-experimental-response-fields).
 - **No change:** `HybridQueryResult`, `HybridLegFailed`, and `KeywordIndexNamespacesResult` remain exported as the declared return types of public `PineconeClient` methods.
 
+### Fixed
+
+- Legacy module facades no longer silently diverge from an explicit `ServerContext` passed to `setupCoreServer` / `setupAllianceServer`. Mixing legacy facades with `{ context: ctx }` setup now throws with migration guidance instead of dual-state behavior.
+
 ## [0.2.0] - 2026-05-29
 
 - Package root export is the generic **core** layer (`setupCoreServer`); full CLI parity uses `@will-cppa/pinecone-read-only-mcp/alliance` (`setupAllianceServer`, built-in URL generators). `resolveConfig` uses env when set, else defaults: index **`rag-hybrid`**, rerank **`bge-reranker-v2-m3`** (constants `DEFAULT_INDEX_NAME` / `DEFAULT_RERANK_MODEL` in `src/core/config.ts`).

README.md

@@ -170,7 +170,7 @@ const server = await setupAllianceServer(resolveAllianceConfig({ apiKey: '...' }
 // Call teardownServer() before re-initializing the process-default context.
 ```
 
-Do not use this pattern for new code or multi-tenant embedding. See [docs/MIGRATION.md](docs/MIGRATION.md#unreleased-legacy-module-facade-deprecations).
+Do not use this pattern for new code or multi-tenant embedding. See [docs/MIGRATION.md](docs/MIGRATION.md#030-legacy-module-facade-deprecations).
 
 ### Custom URL generators
 

docs/MIGRATION.md

@@ -69,9 +69,9 @@ When no experimental fields apply, the `experimental` key is **omitted** (not an
 
 **Promotion:** Moving a field from `experimental` to stable requires CHANGELOG, TOOLS.md, and schema updates per [deprecation-policy.md § Stable vs experimental](./deprecation-policy.md#stable-vs-experimental-mcp-response-fields).
 
-## Unreleased: Legacy module-facade deprecations
+## 0.3.0: Legacy module-facade deprecations
 
-**Rationale:** Module-level singleton facades (`setPineconeClient`, `registerUrlGenerator`, `getDefaultServerContext`, etc.) delegate to a process-global `ServerContext`. They complicate multi-tenant embedding and hide initialization order. They are marked `@deprecated` in JSDoc; earliest removal is **two minor releases after** the deprecation minor (see [deprecation-policy.md § Deprecation window](./deprecation-policy.md#deprecation-window)).
+**Rationale:** Module-level singleton facades (`setPineconeClient`, `registerUrlGenerator`, `getDefaultServerContext`, etc.) delegate to a process-global `ServerContext`. They complicate multi-tenant embedding and hide initialization order. They are marked `@deprecated` in JSDoc since **0.3.0**; earliest removal is **0.5.0** (see [deprecation-policy.md § Deprecation window](./deprecation-policy.md#deprecation-window)).
 
 **Who is affected:** Library embedders importing facade functions from `@will-cppa/pinecone-read-only-mcp` or `/alliance`.
 
@@ -184,7 +184,7 @@ import { buildQueryExperimental } from '@will-cppa/pinecone-read-only-mcp';
 
 ## 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 (see [Legacy module-facade deprecations](#unreleased-legacy-module-facade-deprecations)).
+**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)).
 
 **Deprecated (migrate before removal):**
 

docs/deprecation-policy.md

@@ -34,16 +34,16 @@ APIs deprecated **before** this policy was published follow the removal target r
 
 ### Active deprecations - legacy module facades
 
-Module-level singleton facades delegate to `getDefaultServerContext()`. Migrate to **`ServerContext`** instance methods via `createServer(config)` and pass `{ context: ctx }` to `setupCoreServer` / `setupAllianceServer`. Deprecated in the **next published minor** after merge; earliest removal **two minor releases later** (per [Deprecation window](#deprecation-window) above). See [MIGRATION.md § Legacy module-facade deprecations](./MIGRATION.md#unreleased-legacy-module-facade-deprecations).
+Module-level singleton facades delegate to `getDefaultServerContext()`. Migrate to **`ServerContext`** instance methods via `createServer(config)` and pass `{ context: ctx }` to `setupCoreServer` / `setupAllianceServer`. Deprecated in **`0.3.0`**; earliest removal **`0.5.0`** (per [Deprecation window](#deprecation-window) above). See [MIGRATION.md § Legacy module-facade deprecations](./MIGRATION.md#030-legacy-module-facade-deprecations).
 
 | Facade | Layer | Replacement | Deprecated in | Earliest removal |
 | ------ | ----- | ----------- | ------------- | ---------------- |
-| `getPineconeClient` / `setPineconeClient` / `clearPineconeClient` | core | `ctx.getClient()` / `ctx.setClient()` / `ctx.clearClient()` | next minor (TBD at release) | two minors after deprecation minor |
-| `getServerConfig` / `setServerConfig` / `resetServerConfig` | core | `ctx.getConfig()` / `ctx.setConfig()` / `ctx.teardown()` | next minor (TBD at release) | two minors after deprecation minor |
-| `registerUrlGenerator` / `unregisterUrlGenerator` / `generateUrlForNamespace` / `hasUrlGenerator` / `resetUrlGenerationRegistry` | core | `ctx.registerUrlGenerator()` etc. / `ctx.resetUrlGenerators()` | next minor (TBD at release) | two minors after deprecation minor |
-| `markSuggested` / `requireSuggested` / `resetSuggestionFlow` | core | `ctx.markSuggested()` / `ctx.requireSuggested()` / `ctx.resetSuggestionFlow()` | next minor (TBD at release) | two minors after deprecation minor |
-| `getNamespacesWithCache` / `invalidateNamespacesCache` | core | `ctx.getNamespacesWithCache()` / `ctx.invalidateNamespacesCache()` | next minor (TBD at release) | two minors after deprecation minor |
-| `getDefaultServerContext` | core | Return value of `createServer` or explicit `context` at setup | next minor (TBD at release) | two minors after deprecation minor |
+| `getPineconeClient` / `setPineconeClient` / `clearPineconeClient` | core | `ctx.getClient()` / `ctx.setClient()` / `ctx.clearClient()` | **0.3.0** | **0.5.0** |
+| `getServerConfig` / `setServerConfig` / `resetServerConfig` | core | `ctx.getConfig()` / `ctx.setConfig()` / `ctx.teardown()` | **0.3.0** | **0.5.0** |
+| `registerUrlGenerator` / `unregisterUrlGenerator` / `generateUrlForNamespace` / `hasUrlGenerator` / `resetUrlGenerationRegistry` | core | `ctx.registerUrlGenerator()` etc. / `ctx.resetUrlGenerators()` | **0.3.0** | **0.5.0** |
+| `markSuggested` / `requireSuggested` / `resetSuggestionFlow` | core | `ctx.markSuggested()` / `ctx.requireSuggested()` / `ctx.resetSuggestionFlow()` | **0.3.0** | **0.5.0** |
+| `getNamespacesWithCache` / `invalidateNamespacesCache` | core | `ctx.getNamespacesWithCache()` / `ctx.invalidateNamespacesCache()` | **0.3.0** | **0.5.0** |
+| `getDefaultServerContext` | core | Return value of `createServer` or explicit `context` at setup | **0.3.0** | **0.5.0** |
 
 `teardownServer()` remains supported during the deprecation window; prefer `ctx.teardown()` or `await using` on the setup handle. Documented in MIGRATION.md; not marked `@deprecated` until a later release.
 
@@ -110,7 +110,7 @@ New response fields added before `1.0.0` default to `experimental` unless explic
 
 Legacy module-level facades are deprecated per the [active deprecations table](./deprecation-policy.md#active-deprecations-legacy-module-facades) above. `ServerContext` + `createServer` / setup APIs are the supported public contract going forward.
 
-See [MIGRATION.md § Legacy module-facade deprecations](./MIGRATION.md#unreleased-legacy-module-facade-deprecations) for before/after embedder snippets.
+See [MIGRATION.md § Legacy module-facade deprecations](./MIGRATION.md#030-legacy-module-facade-deprecations) for before/after embedder snippets.
 
 ## CHANGELOG format for breaking changes
 

examples/alliance/library-embedding-demo.ts

@@ -16,7 +16,7 @@
  *
  * **Legacy (deprecated):** `setPineconeClient(client)` then
  * `await setupAllianceServer(config)` still works during the deprecation window;
- * see [docs/MIGRATION.md#unreleased-legacy-module-facade-deprecations](docs/MIGRATION.md#unreleased-legacy-module-facade-deprecations).
+ * see [docs/MIGRATION.md#030-legacy-module-facade-deprecations](docs/MIGRATION.md#030-legacy-module-facade-deprecations).
  */
 
 import { createServer, PineconeClient } from '@will-cppa/pinecone-read-only-mcp';

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@will-cppa/pinecone-read-only-mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A Model Context Protocol (MCP) server that provides semantic search over Pinecone vector databases using hybrid search (dense + sparse) with reranking.",
   "type": "module",
   "main": "dist/core/index.js",

src/alliance/setup.ts

@@ -1,6 +1,6 @@
 import { ALLIANCE_SERVER_INSTRUCTIONS } from '../constants.js';
 import type { ServerConfig } from '../core/config.js';
-import { getDefaultServerContext, type ServerContext } from '../core/server/server-context.js';
+import { resolveDefaultServerContext, type ServerContext } from '../core/server/server-context.js';
 import { resolveAllianceConfig } from './config.js';
 import { setupCoreServer, type ServerHandle, type SetupCoreServerOptions } from '../core/setup.js';
 import { registerBuiltinUrlGenerators } from './url-builtins.js';
@@ -82,7 +82,7 @@ export async function setupAllianceServer(
       config: opts.config ?? config,
       instructions,
     });
-    resolvedCtx = getDefaultServerContext();
+    resolvedCtx = resolveDefaultServerContext();
   }
 
   registerBuiltinUrlGenerators(resolvedCtx);

src/core/server/client-context.ts

@@ -1,41 +1,42 @@
 import { PineconeClient } from '../pinecone-client.js';
-import { getDefaultServerContext } from './server-context.js';
+import { warnLegacyFacade } from './legacy-facade-warn.js';
+import { resolveDefaultServerContext } from './server-context.js';
 
 /**
  * Return the shared Pinecone client; throws if setPineconeClient has not been called.
  *
- * @deprecated Legacy module facade. Use {@link ServerContext.getClient} on a
- * {@link ServerContext} from {@link createServer} instead. Removal follows
- * docs/deprecation-policy.md (no earlier than two minor releases after the
- * deprecation minor). See docs/MIGRATION.md#unreleased-legacy-module-facade-deprecations.
+ * @deprecated since 0.3.0 — removal no earlier than 0.5.0. Legacy module facade. Use
+ * {@link ServerContext.getClient} on a {@link ServerContext} from {@link createServer}
+ * instead. See docs/MIGRATION.md#030-legacy-module-facade-deprecations.
  * @see ServerContext.getClient
  */
 export function getPineconeClient(): PineconeClient {
-  return getDefaultServerContext().getClientIfSet();
+  warnLegacyFacade('getPineconeClient');
+  return resolveDefaultServerContext().getClientIfSet();
 }
 
 /**
  * Set the shared Pinecone client used by all MCP tools.
  *
- * @deprecated Legacy module facade. Use {@link ServerContext.setClient} on a
- * {@link ServerContext} from {@link createServer} instead. Removal follows
- * docs/deprecation-policy.md (no earlier than two minor releases after the
- * deprecation minor). See docs/MIGRATION.md#unreleased-legacy-module-facade-deprecations.
+ * @deprecated since 0.3.0 — removal no earlier than 0.5.0. Legacy module facade. Use
+ * {@link ServerContext.setClient} on a {@link ServerContext} from {@link createServer}
+ * instead. See docs/MIGRATION.md#030-legacy-module-facade-deprecations.
  * @see ServerContext.setClient
  */
 export function setPineconeClient(client: PineconeClient): void {
-  getDefaultServerContext().setClient(client);
+  warnLegacyFacade('setPineconeClient');
+  resolveDefaultServerContext().setClient(client);
 }
 
 /**
  * Clear the shared client (used by {@link teardownServer} and tests).
  *
- * @deprecated Legacy module facade. Use {@link ServerContext.clearClient} on a
- * {@link ServerContext} from {@link createServer} instead. Removal follows
- * docs/deprecation-policy.md (no earlier than two minor releases after the
- * deprecation minor). See docs/MIGRATION.md#unreleased-legacy-module-facade-deprecations.
+ * @deprecated since 0.3.0 — removal no earlier than 0.5.0. Legacy module facade. Use
+ * {@link ServerContext.clearClient} on a {@link ServerContext} from {@link createServer}
+ * instead. See docs/MIGRATION.md#030-legacy-module-facade-deprecations.
  * @see ServerContext.clearClient
  */
 export function clearPineconeClient(): void {
-  getDefaultServerContext().clearClient();
+  warnLegacyFacade('clearPineconeClient');
+  resolveDefaultServerContext().clearClient();
 }

src/core/server/config-context.ts

@@ -1,33 +1,34 @@
 import type { ServerConfig } from '../config.js';
+import { warnLegacyFacade } from './legacy-facade-warn.js';
 import {
-  getDefaultServerContext,
+  resolveDefaultServerContext,
   setDefaultServerContext,
   setPendingServerConfig,
 } from './server-context.js';
 
 /**
  * Replace the process-global server config (called from setup with CLI/env-derived config).
  *
- * @deprecated Legacy module facade. Use {@link ServerContext.setConfig} on a
- * {@link ServerContext} from {@link createServer} instead. Removal follows
- * docs/deprecation-policy.md (no earlier than two minor releases after the
- * deprecation minor). See docs/MIGRATION.md#unreleased-legacy-module-facade-deprecations.
+ * @deprecated since 0.3.0 — removal no earlier than 0.5.0. Legacy module facade. Use
+ * {@link ServerContext.setConfig} on a {@link ServerContext} from {@link createServer}
+ * instead. See docs/MIGRATION.md#030-legacy-module-facade-deprecations.
  * @see ServerContext.setConfig
  */
 export function setServerConfig(config: ServerConfig): void {
+  warnLegacyFacade('setServerConfig');
   setPendingServerConfig(config);
 }
 
 /**
  * Clear active config so the next `getServerConfig()` resolves again (used by {@link teardownServer}).
  *
- * @deprecated Legacy module facade. Use {@link ServerContext.teardown} on a
- * {@link ServerContext} from {@link createServer} instead. Removal follows
- * docs/deprecation-policy.md (no earlier than two minor releases after the
- * deprecation minor). See docs/MIGRATION.md#unreleased-legacy-module-facade-deprecations.
+ * @deprecated since 0.3.0 — removal no earlier than 0.5.0. Legacy module facade. Use
+ * {@link ServerContext.teardown} on a {@link ServerContext} from {@link createServer}
+ * instead. See docs/MIGRATION.md#030-legacy-module-facade-deprecations.
  * @see ServerContext.teardown
  */
 export function resetServerConfig(): void {
+  warnLegacyFacade('resetServerConfig');
   setDefaultServerContext(null);
 }
 
@@ -39,12 +40,12 @@ export function resetServerConfig(): void {
  * (requires `PINECONE_API_KEY` and `PINECONE_INDEX_NAME` or throws). Alliance apps should
  * pass config from `resolveAllianceConfig()` into `setupAllianceServer(config)`.
  *
- * @deprecated Legacy module facade. Use {@link ServerContext.getConfig} on a
- * {@link ServerContext} from {@link createServer} instead. Removal follows
- * docs/deprecation-policy.md (no earlier than two minor releases after the
- * deprecation minor). See docs/MIGRATION.md#unreleased-legacy-module-facade-deprecations.
+ * @deprecated since 0.3.0 — removal no earlier than 0.5.0. Legacy module facade. Use
+ * {@link ServerContext.getConfig} on a {@link ServerContext} from {@link createServer}
+ * instead. See docs/MIGRATION.md#030-legacy-module-facade-deprecations.
  * @see ServerContext.getConfig
  */
 export function getServerConfig(): ServerConfig {
-  return getDefaultServerContext().getConfig();
+  warnLegacyFacade('getServerConfig');
+  return resolveDefaultServerContext().getConfig();
 }