ai-contract-platform/yuqei-contract-platform/packages/contract-openapi

Contract OpenAPI

This package publishes the V2 contract platform HTTP contract. Runtime structure is reconciled against an isolated service export; manually maintained explanations and explicit schema refinements are retained.

Primary file:

openapi.yaml

Rules:

• Contract Web should consume this contract through generated or typed clients.
• Contract API implementation must match this contract.
• Contract API calls AI Platform only through SDK/OpenAPI clients, not direct provider adapters.

The 2026-09-09 local synchronization contains 282 paths, 328 operations and 450 component schemas: 440 runtime schemas plus 10 Documented_* components supporting seven explicit refinements of unconstrained runtime schemas. These refinements are reported separately from exact structural equality and fingerprinted under x-yuqei-sync.

The previous POST /api/v1/auth/login publication has no matching registered runtime route. Its definition remains in x-yuqei-legacy-contract, outside active paths; the appendix does not assert that a login endpoint or flow is available. Documentation from replaced fields remains under x-yuqei-unmatched-documentation. Historical nullable syntax is normalized to OpenAPI 3.1 null unions.

No generated SDK or consumer was replaced in this batch. Runtime operationId changes are recorded for later client migration. See synchronization rules and check commands and before/after evidence. Re-export from current source before claiming current-source consistency; a historical runtime JSON is not proof for newer source.

TP06.10 increment: adds the current-tenant GET /api/v1/admin/product-analytics/scene-quality, privacy-minimized template recommendation events, and GET /api/v1/identity/platform-access. Apply additive migration 20260909_0078 before running the new analytics ORM/event writer. Prompt management in Contract Web checks the live platform permission on every BFF request; this does not extend authentication of direct AI service calls. The new quality view distinguishes candidate origin, withdrawal, reversal, missing information, and failures; its rates are not legal acceptance or pure AI success rates. Historical synchronization counts above predate this increment.

TP06.12 increment: optional DraftingCreateRequest.journey_id binds only an existing same-tenant/user/template draft_guide_started receipt. Workspace journey_timing records server-observed preview, required-input completion and candidate-content delivery checks; existing workspaces stay unmeasured. GET /api/v1/admin/product-analytics/drafting-stage-timing is a current-tenant platform-admin aggregate, with all start journeys in the denominator, explicit missing observations and a separate historical failure-journey count. This is not browser-visible time, legal approval, signing readiness or a release acceptance metric. No database migration is required for these additive workspace JSON fields. Run yuqei-infra/scripts/tp06-12/sync-journey-openapi.py --check with the repository Python paths to verify these scoped fragments; it does not certify all earlier OpenAPI refinements.

TP06.24.1/TP06.24.2 increments add candidate semantic-review creation and action routes. The action route retains the runtime {action} path parameter; the current implementation accepts only refresh, cancel, retry, and repair. Its request binds the expected workspace revision and candidate body hash. It does not expose a separate automatic-repair endpoint. DraftingCandidateRequest.auto_repair defaults to false for omitted API input; the ordinary drafting UI presents an initially checked, editable option and discloses the extra tasks before submission. When enabled, the coordinator may create at most one repair generation and records its parent/review linkage and continuation error without overwriting the parent. The workspace response includes the frozen request, attempt history, deterministic assessment, and server-validated execution evidence. A passed model opinion alone is not legal approval or adoption authorization. Run yuqei-infra/scripts/tp06-24-1/sync-semantic-review-contract-openapi.py without --update to check the isolated memory/no-database runtime fragment. When a reviewed candidate is adopted, ContractVersion.drafting_review_reference may expose only the review, job and audit IDs plus request/output/assessment and receipt hashes. Historical versions return null; the API does not expose the rest of internal version metadata through this field.