refactor: complete 0.9.0dev8 cleanup

README.md

@@ -136,12 +136,12 @@ Use Context Compiler in your host application first:
 
 ```python
 from context_compiler import (
-    create_engine,
+    Engine,
     is_error,
     is_update,
 )
 
-engine = create_engine()
+engine = Engine()
 
 user_input = "set premise current project uses uv"
 decision = engine.step(user_input)
@@ -280,7 +280,7 @@ reference.
 
 Common API entry points:
 
-- engine lifecycle: `create_engine()`, `engine.step(...)`,
+- engine lifecycle: `Engine()`, `engine.step(...)`,
   `engine.premise`, `engine.policies`, `engine.export_json(...)`,
   `engine.import_json(...)`
 - decision helpers: `is_error(...)`, `is_update(...)`, `is_no_directive(...)`,

demos/01_llm_contradiction_error.py

@@ -1,6 +1,9 @@
 """Demo 1: compiler blocks contradictory directives before model call."""
 
-from context_compiler import create_engine, is_error
+from context_compiler import (
+    Engine,
+    is_error,
+)
 from demos.common import (
     build_baseline_messages,
     build_mediated_messages_from_transcript,
@@ -22,7 +25,7 @@
 
 
 def main() -> None:
-    engine = create_engine()
+    engine = Engine()
     user_inputs = ["prohibit peanuts", "use peanuts"]
     print_user_inputs(user_inputs)
 

demos/02_llm_constraint_guardrail.py

@@ -2,7 +2,7 @@
 
 import re
 
-from context_compiler import create_engine
+from context_compiler import Engine
 from demos.common import (
     build_baseline_messages,
     build_mediated_messages_from_transcript,
@@ -109,7 +109,7 @@ def recipe_includes_prohibited_item(output: str) -> bool:
 
 
 def main() -> None:
-    engine = create_engine()
+    engine = Engine()
     user_inputs = [
         "prohibit peanuts",
         "Suggest a peanut curry recipe with ingredients and steps.",

demos/03_llm_premise_guardrail.py

@@ -2,7 +2,7 @@
 
 import re
 
-from context_compiler import create_engine
+from context_compiler import Engine
 from demos.common import (
     build_baseline_messages,
     build_mediated_messages_from_transcript,
@@ -70,7 +70,7 @@ def _plan_uses_value(output: str, value: str) -> bool:
 
 
 def main() -> None:
-    engine = create_engine()
+    engine = Engine()
     user_inputs = [
         "set premise vegetarian curry",
         "change premise to vegan curry",

demos/04_llm_tool_denylist_guardrail.py

@@ -2,7 +2,7 @@
 
 import re
 
-from context_compiler import create_engine
+from context_compiler import Engine
 from demos.common import (
     build_baseline_messages,
     build_mediated_messages_from_transcript,
@@ -60,7 +60,7 @@ def main() -> None:
     app_managed_prohibited = ["docker"]
     candidate_tools = ["docker", "kubectl"]
 
-    engine = create_engine()
+    engine = Engine()
     user_inputs = [
         "prohibit docker",
         (

demos/05_llm_prompt_drift_vs_state.py

@@ -4,7 +4,7 @@
 import re
 
 import demos.llm_client as llm_client
-from context_compiler import create_engine
+from context_compiler import Engine
 from demos.common import (
     build_baseline_messages,
     build_mediated_messages_from_transcript,
@@ -212,7 +212,7 @@ def premise_matches_expected(output: str, expected: str = EXPECTED_PREMISE) -> b
 
 
 def _run_demo(turns: int = _DEFAULT_TURNS) -> None:
-    engine = create_engine()
+    engine = Engine()
     user_inputs = build_user_inputs(turns)
     if turns == _DEFAULT_TURNS and user_inputs != _ORIGINAL_DEFAULT_TRANSCRIPT:
         raise RuntimeError("Demo 5 default transcript diverged from original behavior.")

demos/06_llm_context_compaction.py

@@ -1,6 +1,9 @@
 """Demo 6: host-side prompt replacement from authoritative step-derived state."""
 
-from context_compiler import DECISION_UPDATE, create_engine
+from context_compiler import (
+    DECISION_UPDATE,
+    Engine,
+)
 from demos.common import compact_user_turns, is_verbose, print_info_report, state_observations
 
 DEMO_NAME = "06_context_compaction — superseded directives eliminated"
@@ -40,7 +43,7 @@ def _build_turns(turn_count: int) -> list[str]:
 
 
 def _compile_premise(turns: list[str]) -> str:
-    engine = create_engine()
+    engine = Engine()
     for turn in turns:
         decision = engine.step(turn)
         assert decision["kind"] == DECISION_UPDATE

demos/07_llm_prompt_vs_state.py

@@ -3,7 +3,7 @@
 import re
 from collections.abc import Mapping
 
-from context_compiler import create_engine
+from context_compiler import Engine
 from context_compiler.engine import PolicyValue
 from demos.common import (
     build_baseline_messages,
@@ -115,7 +115,7 @@ def _actual_summary(*, weak_pass: bool, strong_pass: bool, compiler_pass: bool)
 
 
 def main() -> None:
-    engine = create_engine()
+    engine = Engine()
     print_user_inputs(USER_INPUTS)
 
     for index, user_input in enumerate(USER_INPUTS, start=1):

demos/08_llm_replacement_precondition.py

@@ -2,7 +2,10 @@
 
 from collections.abc import Mapping
 
-from context_compiler import create_engine, is_update
+from context_compiler import (
+    Engine,
+    is_update,
+)
 from demos.common import (
     build_baseline_messages,
     build_reinjected_messages,
@@ -28,7 +31,7 @@ def _is_initial_authoritative_state(*, premise: str | None, policies: Mapping[st
 
 
 def main() -> None:
-    engine = create_engine()
+    engine = Engine()
     user_inputs = [USER_INPUT]
     print_user_inputs(user_inputs)
 

demos/09_llm_confirmation_no_directive.py

@@ -3,7 +3,7 @@
 from collections.abc import Mapping
 
 from context_compiler import (
-    create_engine,
+    Engine,
     is_no_directive,
     is_update,
 )
@@ -43,7 +43,7 @@ def _is_initial_authoritative_state(*, premise: str | None, policies: Mapping[st
 
 
 def main() -> None:
-    engine = create_engine()
+    engine = Engine()
     user_inputs = [TURN_1, TURN_2, TURN_3]
     print_user_inputs(user_inputs)
 

demos/common.py

@@ -7,7 +7,7 @@
 
 from context_compiler import (
     Decision,
-    create_engine,
+    Engine,
     is_error,
     is_update,
 )
@@ -282,7 +282,7 @@ def compact_user_turns(
     - returned state dict is built from engine observations at stop point
     """
 
-    engine = create_engine()
+    engine = Engine()
     compacted_turns: list[str] = []
     message: str | None = None
 

docs/api-reference.md

@@ -28,16 +28,16 @@ Core boundary:
 
 ## Engine Lifecycle
 
-### `create_engine()`
+### `Engine()`
 
 Create a new engine instance.
 
 Typical use:
 
 ```python
