test: add api contract fixture coverage

pyproject.toml

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

tests/fixtures/README.md

@@ -5,11 +5,22 @@ This directory contains multiple fixture suites with different contracts.
 ## Fixture types
 
 * [`conformance/`](conformance/) — core engine cross-language conformance contract.
+  Includes a small public API presence contract under `conformance/api/`.
 * [`engine-regression/structured/`](engine-regression/structured/) — deterministic per-turn engine regression fixtures (including checkpoint snapshots).
 * [`preprocessor/`](preprocessor/) — preprocessor heuristic and validation fixtures.
 
 `conformance/` and `engine-regression/structured/` both cover engine behavior at different layers; preprocessor fixtures are intentionally separate from the core engine conformance contract.
 
+## API contract fixture
+
+[`conformance/api/public-api-v1.json`](conformance/api/public-api-v1.json) defines a small public API presence contract for the Python 0.6 surface that ports must expose.
+
+Ports may sync this artifact with conformance fixtures.
+
+Ports should check equivalent public exports and methods using language-appropriate names where casing differs.
+
+Behavioral semantics remain covered by conformance and structured fixtures.
+
 ## Step fixtures
 
 For [`conformance/step/`](conformance/step/):

tests/fixtures/conformance/api/public-api-v1.json

@@ -0,0 +1,29 @@
+{
+  "id": "public-api-v1",
+  "kind": "api-contract",
+  "target": "context-compiler-ports",
+  "module": "context_compiler",
+  "required_exports": [
+    "create_engine",
+    "compile_transcript",
+    "get_premise_value",
+    "get_policy_items",
+    "TranscriptMessage",
+    "Transcript",
+    "ApplyResult"
+  ],
+  "engine": {
+    "type": "Engine",
+    "required_members": [
+      "step",
+      "state",
+      "export_json",
+      "import_json",
+      "apply_transcript",
+      "export_checkpoint",
+      "import_checkpoint",
+      "export_checkpoint_json",
+      "import_checkpoint_json"
+    ]
+  }
+}

tests/fixtures/preprocessor/public-api-v1.json

@@ -0,0 +1,18 @@
+{
+  "id": "experimental-preprocessor-public-api-v1",
+  "kind": "api-contract",
+  "module": "experimental.preprocessor",
+  "required_exports": [
+    "PRECOMPILE_OUTCOME_DIRECTIVE",
+    "PRECOMPILE_OUTCOME_NO_DIRECTIVE",
+    "PRECOMPILE_OUTCOME_UNKNOWN",
+    "PRECOMPILER_NO_DIRECTIVE_SENTINEL",
+    "PrecompileResult",
+    "PrecompileOutcome",
+    "parse_preprocessor_output",
+    "parse_precompiler_output",
+    "precompile_heuristic",
+    "render_prompt",
+    "validate_precompiler_output"
+  ]
+}

tests/test_api_contract_fixture.py

@@ -0,0 +1,33 @@
+import json
+from pathlib import Path
+
+import context_compiler
+
+_CONTRACT_PATH = (
+    Path(__file__).resolve().parent / "fixtures" / "conformance" / "api" / "public-api-v1.json"
+)
+
+
+def _load_contract() -> dict[str, object]:
+    return json.loads(_CONTRACT_PATH.read_text(encoding="utf-8"))
+
+
+def test_api_contract_fixture_matches_python_public_surface() -> None:
+    contract = _load_contract()
+
+    assert contract["kind"] == "api-contract"
+    for name in contract["required_exports"]:
+        assert hasattr(context_compiler, name), name
+        assert name in context_compiler.__all__, name
+
+    engine = context_compiler.create_engine()
+    for name in contract["engine"]["required_members"]:
+        assert hasattr(engine, name), name
+
+
+def test_api_contract_fixture_has_unique_entries() -> None:
+    contract = _load_contract()
+    required_exports = contract["required_exports"]
+    assert len(required_exports) == len(set(required_exports))
+    required_members = contract["engine"]["required_members"]
+    assert len(required_members) == len(set(required_members))

tests/test_preprocessor_api_contract_fixture.py

@@ -0,0 +1,29 @@
+import json
+from pathlib import Path
+
+import experimental.preprocessor as preprocessor
+
+_CONTRACT_PATH = (
+    Path(__file__).resolve().parent / "fixtures" / "preprocessor" / "public-api-v1.json"
+)
+
+
+def _load_contract() -> dict[str, object]:
+    return json.loads(_CONTRACT_PATH.read_text(encoding="utf-8"))
+
+
+def test_preprocessor_api_contract_fixture_matches_public_surface() -> None:
+    contract = _load_contract()
+
+    assert contract["kind"] == "api-contract"
+
+    for name in contract["required_exports"]:
+        assert hasattr(preprocessor, name), name
+        assert name in preprocessor.__all__, name
+
+
+def test_preprocessor_api_contract_fixture_has_unique_entries() -> None:
+    contract = _load_contract()
+
+    required_exports = contract["required_exports"]
+    assert len(required_exports) == len(set(required_exports))

tests/test_preprocessor_conformance.py

@@ -9,7 +9,11 @@
 
 
 def _fixture_paths() -> list[Path]:
-    return sorted(_PREPROCESSOR_FIXTURES_DIR.glob("*.json"))
+    return sorted(
+        path
+        for path in _PREPROCESSOR_FIXTURES_DIR.glob("*.json")
+        if not path.name.startswith("public-api-")
+    )
 
 
 def _load_fixture(path: Path) -> dict[str, object]: