feat!(types): resolve PolicyInfo / MCPPolicyInfo naming collision (v6.0.0)

The TS SDK had two unrelated types using overlapping names that
predated the OpenAPI spec write-up:

- `PolicyInfo` (proxy.ts): proxy-mode shape returned by /api/request
- `MCPPolicyInfo` (connector.ts): MCP shape returned by /mcp/* — this
  is what the OpenAPI spec actually calls `PolicyInfo`.

The wire-shape contract gate flagged this as drift on the spec
PolicyInfo schema, since the SDK's PolicyInfo did not match the spec
shape and there was no way for the gate to know the SDK uses
MCPPolicyInfo for the spec's PolicyInfo.

This PR swaps the names to align with the OpenAPI spec:

  v5.x          →   v6.0.0
  PolicyInfo    →   ProxyPolicyInfo (proxy-mode shape)
  MCPPolicyInfo →   PolicyInfo (MCP shape; matches OpenAPI)

Both old names are kept as `type` aliases for one major-version
migration window:

  type MCPPolicyInfo = PolicyInfo  (in connector.ts)
  type PolicyInfoLegacyProxyShape = ProxyPolicyInfo  (in proxy.ts)

Removed in v7.0.0.

Code that uses the proxy-mode shape via `response.policyInfo` on
ExecuteQueryResponse continues to compile — the property type
changed from `PolicyInfo` to `ProxyPolicyInfo`, but the field shape
is identical.

Code that explicitly imports `PolicyInfo` from the public API will
see the new MCP shape (which is what the spec said it should be).

Migration:
- s/MCPPolicyInfo/PolicyInfo/ in MCP-handling code, OR keep the
  MCPPolicyInfo alias for now.
- s/PolicyInfo/ProxyPolicyInfo/ in proxy-mode code, OR temporarily
  use PolicyInfoLegacyProxyShape.

CHANGELOG marks this as BREAKING under [Unreleased]; the v6.0.0
header will land at release time.

Tests: 859 pass. Lint clean.

Author: saurabhjain1592

CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### BREAKING — `PolicyInfo` reassignment (v6.0.0)
+
+`PolicyInfo` and `MCPPolicyInfo` referred to two different concepts in v5.x:
+
+- `PolicyInfo` (in `src/types/proxy.ts`) was the proxy-mode shape returned by `/api/request` — fields like `policiesEvaluated`, `staticChecks`, `processingTime`, `tenantId`, `codeArtifact`.
+- `MCPPolicyInfo` (in `src/types/connector.ts`) was the MCP shape returned by `/api/v1/mcp/check-input` and friends — fields like `policies_evaluated`, `blocked`, `block_reason`, `processing_time_ms`, `matched_policies`. **This is what the OpenAPI spec calls `PolicyInfo`.**
+
+The naming has been swapped to align with the OpenAPI spec:
+
+| In v5.x | In v6.0.0 |
+|--|--|
+| `PolicyInfo` (proxy shape) | **`ProxyPolicyInfo`** (renamed) |
+| `MCPPolicyInfo` (MCP shape) | **`PolicyInfo`** (renamed; matches OpenAPI spec) |
+
+Migration:
+
+- If you imported `PolicyInfo` to read proxy-mode `/api/request` responses, change to `ProxyPolicyInfo` (or use the `PolicyInfoLegacyProxyShape` type alias as a one-major-version shim).
+- If you imported `MCPPolicyInfo` for MCP responses, change to `PolicyInfo`. The `MCPPolicyInfo` name is kept as a `type` alias for one major-version migration window and will be removed in v7.0.0.
+
+This was previously hidden by the naming collision — code reading `response.policyInfo` on `ExecuteQueryResponse` continues to work because the property type is now `ProxyPolicyInfo` with the same fields. The break only affects code that imported the type names by hand.
+
 ### Fixed
 
 - Telemetry path is bounded at `TELEMETRY_TIMEOUT_MS` (3s) total; the `/health` probe and checkpoint POST share a single monotonic deadline instead of stacking independent timeouts. Aligns with python/go/java SDKs.

src/index.ts

@@ -63,6 +63,11 @@ export type {
   DynamicPolicyInfo,
   DynamicPolicyMatch,
   ConnectorHealthStatus,
+  // v6.0.0: `PolicyInfo` exported from connector.ts is the OpenAPI
+  // `PolicyInfo` (MCP shape). The proxy-mode shape is `ProxyPolicyInfo`
+  // (exported below). `MCPPolicyInfo` kept as a type alias for one
+  // major-version migration window.
+  PolicyInfo,
   MCPPolicyInfo,
   ExfiltrationCheckInfo,
   MCPCheckInputOptions,
@@ -121,7 +126,12 @@ export type {
   CircuitBreakerConfigUpdate,
   // Proxy Mode types
   RequestType,
-  PolicyInfo,
+  // v6.0.0: this is the proxy-mode shape, renamed from `PolicyInfo`.
+  // The OpenAPI `PolicyInfo` (MCP shape) is now exported from the
+  // connector group above; `PolicyInfoLegacyProxyShape` is a kept-
+  // for-back-compat alias of `ProxyPolicyInfo` removed in v7.
+  ProxyPolicyInfo,
+  PolicyInfoLegacyProxyShape,
   CodeArtifact,
   HealthStatus,
   PlatformCapability,

src/types/connector.ts

@@ -38,9 +38,15 @@ export interface PolicyMatchInfo {
 
 /**
  * Policy evaluation information included in MCP responses
- * Provides transparency into policy enforcement decisions
+ * (canonical OpenAPI `PolicyInfo` schema). Provides transparency
+ * into policy enforcement decisions returned by `/api/v1/mcp/*`
+ * endpoints.
+ *
+ * Renamed from `MCPPolicyInfo` in v6.0.0 to match the OpenAPI
+ * spec name. The previous proxy-mode `PolicyInfo` (in `proxy.ts`)
+ * is now `ProxyPolicyInfo` so the names align with the spec.
  */
