test: add portable serialization and checkpoint fixtures

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "context-compiler"
-version = "0.6.17"
+version = "0.6.18"
 description = "Deterministic conversational state engine for LLM applications."
 readme = "README.md"
 requires-python = ">=3.11"

tests/fixtures/README.md

@@ -57,9 +57,27 @@ For conformance transcript fixtures:
 * If `prompt_to_user` is a string → exact match
 * If `prompt_to_user` is `null` → any non-empty string is accepted
 
+## State JSON fixtures
+
+For [`conformance/state-json/`](conformance/state-json/):
+
+Portable serialization contract coverage for `engine.export_json()` and
+`engine.import_json(...)`, including canonical export payload shape and
+deterministic validation/error boundaries.
+
+## Checkpoint fixtures
+
+For [`conformance/checkpoint/`](conformance/checkpoint/):
+
+Portable checkpoint import contract coverage for
+`engine.import_checkpoint(...)`, including deterministic validation/error
+boundaries, atomic failure behavior, and pending-clarification clearing semantics.
+
 ## Source of truth
 
 Fixtures reflect current Python behavior and tests.
+Property/fuzz invariants remain Python-local tests and are not part of the
+portable fixture contract.
 
 ## Engine regression fixtures
 
@@ -83,6 +101,12 @@ These fixtures cover preprocessor behavior (heuristic classification plus output
 
 They are exercised by [`tests/test_preprocessor_conformance.py`](../test_preprocessor_conformance.py), including deterministic replay and validation-boundary checks (only validated directive output may pass through).
 
+Portable fixture scope:
+- deterministic heuristic and validator input/output contracts intended for cross-language parity
+
+Python-local test scope:
+- property/fuzz invariants and filesystem/template behaviors (for example `render_prompt` file-loading behavior) remain in Python unit/property tests and are not portable fixture requirements.
+
 They validate:
 
 * heuristic classification determinism

tests/fixtures/conformance/checkpoint/001_import_checkpoint_non_object_rejected.json

@@ -0,0 +1,24 @@
+{
+  "id": "checkpoint_import_checkpoint_non_object_rejected",
+  "kind": "checkpoint",
+  "initial_state": {
+    "premise": null,
+    "policies": {},
+    "version": 2
+  },
+  "action": {
+    "fn": "import_checkpoint",
+    "payload": []
+  },
+  "expected": {
+    "error": {
+      "type": "ValueError",
+      "message_contains": "Invalid checkpoint payload"
+    },
+    "state": {
+      "premise": null,
+      "policies": {},
+      "version": 2
+    }
+  }
+}

tests/fixtures/conformance/checkpoint/002_import_checkpoint_unsupported_version_rejected.json

@@ -0,0 +1,32 @@
+{
+  "id": "checkpoint_import_checkpoint_unsupported_version_rejected",
+  "kind": "checkpoint",
+  "initial_state": {
+    "premise": null,
+    "policies": {},
+    "version": 2
+  },
+  "action": {
+    "fn": "import_checkpoint",
+    "payload": {
+      "checkpoint_version": 2,
+      "authoritative_state": {
+        "premise": null,
+        "policies": {},
+        "version": 2
+      },
+      "pending": null
+    }
+  },
+  "expected": {
+    "error": {
+      "type": "ValueError",
+      "message_contains": "Unsupported checkpoint version"
+    },
+    "state": {
+      "premise": null,
+      "policies": {},
+      "version": 2
+    }
+  }
+}

tests/fixtures/conformance/checkpoint/003_import_checkpoint_invalid_pending_shape_rejected.json

@@ -0,0 +1,34 @@
+{
+  "id": "checkpoint_import_checkpoint_invalid_pending_shape_rejected",
+  "kind": "checkpoint",
+  "initial_state": {
+    "premise": null,
+    "policies": {},
+    "version": 2
+  },
+  "action": {
+    "fn": "import_checkpoint",
+    "payload": {
+      "checkpoint_version": 1,
+      "authoritative_state": {
+        "premise": null,
+        "policies": {},
+        "version": 2
+      },
+      "pending": {
+        "kind": "replacement"
+      }
+    }
+  },
+  "expected": {
+    "error": {
+      "type": "ValueError",
+      "message_contains": "Invalid checkpoint payload"
+    },
+    "state": {
+      "premise": null,
+      "policies": {},
+      "version": 2
+    }
+  }
+}

tests/fixtures/conformance/checkpoint/004_import_checkpoint_invalid_replacement_shape_rejected.json

@@ -0,0 +1,40 @@
+{
+  "id": "checkpoint_import_checkpoint_invalid_replacement_shape_rejected",
+  "kind": "checkpoint",
+  "initial_state": {
+    "premise": null,
+    "policies": {},
+    "version": 2
+  },
+  "action": {
+    "fn": "import_checkpoint",
+    "payload": {
+      "checkpoint_version": 1,
+      "authoritative_state": {
+        "premise": null,
+        "policies": {},
+        "version": 2
+      },
+      "pending": {
+        "kind": "replacement",
+        "replacement": {
+          "kind": "use_only",
+          "new_item": "kubectl",
+          "old_item": "docker"
+        },
+        "prompt_to_user": "confirm?"
+      }
+    }
+  },
+  "expected": {
+    "error": {
+      "type": "ValueError",
+      "message_contains": "Invalid checkpoint payload"
+    },
+    "state": {
+      "premise": null,
+      "policies": {},
+      "version": 2
+    }
+  }
+}

tests/fixtures/conformance/checkpoint/005_import_checkpoint_invalid_authoritative_state_rejected_atomically.json

@@ -0,0 +1,48 @@
+{
+  "id": "checkpoint_import_checkpoint_invalid_authoritative_state_rejected_atomically",
+  "kind": "checkpoint",
+  "initial_state": {
+    "premise": null,
+    "policies": {},
+    "version": 2
+  },
+  "prelude": [
+    "use kubectl instead of docker"
+  ],
+  "action": {
+    "fn": "import_checkpoint",
+    "payload": {
+      "checkpoint_version": 1,
+      "authoritative_state": {
+        "premise": null,
+        "policies": [],
+        "version": 2
+      },
+      "pending": null
+    }
+  },
+  "expected": {
+    "error": {
+      "type": "ValueError",
+      "message_contains": "Invalid state payload"
+    },
+    "state": {
+      "premise": null,
+      "policies": {},
+      "version": 2
+    },
+    "followup": {
+      "input": "maybe",
+      "decision": {
+        "kind": "clarify",
+        "state": null,
+        "prompt_to_user": "Did you mean to use \"kubectl\" instead?"
+      },
+      "state": {
+        "premise": null,
+        "policies": {},
+        "version": 2
+      }
+    }
+  }
+}

tests/fixtures/conformance/checkpoint/006_import_checkpoint_pending_null_clears_existing_pending.json

@@ -0,0 +1,50 @@
+{
+  "id": "checkpoint_import_checkpoint_pending_null_clears_existing_pending",
+  "kind": "checkpoint",
+  "initial_state": {
+    "premise": null,
+    "policies": {},
+    "version": 2
+  },
+  "prelude": [
+    "use kubectl instead of docker"
+  ],
+  "action": {
+    "fn": "import_checkpoint",
+    "payload": {
+      "checkpoint_version": 1,
+      "authoritative_state": {
+        "premise": "baseline",
+        "policies": {
+          "pytest": "use"
+        },
+        "version": 2
+      },
+      "pending": null
+    }
+  },
+  "expected": {
+    "state": {
+      "premise": "baseline",
+      "policies": {
+        "pytest": "use"
+      },
+      "version": 2
+    },
+    "followup": {
+      "input": "yes",
+      "decision": {
+        "kind": "passthrough",
+        "state": null,
+        "prompt_to_user": null
+      },
+      "state": {
+        "premise": "baseline",
+        "policies": {
+          "pytest": "use"
+        },
+        "version": 2
+      }
+    }
+  }
+}

tests/fixtures/conformance/checkpoint/007_import_checkpoint_pending_absent_clears_existing_pending.json

@@ -0,0 +1,49 @@
+{
+  "id": "checkpoint_import_checkpoint_pending_absent_clears_existing_pending",
+  "kind": "checkpoint",
+  "initial_state": {
+    "premise": null,
+    "policies": {},
+    "version": 2
+  },
+  "prelude": [
+    "use kubectl instead of docker"
+  ],
+  "action": {
+    "fn": "import_checkpoint",
+    "payload": {
+      "checkpoint_version": 1,
+      "authoritative_state": {
+        "premise": "baseline",
+        "policies": {
+          "pytest": "use"
+        },
+        "version": 2
+      }
+    }
+  },
+  "expected": {
+    "state": {
+      "premise": "baseline",
+      "policies": {
+        "pytest": "use"
+      },
+      "version": 2
+    },
+    "followup": {
+      "input": "yes",
+      "decision": {
+        "kind": "passthrough",
+        "state": null,
+        "prompt_to_user": null
+      },
+      "state": {
+        "premise": "baseline",
+        "policies": {
+          "pytest": "use"
+        },
+        "version": 2
+      }
+    }
+  }
+}

tests/fixtures/conformance/state-json/001_export_json_canonical_sorted_compact.json

@@ -0,0 +1,28 @@
+{
+  "id": "state_json_export_json_canonical_sorted_compact",
+  "kind": "state_json",
+  "initial_state": {
+    "premise": null,
+    "policies": {},
+    "version": 2
+  },
+  "prelude": [
+    "set premise concise",
+    "use zeta",
+    "use alpha"
+  ],
+  "action": {
+    "fn": "export_json"
+  },
+  "expected": {
+    "payload": "{\"policies\":{\"alpha\":\"use\",\"zeta\":\"use\"},\"premise\":\"concise\",\"version\":2}",
+    "state": {
+      "premise": "concise",
+      "policies": {
+        "alpha": "use",
+        "zeta": "use"
+      },
+      "version": 2
+    }
+  }
+}

tests/fixtures/conformance/state-json/002_import_json_invalid_json_rejected.json

@@ -0,0 +1,24 @@
+{
+  "id": "state_json_import_json_invalid_json_rejected",
+  "kind": "state_json",
+  "initial_state": {
+    "premise": null,
+    "policies": {},
+    "version": 2
+  },
+  "action": {
+    "fn": "import_json",
+    "payload": "{"
+  },
+  "expected": {
+    "error": {
+      "type": "ValueError",
+      "message_contains": "Invalid JSON payload"
+    },
+    "state": {
+      "premise": null,
+      "policies": {},
+      "version": 2
+    }
+  }
+}