Input, output, and modality contracts¶

These contracts define the data that may cross entrypoint, orchestration, stage, connector, and model boundaries.

Contract status¶

This document is a draft description of the current request, message, serialization, modality, accumulation, and output types. It does not assign semantic error ownership to the wire schema.

Ownership boundary¶

This document owns request identity, prompt/input types, modality keys and metadata, queue and wire message schemas, serialization, output types, accumulation, completion semantics, and compatibility shims.

It does not own route-specific validation or rendering, model-specific interpretation, connector transport mechanics, scheduling policy, or semantic error classification. The ErrorMessage schema belongs here; the meaning and public rendering of its error fields belong to error_contracts.md.

Candidate invariants¶

These identifiers are proposals while the document is draft.

IO-INV-001: Boundary data has an explicit modality¶

Rule: Data crossing a module or stage boundary MUST identify its modality and use the corresponding validated contract.

IO-INV-100: Request identity is stable¶

Rule: Request identity MUST be preserved across conversions, stages, streaming updates, cancellation, and errors.

IO-INV-101: Completion is explicit¶

Rule: Producers MUST distinguish partial updates from the terminal update for every output modality.

IO-INV-300: Internal objects do not leak into public protocols¶

Rule: Entrypoints MUST explicitly translate internal output objects into public response types.

Invariant namespace¶

IO-INV reserves 001-099 for schema ownership and dependency direction, 100-199 for identity, modality, accumulation, ordering, and completion, 200-299 for serialization failure and payload cleanup, and 300-399 for upstream extension, deprecation, and compatibility. Numbers become append-only after normative promotion.

Safe-change guide¶

Test construction, validation, serialization, round trips, streaming, accumulation, completion, optional fields, unknown fields, and compatibility at every affected producer-consumer boundary.

Promotion gate¶

• Add explicit CODEOWNERS for the primary I/O paths or confirm that fallback ownership is intentional.
• Document the compatibility window for deprecated vllm_omni.engine I/O-related imports.
• Verify wire round trips and rejection of unknown or incompatible schema fields.
• Define payload-versus-metadata rules and completion semantics for streaming and batched outputs.
• Obtain approval from a technical owner and independent AR, diffusion, connector, entrypoint, and validation reviewers as applicable.