test(sdk): add cross-language SDK parity CI and fix MatchResult nullables

[AbhilashG12]

Opening this as a draft/proof-of-concept to accompany the discussion in Discord. I wanted to see if an AST-based approach would cleanly map to our openapi.yaml without needing to spin up the sidecar or block current workflows. Feel free to review the architecture when you have a moment!

---

Description

This PR introduces a strict CI guardrail to prevent cross-language SDK drift, directly addressing the root cause of recent type mismatches (like #1057 and #1418).

Instead of playing whack-a-mole with nullable/required field mismatches, this adds an automated validator that enforces the openapi.yaml schema as the absolute source of truth.

Architecture

• OpenAPI Source: Extracts the source of truth directly from openapi.yaml.
• TypeScript Native: Parses TS interfaces natively via the typescript compiler API.
• Python Native: Parses Python classes via the native ast module (no imports or sidecar required).
• CI Enforcement: Automatically fails CI if the SDK types drift from the schema contract.

Fixes Included

On the first run, the parity engine caught existing schema drift in the TypeScript SDK. This PR includes the fixes for those models to ensure CI passes immediately:

• Fixed MatchResult (updated reasoning, bestBid, bestAsk to allow null).
• Fixed PriceComparison (updated reasoning, bestBid, bestAsk to allow null).

Note: Existing models not yet unified in the TS SDK are safely logged as warnings so this check does not block current development while we enforce the standard moving forward.

[realfishsam]

PR Review: FAIL

What This Does

Adds a GitHub Actions SDK parity check plus a local npm run check:sdk-parity validator, and adjusts TypeScript router match result nullable fields to align with OpenAPI/Python. This matters because it is intended to prevent Python/TypeScript/OpenAPI schema drift in CI.

Blast Radius

GitHub Actions, root package scripts/dependencies, package-lock metadata, new validation scripts, and TypeScript MatchResult / PriceComparison model typings.

Consumer Verification

Before (base branch):
No root check:sdk-parity script exists, and the TypeScript MatchResult / PriceComparison fields reasoning, bestBid, and bestAsk were optional but not nullable.

After (PR branch):
A fully installed workspace can run the validator:

npm run check:sdk-parity
✅ SDK Parity Passed! OpenAPI schema aligns with generated code.

However, a clean metadata check shows the PR did not commit the required root lockfile updates. Running:

npm install --package-lock-only --ignore-scripts

produces a non-empty package-lock.json diff adding the new root dev dependencies (@types/node, yaml) and associated resolved packages. On the pre-existing lockfile, the new root script also failed in this checkout with:

> check:sdk-parity
> tsx scripts/validate-sdk-parity.ts
sh: 1: tsx: not found

because the root script depends on an executable not available from the committed root package metadata/lock state.

Test Results

• Build: N/A (CI/tooling-only PR)
• Unit tests: N/A
• Server starts: N/A
• E2E smoke: FAIL for the new CI/tooling consumer path under clean lockfile metadata; PASS only after local npm install mutates package-lock.json.

Findings

1. package.json:18 / package-lock.json -- the PR adds root script/dependencies but does not commit the corresponding root lockfile changes. npm install --package-lock-only --ignore-scripts modifies package-lock.json to add the new root dependency metadata. That makes the package/build-tooling change non-durable and can make CI or clean installs run with stale metadata.
2. package.json:18 -- check:sdk-parity invokes tsx, but tsx is not declared as a root devDependency. In this checkout, before the full install rewrote local node_modules, npm run check:sdk-parity failed with sh: 1: tsx: not found. Either declare tsx at the root or invoke a workspace-owned binary explicitly.

PMXT Pipeline Check

• Field propagation (3-layer): PASS for the specific nullable TypeScript model edits checked by the validator.
• OpenAPI sync: N/A
• Financial precision: N/A
• Type safety: OK for the nullable model changes.
• Auth safety: N/A

Semver Impact

patch -- test/CI hardening plus type nullability corrections.

Risk

The parity validator itself currently ignores missing TS/Python models with warnings, so it is useful for nullable-field drift but not a complete SDK-surface parity gate. The blocking issue is the stale/incomplete root dependency metadata.

[AbhilashG12]

Fixes applied:

Added tsx explicitly to the root devDependencies.

Ran a clean root install to sync and commit the updated package-lock.json metadata for the new dependencies (tsx, yaml, @types/node).

Fresh checkouts should now resolve all binaries and pass npm run check:sdk-parity cleanly. Let me know if you need any other adjustments to the validator!