-export interface MCPPolicyInfo {
+export interface PolicyInfo {
   policies_evaluated: number;
   blocked: boolean;
   block_reason?: string;
@@ -53,6 +59,14 @@ export interface MCPPolicyInfo {
   dynamic_policy_info?: DynamicPolicyInfo;
 }
 
+/**
+ * @deprecated Renamed to `PolicyInfo` in v6.0.0 to match the OpenAPI
+ * spec. The previous SDK `PolicyInfo` (proxy-mode shape) is now
+ * `ProxyPolicyInfo`. This alias keeps existing code compiling for
+ * one major version. Removed in v7.0.0.
+ */
+export type MCPPolicyInfo = PolicyInfo;
+
 /**
  * Information about exfiltration limit checks (Issue #966)
  * Helps prevent large-scale data extraction via MCP queries

src/types/proxy.ts

@@ -55,9 +55,16 @@ export interface CodeArtifact {
 }
 
 /**
- * Policy evaluation information from the agent
+ * Proxy-mode policy evaluation summary returned by `/api/request`.
+ *
+ * Renamed from `PolicyInfo` in v6.0.0 — the original name collided
+ * with the OpenAPI `PolicyInfo` schema served by the MCP path
+ * (`/api/v1/mcp/check-input` etc.), which the SDK exposes as
+ * `MCPPolicyInfo`. This type is the proxy-mode shape; the v6
+ * top-level `PolicyInfo` export now refers to the MCP shape (matching
+ * the OpenAPI spec).
  */
-export interface PolicyInfo {
+export interface ProxyPolicyInfo {
   /** List of policies that were evaluated */
   policiesEvaluated: string[];
   /** Static checks that were applied */
@@ -70,6 +77,18 @@ export interface PolicyInfo {
   codeArtifact?: CodeArtifact;
 }
 
+/**
+ * @deprecated Renamed to `ProxyPolicyInfo` in v6.0.0 to resolve a
+ * name collision with the OpenAPI `PolicyInfo` schema (the MCP
+ * shape). For new code, use `ProxyPolicyInfo` from `@axonflow/sdk`
+ * for the proxy-mode shape, or `PolicyInfo` for the MCP shape (the
+ * latter is what was previously exported as `MCPPolicyInfo`).
+ *
+ * This alias keeps existing code compiling for one major version.
+ * Removed in v7.0.0.
+ */
+export type PolicyInfoLegacyProxyShape = ProxyPolicyInfo;
+
 /**
  * Budget enforcement status information (Issue #1082).
  *
@@ -116,8 +135,8 @@ export interface ExecuteQueryResponse {
   blocked: boolean;
   /** Reason for blocking (if blocked) */
   blockReason?: string;
-  /** Policy evaluation info */
-  policyInfo?: PolicyInfo;
+  /** Policy evaluation info (proxy-mode shape) */
+  policyInfo?: ProxyPolicyInfo;
   /** Budget status (Issue #1082) */
   budgetInfo?: BudgetInfo;
   /** Media analysis results (present when media was submitted) */