Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
fix(openai): harden strict schema normalization
AkitaOnRails1e7f10d0f881
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 8e8584fa..4bbc7374 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -9,6 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0### Fixed- Filesystem watcher now reindexes a project when backends report only aparent-directory event, improving external editor capture on macOS/FSEvents.+- OpenAI strict structured-output schema normalization now strips generated+ `$ref` annotation siblings and rewrites generated enum `oneOf` schemas to+ `anyOf`, unblocking `memory_consolidate multi_page=true` on OpenAI models.## [0.2.0] - 2026-05-26### Addeddiff --git a/crates/ai-memory-llm/src/openai.rs b/crates/ai-memory-llm/src/openai.rsindex 0b180ce5..8b4048a6 100644--- a/crates/ai-memory-llm/src/openai.rs+++ b/crates/ai-memory-llm/src/openai.rs@@ -346,29 +346,24 @@ impl OpenAiProvider {fn enforce_strict_object_schemas(value: &mut serde_json::Value) {match value {serde_json::Value::Object(map) => {- // OpenAI's structured-output validator rejects any sibling- // keyword next to `$ref` with a 400 (per JSON Schema 2020-12- // §8.2.3.1, $ref siblings are ignored during validation —- // OpenAI hardens that into a hard error). schemars 1.x emits- // a field-level `description` next to `$ref` for every- // doc-commented field typed as an external enum (e.g.- // `tier: Tier` on `ConsolidatedPageUpdate`); without this- // strip, `memory_consolidate multi_page=true` 400s on every- // call. Dropping the siblings is semantically a no-op —- // only the documentation-only annotation is lost; the- // type's own description on the referenced `$defs` entry- // is what reaches the model.+ // OpenAI's structured-output subset rejects any sibling+ // keyword next to `$ref` with a 400. schemars 1.x emits a+ // field-level `description` next to `$ref` for doc-commented+ // fields typed as external enums (e.g. `tier: Tier` on+ // `ConsolidatedPageUpdate`); without this strip,+ // `memory_consolidate multi_page=true` fails before the model+ // runs. In our generated schemas those siblings are+ // annotations, not validation constraints, so the referenced+ // definition remains the source of truth.if map.contains_key("$ref") {map.retain(|k, _| k == "$ref");return;}// OpenAI strict mode rejects `oneOf` outright but accepts- // `anyOf`. schemars 1.x emits `oneOf` for every Rust enum- // with tagged variants (closed sets where exactly one- // branch matches), e.g. `Tier` and `PageKind` under `$defs`- // in `ConsolidatedBatch`. For non-overlapping branches the- // rewrite is semantically lossless and unblocks every- // structured-output call that touches an enum.+ // `anyOf`. schemars 1.x emits `oneOf` for closed Rust enums+ // such as `Tier` and `PageKind` under `$defs` in+ // `ConsolidatedBatch`; their const branches are disjoint, so+ // the rewrite preserves the generated schema's accepted set.if let Some(one_of) = map.remove("oneOf") {map.insert("anyOf".to_string(), one_of);}@@ -466,7 +461,9 @@ mod tests {model_requires_max_completion_tokens, normalize_openai_base,};use crate::types::{ChatMessage, ChatRequest, Role};+ use schemars::JsonSchema;use secrecy::SecretString;+ use serde::{Deserialize, Serialize};use serde_json::json;fn provider_for(model: &str) -> OpenAiProvider {@@ -574,11 +571,8 @@ mod tests {// doc-commented field is typed as an external enum (e.g.// `tier: Tier` in `ConsolidatedPageUpdate`). Without this// strip, `memory_consolidate multi_page=true` 400s on every- // call against gpt-4o-mini. JSON Schema 2020-12 §8.2.3.1 says- // siblings of `$ref` are ignored during validation, so- // dropping them is semantically a no-op — only the- // documentation-only field-level description is lost (the- // type's own description on the referenced definition stays).+ // call against gpt-4o-mini. In our generated schemas those+ // siblings are annotations, not validation constraints.let mut schema = json!({"type": "object","properties": {@@ -634,11 +628,37 @@ mod tests {assert_eq!(any_of.as_array().unwrap().len(), 2);}+ #[test]+ fn enforce_strict_normalizes_schemars_enum_refs() {+ #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]+ struct Fixture {+ /// Doc-commented enum field, matching the schemars shape that+ /// triggered OpenAI's `$ref` sibling rejection.+ tier: FixtureTier,+ /// Array of the same enum, covering `$ref` under `items`.+ tiers: Vec<FixtureTier>,+ }++ #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]+ #[serde(rename_all = "snake_case")]+ enum FixtureTier {+ Working,+ Episodic,+ }++ let mut schema = serde_json::to_value(schemars::schema_for!(Fixture)).unwrap();+ enforce_strict_object_schemas(&mut schema);++ assert_no_one_of(&schema);+ assert_no_ref_siblings(&schema);+ assert_eq!(schema["additionalProperties"], json!(false));+ }+#[test]fn enforce_strict_strips_ref_siblings_inside_array_items() {- // The same JSON-Schema-2020-12 rule applies anywhere $ref- // appears, not just on direct object properties — schemars- // emits it inside `items` for `Vec<EnumType>` too.+ // OpenAI applies the same `$ref` sibling restriction anywhere a+ // ref appears, not just on direct object properties. schemars+ // emits this shape inside `items` for `Vec<EnumType>` too.let mut schema = json!({"type": "array","items": {@@ -652,6 +672,42 @@ mod tests {assert!(items.get("description").is_none());}+ fn assert_no_one_of(value: &serde_json::Value) {+ match value {+ serde_json::Value::Object(map) => {+ assert!(map.get("oneOf").is_none(), "oneOf remains in {value}");+ for child in map.values() {+ assert_no_one_of(child);+ }+ }+ serde_json::Value::Array(items) => {+ for child in items {+ assert_no_one_of(child);+ }+ }+ _ => {}+ }+ }++ fn assert_no_ref_siblings(value: &serde_json::Value) {+ match value {+ serde_json::Value::Object(map) => {+ if map.contains_key("$ref") {+ assert_eq!(map.len(), 1, "$ref has siblings in {value}");+ }+ for child in map.values() {+ assert_no_ref_siblings(child);+ }+ }+ serde_json::Value::Array(items) => {+ for child in items {+ assert_no_ref_siblings(child);+ }+ }+ _ => {}+ }+ }+#[test]fn enforce_strict_overwrites_caller_additional_properties_true() {// OpenAI strict mode requires `additionalProperties: false` ondiff --git a/docs/deploy.md b/docs/deploy.mdindex 3fd8cda7..12b5b708 100644--- a/docs/deploy.md+++ b/docs/deploy.md@@ -152,9 +152,11 @@ alternatives:> reasoning off.ai-memory's consolidator uses OpenAI's `json_schema` strict mode for-structured output. Most modern models honour this, but if you switch-to a niche local model, run a quick `ai-memory llm-test` (with a-structured prompt) before trusting it.+structured output. The OpenAI provider normalizes schemars output into+OpenAI's supported subset (`additionalProperties: false`, complete+`required`, generated enum `anyOf`, and plain `$ref` nodes). Most modern+models honour this, but if you switch to a niche local model, run a quick+`ai-memory llm-test` (with a structured prompt) before trusting it.## Backups