refactor: separate subsystem API boundaries

README.md

@@ -276,14 +276,15 @@ Common API entry points:
 - decision helpers: `is_clarify(...)`, `is_update(...)`, `is_passthrough(...)`,
   `get_clarify_prompt(...)`, `get_decision_state(...)`
 - state transport: `engine.export_json(...)`, `engine.import_json(...)`
-- controller APIs: `preview(...)`, `step(...)`, `state_diff(...)`
+- controller API: `step(...)`
+- audit APIs: `preview(...)`, `state_diff(...)`
 
-### Controller API (Reusable Outside REPL)
+### Controller And Audit APIs (Reusable Outside REPL)
 
-- `preview(engine, user_input)` performs a deterministic dry run and restores
-  live engine state afterward
 - `step(engine, user_input)` returns a reusable result envelope around one
   engine turn
+- `preview(engine, user_input)` performs a deterministic dry run and restores
+  live engine state afterward
 - `state_diff(state_before, state_after)` summarizes structural state changes
 
 For examples and helper accessors such as `get_step_decision(...)`,

docs/api-reference.md

@@ -189,10 +189,11 @@ Conceptual boundary:
 - imported policy keys are normalized during `import_json(...)`
 - if a policy key normalizes to `""`, the payload is invalid and is rejected
 
-## Controller APIs
+## Controller And Audit APIs
 
-These controller APIs are public package exports and can be used directly in
-host code, not only through the REPL.
+The `step(...)` convenience wrapper remains part of the root host-facing API.
+
+Preview and structural diff helpers live under `context_compiler.audit`.
 
 ### `step(engine, user_input)`
 
@@ -229,8 +230,8 @@ state snapshots.
 Typical use:
 
 ```python
-from context_compiler import (
-    create_engine,
+from context_compiler import create_engine
+from context_compiler.audit import (
     diff_has_changes,
     get_preview_state_after,
     preview,
@@ -246,7 +247,7 @@ if diff_has_changes(diff):
     show_preview(diff)
 ```
 
-Controller helper functions:
+Audit helper functions:
 
 - `get_step_decision(step_result)`
 - `get_step_state(step_result)`
@@ -255,7 +256,7 @@ Controller helper functions:
 - `preview_would_mutate(preview_result)`
 - `diff_has_changes(diff)`
 
-For controller result-envelope details, see the controller conformance fixture
+For audit result-envelope details, see the fixture
 documentation in [tests/fixtures/README.md](../tests/fixtures/README.md).
 
 ## Public Constants
@@ -281,8 +282,6 @@ Public result and data object names exported at package root include:
 - `Decision`
 - `State`
 - `StepResult`
-- `PreviewResult`
-- `StructuralDiff`
 - `Engine`
 
 These names are part of the public package surface. For the exact portable API

examples/08_controller_preview_diff.py

@@ -4,14 +4,16 @@
 
 from context_compiler import (
     create_engine,
-    diff_has_changes,
-    get_preview_decision,
     get_step_decision,
     get_step_state,
+    step,
+)
+from context_compiler.audit import (
+    diff_has_changes,
+    get_preview_decision,
     preview,
     preview_would_mutate,
     state_diff,
-    step,
 )
 
 

pyproject.toml

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

src/context_compiler/__init__.py

@@ -8,17 +8,9 @@
     POLICY_USE,
 )
 from .controller import (
-    PreviewResult,
     StepResult,
-    StructuralDiff,
-    diff_has_changes,
-    get_preview_decision,
-    get_preview_state_after,
     get_step_decision,
     get_step_state,
-    preview,
-    preview_would_mutate,
-    state_diff,
     step,
 )
 from .decision_helpers import (
@@ -36,7 +28,6 @@
     State,
     create_engine,
 )
-from .grammar import DirectiveKind, is_canonical_directive, render_directive, validate_directive
 
 __version__ = version("context-compiler")
 
@@ -46,31 +37,19 @@
     "DECISION_CLARIFY",
     "DECISION_PASSTHROUGH",
     "DECISION_UPDATE",
-    "DirectiveKind",
     "Engine",
     "POLICY_PROHIBIT",
     "POLICY_USE",
     "PolicyValue",
-    "PreviewResult",
     "State",
     "StepResult",
-    "StructuralDiff",
-    "diff_has_changes",
     "create_engine",
     "get_clarify_prompt",
     "get_decision_state",
-    "get_preview_decision",
-    "get_preview_state_after",
     "get_step_decision",
     "get_step_state",
-    "is_canonical_directive",
     "is_clarify",
     "is_passthrough",
     "is_update",
-    "preview",
-    "preview_would_mutate",
-    "render_directive",
-    "state_diff",
     "step",
-    "validate_directive",
 ]

src/context_compiler/audit.py

@@ -0,0 +1,23 @@
+"""Public auditability helpers layered above the authoritative engine."""
+
+from .controller import (
+    PreviewResult,
+    StructuralDiff,
+    diff_has_changes,
+    get_preview_decision,
+    get_preview_state_after,
+    preview,
+    preview_would_mutate,
+    state_diff,
+)
+
+__all__ = [
+    "PreviewResult",
+    "StructuralDiff",
+    "diff_has_changes",
+    "get_preview_decision",
+    "get_preview_state_after",
+    "preview",
+    "preview_would_mutate",
+    "state_diff",
+]

tests/fixtures/README.md

@@ -13,9 +13,11 @@ surface, rather than as Python-only test inputs.
 * [`engine-regression/structured/`](engine-regression/structured/) — deterministic per-turn engine regression fixtures using authoritative state snapshots.
 `conformance/` and `engine-regression/structured/` both cover engine behavior at different layers.
 
-## API contract fixture
+## API contract fixtures
 
-[`conformance/api/public-api-v1.json`](conformance/api/public-api-v1.json) defines the current portable core public API contract for Python and ports.
+[`conformance/api/public-api-v1.json`](conformance/api/public-api-v1.json) defines the current portable core root public API contract for Python and ports.
+
+[`conformance/api/public-audit-v1.json`](conformance/api/public-audit-v1.json) defines the current portable audit-module public API contract for Python and ports.
 
 Ports may sync this artifact with conformance fixtures.
 
@@ -32,10 +34,13 @@ Ports should check equivalent public exports, members, and signatures using lang
 
 Behavioral semantics remain covered by conformance and structured fixtures.
 
-The API contract includes the public controller helper accessors:
+The root API contract includes the public step helper accessors:
 
 * `get_step_decision`
 * `get_step_state`
+
+The audit API contract includes:
+
 * `get_preview_decision`
 * `get_preview_state_after`
 * `preview_would_mutate`
@@ -88,9 +93,10 @@ Portable controller contract coverage for:
 * `preview(engine, user_input)` result envelope, `would_mutate`, and non-mutation of live engine state
 * `state_diff(state_before, state_after)` deterministic structural diff output
 
-These fixtures keep a minimal, language-neutral contract matrix for controller APIs.
-They intentionally validate the raw controller result envelopes; helper accessors
-are covered separately by the public API presence contract above.
+These fixtures keep a minimal, language-neutral contract matrix for step and
+audit APIs. They intentionally validate the raw result envelopes; helper
+accessors are covered separately by the root and audit API presence contracts
+above.
 
 The current runner enforces a closed fixture shape for this family.
 Unknown top-level, action, expected, and documented result/diff fields are rejected.