Skip to content

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

Merged
saurabhjain1592 merged 1 commit into
mainfrom
feat/v6-policyinfo-rename
Apr 25, 2026
Merged

feat!(types): resolve PolicyInfo / MCPPolicyInfo naming collision (v6.0.0)#186
saurabhjain1592 merged 1 commit into
mainfrom
feat/v6-policyinfo-rename

Conversation

@saurabhjain1592

Copy link
Copy Markdown
Member

Summary

v6.0.0 prep PR. Resolves the only genuinely-breaking change surfaced by the wire-shape contract gate audit: the `PolicyInfo` / `MCPPolicyInfo` naming collision.

This is the second of two PRs from the wire-shape audit:

Background

The TS SDK had two unrelated types using overlapping names:

  • `PolicyInfo` (in `src/types/proxy.ts`): the proxy-mode shape returned by `/api/request` — fields like `policiesEvaluated`, `staticChecks`, `processingTime`, `tenantId`, `codeArtifact`.
  • `MCPPolicyInfo` (in `src/types/connector.ts`): the MCP shape returned by `/api/v1/mcp/*` endpoints — fields like `policies_evaluated`, `blocked`, `block_reason`, `processing_time_ms`, `matched_policies`. This is what the OpenAPI spec calls `PolicyInfo`.

The two types refer to genuinely different concepts; the names just collided historically. The wire-shape gate could never resolve spec `PolicyInfo` to the right SDK type, because the spec name and the SDK name pointed at different shapes.

Change

Swap the names to align with the OpenAPI spec:

In v5.x In v6.0.0
`PolicyInfo` (proxy shape) `ProxyPolicyInfo`
`MCPPolicyInfo` (MCP shape) `PolicyInfo` (matches OpenAPI)

Migration

Code using the proxy-mode shape via the property `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 the type names by hand needs one of:

  • `s/MCPPolicyInfo/PolicyInfo/` for MCP-handling code, OR keep the `MCPPolicyInfo` alias (kept for one major)
  • `s/PolicyInfo/ProxyPolicyInfo/` for proxy-mode code, OR temporarily use `PolicyInfoLegacyProxyShape` (kept for one major)

Both legacy aliases are removed in v7.0.0.

Verification

  • Build: ✅ `tsc` passes (both CJS and ESM targets)
  • Tests: ✅ 859 pass
  • Lint: ✅ clean
  • Wire-shape gate: when this lands, the spec `PolicyInfo` schema resolves cleanly against TS `PolicyInfo` (the renamed MCPPolicyInfo) — drift entry for `PolicyInfo` disappears

Why a separate PR from #185

#185 is a pure additive sweep — every entry is opt-in (new optional fields) or marked `@deprecated` (compile-time compatible). It's safe to ship without a major version bump.

This PR is the only genuinely breaking change from the audit. Putting it in its own PR makes the v6.0.0 manifest reviewable on its own and keeps #185's diff focused on additions.

Out of scope

  • Version bump in package.json — held until release time per current release procedure.
  • Tag / publish — held until release time.

Test plan

  • Build passes
  • All tests pass
  • Lint clean
  • CHANGELOG `[Unreleased]` declares the breaking change with migration instructions
  • CI on this PR is green

….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.
@saurabhjain1592 saurabhjain1592 force-pushed the feat/v6-policyinfo-rename branch from 722fa4f to 59183d7 Compare April 25, 2026 12:57
@saurabhjain1592

Copy link
Copy Markdown
Member Author

Rebased onto current main (post-#185 / post-#187 / post-#188 / post-#189). All 10 CI checks green:

  • Lint, Build, Test (Node 18/20/22), Validate Wire Shape, Validate Version Alignment, CodeQL, Analyze (actions, javascript-typescript)

Holding for merge until the bundled-release story is ready: platform spec PR axonflow-enterprise#1710 lands and the community mirror sync runs, then this PR ships in the same release as the spec corrections (AISystemRegistry.materiality_classification, DynamicPolicyInfo schema). After both land, this SDK gets a small follow-up PR to bump the wire-shape baseline's pinned SHA and regenerate the baseline, which auto-resolves 2 entries (AISystemRegistry, DynamicPolicyInfo).

CHANGELOG [Unreleased] now bundles both threads — the v6 PolicyInfo rename (BREAKING) and the wire-shape sweep entries that already merged via #185.

@saurabhjain1592 saurabhjain1592 merged commit 1ea8715 into main Apr 25, 2026
10 checks passed
@saurabhjain1592 saurabhjain1592 deleted the feat/v6-policyinfo-rename branch April 25, 2026 13:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant