i/Aether
1
0
Fork 0
mirror of https://github.com/fawney19/Aether.git synced 2026-09-12 14:10:19 +08:00
Code Issues Packages Projects Releases Wiki Activity

fix: preserve provider schema drift safely

Browse Source
This commit is contained in:
elky
2026-06-03 22:29:24 +08:00
parent da5624c98e
commit 465476985b
7 changed files with 93 additions and 7 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/api/format-passthrough-contract.md
+4 -1
View File
@@ -20,6 +20,8 @@ Important limitation:
- The current transport helper receives `body_json: &serde_json::Value`, not raw request bytes. It therefore guarantees no canonical conversion and JSON value preservation at this layer, but it cannot preserve original whitespace or object key order by itself.
- True byte-level passthrough for requests with no transport edits requires a higher-level raw-body path that can forward the original bytes directly. Until that raw-body plumbing exists, tests should assert "conversion module not called" and JSON value equivalence for this helper, not byte-for-byte serialization equivalence.
Provider schema drift does not change this rule. If OpenAI, Claude, or Gemini add a new field, same-format runtime routing must still forward it as part of the original provider body. The schema inventory and field coverage matrix are audit aids, not the runtime allowlist for same-format traffic.
## Canonical Same-Format Roundtrip
Canonical same-format roundtrip is only a test/audit mode:
@@ -33,6 +35,7 @@ Required behavior:
- JSON-normalized equality, ignoring object field order and whitespace.
- Field values, array order, unknown fields, extension namespaces, and unknown enum strings must be preserved.
- This path may parse and emit; it is not the runtime path.
- Unknown provider fields are carried in provider extension namespaces and replayed when emitting the same provider format.
## Cross-Format Conversion
@@ -49,6 +52,7 @@ Required behavior:
- Preserve source fields only when the target has an equivalent field or documented extension passthrough.
- Fail closed with `FormatError::LossyConversionBlocked`, `FormatError::UnsupportedField`, `FormatError::InvalidEnumValue`, or `FormatError::InvalidTargetField` when no lossless mapping exists.
- Do not use `None` or silent omission to represent conversion failure.
- Newly added provider fields follow the same rule as other unknown fields: preserve same-format, fail closed cross-format. A code change is required only when Aether intentionally supports a new cross-format semantic mapping.
## Pure Conversion Interface
@@ -79,4 +83,3 @@ Current pure entrypoints:
- `convert_response_pure`
`convert_request` and `convert_response` remain legacy wrappers for existing callers that still need mapped model/report-context behavior during migration.