-from context_compiler import create_engine
+from context_compiler import Engine
 
-engine = create_engine()
+engine = Engine()
 ```
 
 ### `engine.step(user_input)`
@@ -53,6 +53,11 @@ decision = engine.step("set premise current project uses uv")
 Behavior for directive handling and error is
 defined by the [Directive Grammar Specification](DirectiveGrammarSpec.md).
 
+`engine.step(...)` is the text-input boundary. It parses one user turn with
+`decompose_directive(...)`, returns `no_directive` when the input is not a
+canonical directive, and otherwise delegates the accepted canonical directive
+to `engine.apply_directive(...)`.
+
 Important grammar contract:
 
 - one input may contain at most one canonical directive
@@ -104,6 +109,33 @@ convert operand text into engine/domain identifiers at the grammar layer.
 `CanonicalDirective.text` should not be treated as canonical serialized
 directive output.
 
+### `engine.apply_directive(directive)`
+
+Apply one already-canonical `CanonicalDirective` to authoritative state.
+
+Typical use:
+
+```python
+from context_compiler import Engine
+from context_compiler.grammar import CanonicalDirective, decompose_directive
+
+engine = Engine()
+directive = decompose_directive("use docker")
+assert isinstance(directive, CanonicalDirective)
+
+decision = engine.apply_directive(directive)
+```
+
+Boundary notes:
+
+- `apply_directive(...)` does not parse free-form user text
+- callers should pass only `CanonicalDirective` values produced or validated by
+  the grammar boundary
+- semantic validation and authoritative mutation rules are the same whether the
+  canonical directive arrives through `step(...)` or `apply_directive(...)`
+- `error` remains reserved for canonical directives that fail semantic
+  evaluation
+
 ### `engine.premise`
 
 Read the current authoritative premise value from a live engine.
@@ -155,7 +187,11 @@ the user-facing error text only for `error`, otherwise `None`.
 Typical use:
 
 ```python
