API Contract Preservation

Always preserve the meaning of public/API-facing inputs and fields across client/server boundaries.

Apply this checklist:

• Round-trip fields: if a request/event accepts a new field, ensure every projection/conversion path carries it through (avoid “write-only” fields).
• Bind scope explicitly: when performing multi-step RPCs, snapshots/tokens should carry the original scope (e.g., account/provider/session) so later calls cannot silently switch context.
• Never change identifier meaning without renaming: if you change what a header/value represents (e.g., task ID → ULID), either keep the original semantic value or rename the header (and document). If both are needed, send both distinctly.
• Enforce spec invariants unconditionally: if the contract says “must not list tools whose visibility excludes model,” do it regardless of optional feature flags.
• Safe URL/version normalization: do not inherit defaults that alter user-supplied semantics (e.g., don’t append/assume a version path for “user-supplied full URLs”). Always normalize trailing slashes/version prefixes consistently.

Example (header semantics):

// Prefer either stable semantics:
headers["X-Task-ID"] = taskId;

// Or make the contract explicit when semantics changed:
headers["X-Task-ID"] = taskId;
headers["X-Task-ULID"] = ulid;

Example (field round-trip):

// Ensure converters/projectors preserve new fields.
// If hub input includes displayPrompt, emit it in the hub envelope,
// and in HubRuntimeHost’s event conversion.