[P1][Contract] Track remaining public client contract gaps

[linfangw]

Purpose

Track only the remaining public client-contract gaps after the current QVeris API and toolkit releases. This issue is an umbrella for contract alignment, not a place to invent server fields or pre-announce run, eval, or replay commands.

Current public baseline — 2026-07-22

Completed in the toolkit:

• Public OpenAPI artifacts, generated types, and contract checks are synchronized.
• Discover exposes why_recommended, capability descriptors, cost class, expected cost, and opt-in routing projections.
• Inspect exposes current parameter schemas, stats, billing_rule, examples, provider metadata, and capability tags.
• Call exposes execution_id, success/error state, compact pre-settlement billing when available, and opt-in summary/field projections.
• Usage history and credits ledger expose final audit and settlement semantics.
• CLI doctor/init, first-call guidance, and explainable-routing recipes are implemented.
• Zero-cost probe schema/quote client support is tracked by [Clients] Add zero-cost tools probe support across CLI, MCP, JavaScript, and Python #259 and implemented in feat: add zero-cost tool probe clients #260.

Remaining contract gaps

The following names are not currently declared as public Call/Discover/Inspect fields and must not be guessed by clients:

• rank_components
• quality_snapshot
• pricing_snapshot
• trace_id
• billing_statement as a distinct response object

Existing public equivalents are deliberately preserved:

• stats and capability metadata cover the currently published quality surface.
• billing_rule, compact billing, usage history, and credits ledger cover published pricing and settlement surfaces.
• execution_outcome belongs to UsageEventItem; it is an audit record, not a projected Call response field.

Separate follow-ups

• /tools/probe: schema and quote are available; coverage and sample currently return an explicit unknown verdict. Client work is [Clients] Add zero-cost tools probe support across CLI, MCP, JavaScript, and Python #259/feat: add zero-cost tool probe clients #260.
• Published discover-to-call accuracy results are tracked by [Product] Published discover→call accuracy benchmark (reproducible evals) #163.
• run, eval, and replay require separate stable public contracts and will receive dedicated issues if those contracts are published.

Start conditions for any remaining item

• The field or endpoint is present in the public OpenAPI or equivalent public contract.
• Request, response, error, and compatibility semantics are specified.
• Deterministic fixtures are available for supported public deployments.
• CLI, MCP, JavaScript, and Python behavior can be aligned without client-side inference.

Acceptance criteria

• Generated types and contract checks match the published contract.
• Clients expose the same field names and error semantics.
• Existing defaults and API-key behavior remain compatible.
• Documentation describes public behavior only and does not depend on unpublished fields.

[linfangw]

Status audit (2026-07-09): most of the checklist has been delivered by intervening work — updating the issue to reflect reality.

Effectively done:

• CLI discover 展示 why_recommended — feat: surface why_recommended and declare capability/cost/provider fields #102 (released in cli 0.7.0), including capability/cost/provider fields
• CLI call 展示 execution_id / billing_statement / outcome — call output shows execution id, pre-settlement billing, remaining credits; usage/ledger reconcile final charges
• MCP tools 与 Python SDK 对齐相同字段 — feat: surface why_recommended and declare capability/cost/provider fields #102 landed the same fields across MCP/js-sdk/python-sdk types (drift guard enforces MCP↔js-sdk)
• recipes explainable routing 示例 — feat(recipes): add explainable-routing recipe and example (#115) #128 (recipes/explainable-routing/ + python example)
• doctor/init 检查区域/API key/合同版本/测试调用 — [P1][CLI] Enhance doctor/init diagnostics: region, API key, contract version, test call #110/feat(cli): enhanced doctor/init diagnostics with actionable hints (#110) #131: doctor now checks Node, key, region, free-probe connectivity, credits, and contract conformance ("Response conforms to contract 2026-05-12"); init is the guided first-call wizard
• 强化 first-call path — npx @qverisai/cli init end-to-end (validated in the 0.7.0 release wave, including driven from Codex CLI)

Remaining, blocked on upstream:

• Data Harness v1 schema sync + contract-check update — needs the stable Quaestio OpenAPI schema
• quality_snapshot / pricing_snapshot / trace_id surfaces — need the server to expose those fields (today: stats + billing_rule cover part of this)
• run / eval / replay evaluation — explicitly gated on backend replay/eval contracts

Suggest keeping this open as the Data-Harness-v1 tracking issue, scoped to the blocked items above.