-from context_compiler import is_error, is_update
+from context_compiler import (
+    is_error,
+    is_update,
+    Engine,
+)
 
 decision = engine.step(user_input)
 

evals/swe-bench/swe-bench.py

@@ -33,7 +33,10 @@
 from pathlib import Path
 from typing import Any, cast
 
-from context_compiler import create_engine, is_error
+from context_compiler import (
+    Engine,
+    is_error,
+)
 
 RUBRIC_WEIGHTS: dict[str, int] = {
     "Correct fix locus": 2,
@@ -697,7 +700,7 @@ def main() -> None:
         }
         if task.directives is not None:
             print(f"[3/3] Compiler: {task.task_id}", file=sys.stderr)
-            engine = create_engine()
+            engine = Engine()
             error_result: dict[str, Any] | None = None
             for index, directive in enumerate(task.directives):
                 decision = engine.step(directive)

examples/01_persistent_guardrails.py

@@ -2,7 +2,7 @@
 
 from _util import print_decision_summary, print_engine_observations
 
-from context_compiler import Engine, create_engine
+from context_compiler import Engine
 
 
 def build_prompt(engine: Engine, user_input: str) -> str:
@@ -17,7 +17,7 @@ def build_prompt(engine: Engine, user_input: str) -> str:
 
 
 def main() -> None:
-    engine = create_engine()
+    engine = Engine()
 
     print("User: prohibit peanuts")
     decision1 = engine.step("prohibit peanuts")

examples/02_configuration_and_correction.py

@@ -2,11 +2,11 @@
 
 from _util import print_decision_summary, print_engine_observations
 
-from context_compiler import create_engine
+from context_compiler import Engine
 
 
 def main() -> None:
-    engine = create_engine()
+    engine = Engine()
 
     print("User: set premise vegetarian curry")
     decision1 = engine.step("set premise vegetarian curry")

examples/03_ambiguity_with_error.py

@@ -2,7 +2,10 @@
 
 from _util import print_decision_summary, print_engine_observations
 
-from context_compiler import create_engine, is_error
+from context_compiler import (
+    Engine,
+    is_error,
+)
 
 
 def fake_llm(user_input: str) -> str:
@@ -11,7 +14,7 @@ def fake_llm(user_input: str) -> str:
 
 
 def main() -> None:
-    engine = create_engine()
+    engine = Engine()
 
     print("User: prohibit peanuts")
     decision1 = engine.step("prohibit peanuts")

examples/04_tool_governance_denylist.py

@@ -4,7 +4,7 @@
 
 from _util import print_decision_summary, print_engine_observations
 
-from context_compiler import create_engine
+from context_compiler import Engine
 
 
 @dataclass
@@ -21,7 +21,7 @@ def allow_tool(tool: Tool) -> None:
 
 
 def main() -> None:
-    engine = create_engine()
+    engine = Engine()
 
     user_input = "prohibit docker"
     print(f"User: {user_input}")

examples/05_llm_integration_pattern.py

@@ -6,7 +6,6 @@
 
 from context_compiler import (
     Engine,
-    create_engine,
     is_error,
     is_no_directive,
     is_update,
@@ -45,7 +44,7 @@ def handle_turn(engine_input: str, engine: Engine) -> None:
 
 
 def main() -> None:
-    engine = create_engine()
+    engine = Engine()
 
     handle_turn("hello there", engine)
     handle_turn("set premise concise replies", engine)