context-compiler 0.9.0.dev7__tar.gz → 0.9.0.dev8__tar.gz

{context_compiler-0.9.0.dev7 → context_compiler-0.9.0.dev8}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: context-compiler
-Version: 0.9.0.dev7
+Version: 0.9.0.dev8
 Summary: Deterministic conversational state engine for LLM applications.
 Project-URL: Homepage, https://github.com/rlippmann/context-compiler
 Project-URL: Repository, https://github.com/rlippmann/context-compiler
@@ -158,12 +158,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)
@@ -302,7 +302,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(...)`,

{context_compiler-0.9.0.dev7 → context_compiler-0.9.0.dev8}/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(...)`,

{context_compiler-0.9.0.dev7 → context_compiler-0.9.0.dev8}/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 @@ from demos.llm_client import complete_messages
 
 
 def main() -> None:
-    engine = create_engine()
+    engine = Engine()
     user_inputs = ["prohibit peanuts", "use peanuts"]
     print_user_inputs(user_inputs)
 

{context_compiler-0.9.0.dev7 → context_compiler-0.9.0.dev8}/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.",

{context_compiler-0.9.0.dev7 → context_compiler-0.9.0.dev8}/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",

{context_compiler-0.9.0.dev7 → context_compiler-0.9.0.dev8}/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",
         (

{context_compiler-0.9.0.dev7 → context_compiler-0.9.0.dev8}/demos/05_llm_prompt_drift_vs_state.py

@@ -4,7 +4,7 @@ import argparse
 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.")

{context_compiler-0.9.0.dev7 → context_compiler-0.9.0.dev8}/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

{context_compiler-0.9.0.dev7 → context_compiler-0.9.0.dev8}/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):

{context_compiler-0.9.0.dev7 → context_compiler-0.9.0.dev8}/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)
 

{context_compiler-0.9.0.dev7 → context_compiler-0.9.0.dev8}/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)
 

{context_compiler-0.9.0.dev7 → context_compiler-0.9.0.dev8}/demos/common.py

@@ -7,7 +7,7 @@ from typing import Literal, NotRequired, TypedDict
 
 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
 

{context_compiler-0.9.0.dev7 → context_compiler-0.9.0.dev8}/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")

{context_compiler-0.9.0.dev7 → context_compiler-0.9.0.dev8}/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")

{context_compiler-0.9.0.dev7 → context_compiler-0.9.0.dev8}/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")

{context_compiler-0.9.0.dev7 → context_compiler-0.9.0.dev8}/examples/04_tool_governance_denylist.py

@@ -4,7 +4,7 @@ from dataclasses import dataclass
 
 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}")

{context_compiler-0.9.0.dev7 → context_compiler-0.9.0.dev8}/examples/05_llm_integration_pattern.py

@@ -6,7 +6,6 @@ from _util import print_decision_summary, print_engine_observations
 
 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)

{context_compiler-0.9.0.dev7 → context_compiler-0.9.0.dev8}/examples/06_step_sequence_and_state_restore.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()
     turns = [
         "prohibit peanuts",
         "set premise vegetarian curry",
@@ -22,7 +22,7 @@ def main() -> None:
 
     # Hosts can persist authoritative state directly instead of replaying prior turns.
     state_json = engine.export_json()
-    restored = create_engine()
+    restored = Engine()
     restored.import_json(state_json)
 
     print("JSON restore keeps authority state:")

{context_compiler-0.9.0.dev7 → context_compiler-0.9.0.dev8}/examples/07_single_policy_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: prohibit peanuts")
     decision1 = engine.step("prohibit peanuts")

{context_compiler-0.9.0.dev7 → context_compiler-0.9.0.dev8}/pyproject.toml

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

{context_compiler-0.9.0.dev7 → context_compiler-0.9.0.dev8}/src/context_compiler/__init__.py

@@ -18,7 +18,6 @@ from .engine import (
     DecisionKind,
     Engine,
     PolicyValue,
-    create_engine,
 )
 
 __version__ = version("context-compiler")
@@ -33,7 +32,6 @@ __all__ = [
     "POLICY_PROHIBIT",
     "POLICY_USE",
     "PolicyValue",
-    "create_engine",
     "get_error_message",
     "is_error",
     "is_no_directive",

{context_compiler-0.9.0.dev7 → context_compiler-0.9.0.dev8}/src/context_compiler/engine.py

@@ -4,7 +4,6 @@ import json
 import re
 from collections.abc import Mapping
 from copy import deepcopy
-from dataclasses import dataclass
 from enum import StrEnum
 from typing import Literal, TypedDict
 from unicodedata import normalize as unicode_normalize
@@ -20,7 +19,7 @@ from .const import (
     STATE_PREMISE,
     STATE_VERSION,
 )
-from .grammar import DirectiveKind, decompose_directive
+from .grammar import CanonicalDirective, _DirectiveKind, decompose_directive
 
 PolicyValue = Literal["use", "prohibit"]
 
@@ -48,29 +47,7 @@ class Decision(TypedDict):
     message: str | None
 
 
-@dataclass(frozen=True)
-class Action:
-    """Represent one parsed engine action before state validation or mutation."""
-
-    kind: Literal[
-        "set_premise",
-        "change_premise",
-        "use_item",
-        "prohibit_item",
-        "remove_policy_item",
-        "replace_use",
-        "clear_premise",
-        "reset_policies",
-        "clear_state",
-    ]
-    value: str | None = None
-    item: str | None = None
-    new_item: str | None = None
-    old_item: str | None = None
-
-
-@dataclass(frozen=True)
-class _EvaluatedTransition:
+class _EvaluatedTransition(TypedDict):
     decision: Decision
     next_state: _State
 
@@ -78,12 +55,6 @@ class _EvaluatedTransition:
 _NO_DIRECTIVE: Decision = {"kind": DecisionKind.NO_DIRECTIVE, "message": None}
 
 
-def create_engine() -> "Engine":
-    """Create an engine initialized to the empty authoritative state."""
-
-    return Engine()
-
-
 class Engine:
     """Own the authoritative state and apply one directive transition at a time."""
 
@@ -120,40 +91,48 @@ class Engine:
     def step(self, user_input: str) -> Decision:
         """Evaluate and commit one user input against authoritative state.
 
-        Non-directive input returns ``no_directive`` without changing state.
-        Invalid directives return ``error`` without changing state. Accepted
+        Non-canonical input does not produce a state transition and returns
+        ``no_directive``. At the current engine boundary, invalid directive
+        classification is handled the same way as no-directive input. Accepted
         directives return ``update`` and commit the resulting authoritative
         state before the decision is returned.
         """
 
-        evaluated = self._evaluate_transition(self._state, user_input)
-        self._replace_state(evaluated.next_state)
-        return evaluated.decision
+        directive = decompose_directive(user_input)
+        if not isinstance(directive, CanonicalDirective):
+            return _NO_DIRECTIVE.copy()
+
+        return self.apply_directive(directive)
+
+    def apply_directive(self, directive: CanonicalDirective) -> Decision:
+        """Evaluate and commit one canonical directive against authoritative state."""
 
-    def _evaluate_transition(self, state: _State, user_input: str) -> _EvaluatedTransition:
-        action = _parse_directive(user_input)
-        if action is None:
-            return _EvaluatedTransition(decision=_NO_DIRECTIVE.copy(), next_state=deepcopy(state))
+        evaluated = self._evaluate_directive_transition(self._state, directive)
+        self._replace_state(evaluated["next_state"])
+        return evaluated["decision"]
 
-        error_decision = self._pre_mutation_error(action, state=state)
+    def _evaluate_directive_transition(
+        self, state: _State, directive: CanonicalDirective
+    ) -> _EvaluatedTransition:
+        error_decision = self._pre_mutation_error(directive, state=state)
         if error_decision is not None:
-            return _EvaluatedTransition(decision=error_decision, next_state=deepcopy(state))
+            return {"decision": error_decision, "next_state": deepcopy(state)}
 
-        next_state = self._apply_action(action, state=state)
-        return _EvaluatedTransition(decision=_update_decision(next_state), next_state=next_state)
+        next_state = self._apply_directive(directive, state=state)
+        return {"decision": _update_decision(next_state), "next_state": next_state}
 
     def _replace_state(self, state: _State) -> None:
         self._state = state
 
     def _pre_mutation_error(
-        self, action: Action, *, state: _State | None = None
+        self, directive: CanonicalDirective, *, state: _State | None = None
     ) -> Decision | None:
         candidate_state = self._state if state is None else state
         # Single error path: all error outcomes are detected before any mutation.
-        if action.kind in {"set_premise", "change_premise"}:
-            assert action.value is not None
-            if _sanitize_premise_value(action.value) == "":
-                if action.kind == "set_premise":
+        if directive.kind in {_DirectiveKind.SET_PREMISE, _DirectiveKind.CHANGE_PREMISE}:
+            value = directive.operands["value"]
+            if _sanitize_premise_value(value) == "":
+                if directive.kind is _DirectiveKind.SET_PREMISE:
                     return _error(
                         "Premise value cannot be empty.\n"
                         "Use 'set premise <value>' with a non-empty value."
@@ -163,56 +142,60 @@ class Engine:
                     "Use 'change premise to <value>' with a non-empty value."
                 )
 
-        if action.kind == "remove_policy_item":
-            assert action.item is not None
-            if _normalize_item(action.item) == "":
-                return _error(
-                    "Policy item cannot be empty.\n"
-                    "Use 'remove policy <item>' with a non-empty value."
-                )
-
-        if action.kind == "use_item":
-            assert action.item is not None
-            if _normalize_item(action.item) == "":
-                return _error(
-                    "Policy item cannot be empty.\nUse 'use <item>' with a non-empty value."
-                )
-
-        if action.kind == "prohibit_item":
-            assert action.item is not None
-            if _normalize_item(action.item) == "":
-                return _error(
-                    "Policy item cannot be empty.\nUse 'prohibit <item>' with a non-empty value."
-                )
-
-        if action.kind == "set_premise" and candidate_state[STATE_PREMISE] is not None:
+        if (
+            directive.kind is _DirectiveKind.REMOVE_POLICY
+            and _normalize_item(directive.operands["item"]) == ""
+        ):
+            return _error(
+                "Policy item cannot be empty.\nUse 'remove policy <item>' with a non-empty value."
+            )
+
+        if (
+            directive.kind is _DirectiveKind.USE_ITEM
+            and _normalize_item(directive.operands["item"]) == ""
+        ):
+            return _error("Policy item cannot be empty.\nUse 'use <item>' with a non-empty value.")
+
+        if (
+            directive.kind is _DirectiveKind.PROHIBIT_ITEM
+            and _normalize_item(directive.operands["item"]) == ""
+        ):
+            return _error(
+                "Policy item cannot be empty.\nUse 'prohibit <item>' with a non-empty value."
+            )
+
+        if (
+            directive.kind is _DirectiveKind.SET_PREMISE
+            and candidate_state[STATE_PREMISE] is not None
+        ):
             return _error("Premise already set.\nUse 'change premise to <value>' to modify it.")
 
-        if action.kind == "change_premise" and candidate_state[STATE_PREMISE] is None:
+        if (
+            directive.kind is _DirectiveKind.CHANGE_PREMISE
+            and candidate_state[STATE_PREMISE] is None
+        ):
             return _error("No premise is set.\nUse 'set premise <value>' to define one.")
 
-        if action.kind == "use_item":
-            assert action.item is not None
-            item_key = _normalize_item(action.item)
+        if directive.kind is _DirectiveKind.USE_ITEM:
+            item_key = _normalize_item(directive.operands["item"])
             if candidate_state[STATE_POLICIES].get(item_key) == POLICY_PROHIBIT:
                 return _error(
                     f'"{item_key}" is currently prohibited.\nRemove or replace it before using it.'
                 )
 
-        if action.kind == "prohibit_item":
-            assert action.item is not None
-            item_key = _normalize_item(action.item)
+        if directive.kind is _DirectiveKind.PROHIBIT_ITEM:
+            item_key = _normalize_item(directive.operands["item"])
             if candidate_state[STATE_POLICIES].get(item_key) == POLICY_USE:
                 return _error(
                     f'"{item_key}" is currently in use.\n'
                     "Remove or replace it before prohibiting it."
                 )
 
-        if action.kind == "replace_use":
-            assert action.new_item is not None
-            assert action.old_item is not None
-            new_key = _normalize_item(action.new_item)
-            old_key = _normalize_item(action.old_item)
+        if directive.kind is _DirectiveKind.REPLACE_USE:
+            new_item = directive.operands["new_item"]
+            old_item = directive.operands["old_item"]
+            new_key = _normalize_item(new_item)
+            old_key = _normalize_item(old_item)
             if new_key == old_key:
                 return None
 
@@ -220,67 +203,63 @@ class Engine:
             new_state = candidate_state[STATE_POLICIES].get(new_key)
             if old_state == POLICY_PROHIBIT:
                 return _error(
-                    f'"{action.old_item}" is currently prohibited.\n'
+                    f'"{old_item}" is currently prohibited.\n'
                     "Submit explicit directive(s) to remove it or use a different item."
                 )
             if new_state == POLICY_PROHIBIT:
                 return _error(
-                    f'"{action.new_item}" is currently prohibited.\n'
+                    f'"{new_item}" is currently prohibited.\n'
                     "Submit explicit directive(s) to remove it or use a different item."
                 )
             if old_state not in {None, POLICY_USE}:
                 return _error(
-                    f'"{action.old_item}" is not currently in use.\n'
+                    f'"{old_item}" is not currently in use.\n'
                     "Replacement requires an active 'use' policy."
                 )
 
         return None
 
-    def _apply_action(self, action: Action, *, state: _State) -> _State:
+    def _apply_directive(self, directive: CanonicalDirective, *, state: _State) -> _State:
         next_state = deepcopy(state)
-        kind = action.kind
 
-        if kind == "set_premise":
-            assert action.value is not None
-            next_state[STATE_PREMISE] = _sanitize_premise_value(action.value)
+        if directive.kind is _DirectiveKind.SET_PREMISE:
+            next_state[STATE_PREMISE] = _sanitize_premise_value(directive.operands["value"])
             return next_state
 
-        if kind == "change_premise":
-            assert action.value is not None
-            next_state[STATE_PREMISE] = _sanitize_premise_value(action.value)
+        if directive.kind is _DirectiveKind.CHANGE_PREMISE:
+            next_state[STATE_PREMISE] = _sanitize_premise_value(directive.operands["value"])
             return next_state
 
-        if kind == "use_item":
-            assert action.item is not None
-            item_key = _normalize_item(action.item)
+        if directive.kind is _DirectiveKind.USE_ITEM:
+            item_key = _normalize_item(directive.operands["item"])
             # Idempotent directives are updates even if state does not change.
             next_state[STATE_POLICIES][item_key] = POLICY_USE
             return next_state
 
-        if kind == "prohibit_item":
-            assert action.item is not None
-            item_key = _normalize_item(action.item)
+        if directive.kind is _DirectiveKind.PROHIBIT_ITEM:
+            item_key = _normalize_item(directive.operands["item"])
             # Idempotent directives are updates even if state does not change.
             next_state[STATE_POLICIES][item_key] = POLICY_PROHIBIT
             return next_state
 
-        if kind == "replace_use":
-            assert action.new_item is not None
-            assert action.old_item is not None
-            self._apply_replacement_explicit(next_state, action.new_item, action.old_item)
+        if directive.kind is _DirectiveKind.REPLACE_USE:
+            self._apply_replacement_explicit(
+                next_state,
+                directive.operands["new_item"],
+                directive.operands["old_item"],
+            )
             return next_state
 
-        if kind == "remove_policy_item":
-            assert action.item is not None
-            item_key = _normalize_item(action.item)
+        if directive.kind is _DirectiveKind.REMOVE_POLICY:
+            item_key = _normalize_item(directive.operands["item"])
             next_state[STATE_POLICIES].pop(item_key, None)
             return next_state
 
-        if kind == "clear_premise":
+        if directive.kind is _DirectiveKind.CLEAR_PREMISE:
             next_state[STATE_PREMISE] = None
             return next_state
 
-        if kind == "reset_policies":
+        if directive.kind is _DirectiveKind.RESET_POLICIES:
             next_state[STATE_POLICIES] = {}
             return next_state
 
@@ -297,34 +276,6 @@ class Engine:
         state[STATE_POLICIES][new_key] = POLICY_USE
 
 
-def _parse_directive(user_input: str) -> Action | None:
-    parsed = decompose_directive(user_input)
-    if parsed is None:
-        return None
-
-    if parsed.kind is DirectiveKind.SET_PREMISE:
-        return Action(kind="set_premise", value=parsed.operands["value"])
-    if parsed.kind is DirectiveKind.CHANGE_PREMISE:
-        return Action(kind="change_premise", value=parsed.operands["value"])
-    if parsed.kind is DirectiveKind.USE_ITEM:
-        return Action(kind="use_item", item=parsed.operands["item"])
-    if parsed.kind is DirectiveKind.PROHIBIT_ITEM:
-        return Action(kind="prohibit_item", item=parsed.operands["item"])
-    if parsed.kind is DirectiveKind.REMOVE_POLICY:
-        return Action(kind="remove_policy_item", item=parsed.operands["item"])
-    if parsed.kind is DirectiveKind.REPLACE_USE:
-        return Action(
-            kind="replace_use",
-            new_item=parsed.operands["new_item"],
-            old_item=parsed.operands["old_item"],
-        )
-    if parsed.kind is DirectiveKind.CLEAR_PREMISE:
-        return Action(kind="clear_premise")
-    if parsed.kind is DirectiveKind.RESET_POLICIES:
-        return Action(kind="reset_policies")
-    return Action(kind="clear_state")
-
-
 def _initial_state() -> _State:
     return {
         STATE_PREMISE: None,

{context_compiler-0.9.0.dev7 → context_compiler-0.9.0.dev8}/src/context_compiler/grammar.py

@@ -7,7 +7,7 @@ from enum import StrEnum
 from types import MappingProxyType
 
 
-class DirectiveKind(StrEnum):
+class _DirectiveKind(StrEnum):
     """Enumerate the supported canonical directive families."""
 
     SET_PREMISE = "set_premise"
@@ -26,19 +26,22 @@ class CanonicalDirective:
     """Represent one parsed canonical directive and its named operands.
 
     ``text`` preserves the original accepted input text. It may retain caller
-    formatting or casing and is not canonical serialized directive text; use
-    :func:`render_directive` to produce canonical directive text from semantic
-    kind and operands.
+    formatting or casing and is not canonical serialized directive text.
     """
 
     text: str
-    kind: DirectiveKind
+    kind: _DirectiveKind
     operands: MappingProxyType[str, str]
 
 
+@dataclass(frozen=True, slots=True)
+class InvalidDirectiveSyntax:
+    """Represent directive-shaped input that fails canonical syntax parsing."""
+
+
 @dataclass(frozen=True, slots=True)
 class _DirectiveSpec:
-    kind: DirectiveKind
+    kind: _DirectiveKind
     operand_names: tuple[str, ...]
     exact_text: str | None
     renderer: Callable[[MappingProxyType[str, str]], str]
@@ -49,6 +52,10 @@ _CHANGE_PREMISE_PREFIX = "change premise to "
 _USE_PREFIX = "use "
 _PROHIBIT_PREFIX = "prohibit "
 _REMOVE_POLICY_PREFIX = "remove policy "
+_CLEAR_PREMISE_TEXT = "clear premise"
+_RESET_POLICIES_TEXT = "reset policies"
+_CLEAR_STATE_TEXT = "clear state"
+_CHANGE_PREMISE_FAMILY = "change premise"
 _INSTEAD_OF_DELIMITER = " instead of "
 _ASCII_WHITESPACE = " \t\n\r\x0b\x0c"
 _HORIZONTAL_WHITESPACE = " \t"
@@ -62,15 +69,37 @@ _REPLACE_RE = re.compile(
     r"(?i)^use[ \t]+(?P<new_item>.*?)[ \t]+instead[ \t]+of[ \t]+(?P<old_item>.+)$"
 )
 
-_CANONICAL_DIRECTIVE_STARTS: tuple[tuple[str, bool], ...] = (
+_PREFIX_DIRECTIVE_STARTS: tuple[tuple[str, bool], ...] = (
     (_CHANGE_PREMISE_PREFIX.removesuffix(" "), True),
     (_SET_PREMISE_PREFIX.removesuffix(" "), True),
     (_REMOVE_POLICY_PREFIX.removesuffix(" "), True),
-    ("reset policies", False),
-    ("clear premise", False),
-    ("clear state", False),
     (_PROHIBIT_PREFIX.removesuffix(" "), True),
-    ("use", True),
+    (_USE_PREFIX.removesuffix(" "), True),
+)
+
+_EXACT_DIRECTIVE_STARTS: tuple[tuple[str, bool], ...] = (
+    (_RESET_POLICIES_TEXT, False),
+    (_CLEAR_PREMISE_TEXT, False),
+    (_CLEAR_STATE_TEXT, False),
+)
+
+_CANONICAL_DIRECTIVE_STARTS: tuple[tuple[str, bool], ...] = (
+    _PREFIX_DIRECTIVE_STARTS[0],
+    _PREFIX_DIRECTIVE_STARTS[1],
+    _PREFIX_DIRECTIVE_STARTS[2],
+    _EXACT_DIRECTIVE_STARTS[0],
+    _EXACT_DIRECTIVE_STARTS[1],
+    _EXACT_DIRECTIVE_STARTS[2],
+    _PREFIX_DIRECTIVE_STARTS[3],
+    _PREFIX_DIRECTIVE_STARTS[4],
+)
+
+_DIRECTIVE_FAMILY_STARTS: tuple[tuple[str, bool], ...] = (
+    (_CHANGE_PREMISE_FAMILY, True),
+    _PREFIX_DIRECTIVE_STARTS[1],
+    _PREFIX_DIRECTIVE_STARTS[2],
+    *_EXACT_DIRECTIVE_STARTS,
+    *_PREFIX_DIRECTIVE_STARTS[3:],
 )
 
 
@@ -97,59 +126,59 @@ def _render_exact(text: str) -> Callable[[MappingProxyType[str, str]], str]:
 
 _DIRECTIVE_SPECS = MappingProxyType(
     {
-        DirectiveKind.SET_PREMISE: _DirectiveSpec(
-            kind=DirectiveKind.SET_PREMISE,
+        _DirectiveKind.SET_PREMISE: _DirectiveSpec(
+            kind=_DirectiveKind.SET_PREMISE,
             operand_names=("value",),
             exact_text=None,
             renderer=_render_with_prefix(_SET_PREMISE_PREFIX, "value"),
         ),
-        DirectiveKind.CHANGE_PREMISE: _DirectiveSpec(
-            kind=DirectiveKind.CHANGE_PREMISE,
+        _DirectiveKind.CHANGE_PREMISE: _DirectiveSpec(
+            kind=_DirectiveKind.CHANGE_PREMISE,
             operand_names=("value",),
             exact_text=None,
             renderer=_render_with_prefix(_CHANGE_PREMISE_PREFIX, "value"),
         ),
-        DirectiveKind.USE_ITEM: _DirectiveSpec(
-            kind=DirectiveKind.USE_ITEM,
+        _DirectiveKind.USE_ITEM: _DirectiveSpec(
+            kind=_DirectiveKind.USE_ITEM,
             operand_names=("item",),
             exact_text=None,
             renderer=_render_with_prefix(_USE_PREFIX, "item"),
         ),
-        DirectiveKind.PROHIBIT_ITEM: _DirectiveSpec(
-            kind=DirectiveKind.PROHIBIT_ITEM,
+        _DirectiveKind.PROHIBIT_ITEM: _DirectiveSpec(
+            kind=_DirectiveKind.PROHIBIT_ITEM,
             operand_names=("item",),
             exact_text=None,
             renderer=_render_with_prefix(_PROHIBIT_PREFIX, "item"),
         ),
-        DirectiveKind.REMOVE_POLICY: _DirectiveSpec(
-            kind=DirectiveKind.REMOVE_POLICY,
+        _DirectiveKind.REMOVE_POLICY: _DirectiveSpec(
+            kind=_DirectiveKind.REMOVE_POLICY,
             operand_names=("item",),
             exact_text=None,
             renderer=_render_with_prefix(_REMOVE_POLICY_PREFIX, "item"),
         ),
-        DirectiveKind.REPLACE_USE: _DirectiveSpec(
-            kind=DirectiveKind.REPLACE_USE,
+        _DirectiveKind.REPLACE_USE: _DirectiveSpec(
+            kind=_DirectiveKind.REPLACE_USE,
             operand_names=("new_item", "old_item"),
             exact_text=None,
             renderer=_render_replace_use,
         ),
-        DirectiveKind.CLEAR_PREMISE: _DirectiveSpec(
-            kind=DirectiveKind.CLEAR_PREMISE,
+        _DirectiveKind.CLEAR_PREMISE: _DirectiveSpec(
+            kind=_DirectiveKind.CLEAR_PREMISE,
             operand_names=(),
-            exact_text="clear premise",
-            renderer=_render_exact("clear premise"),
+            exact_text=_CLEAR_PREMISE_TEXT,
+            renderer=_render_exact(_CLEAR_PREMISE_TEXT),
         ),
-        DirectiveKind.RESET_POLICIES: _DirectiveSpec(
-            kind=DirectiveKind.RESET_POLICIES,
+        _DirectiveKind.RESET_POLICIES: _DirectiveSpec(
+            kind=_DirectiveKind.RESET_POLICIES,
             operand_names=(),
-            exact_text="reset policies",
-            renderer=_render_exact("reset policies"),
+            exact_text=_RESET_POLICIES_TEXT,
+            renderer=_render_exact(_RESET_POLICIES_TEXT),
         ),
-        DirectiveKind.CLEAR_STATE: _DirectiveSpec(
-            kind=DirectiveKind.CLEAR_STATE,
+        _DirectiveKind.CLEAR_STATE: _DirectiveSpec(
+            kind=_DirectiveKind.CLEAR_STATE,
             operand_names=(),
-            exact_text="clear state",
-            renderer=_render_exact("clear state"),
+            exact_text=_CLEAR_STATE_TEXT,
+            renderer=_render_exact(_CLEAR_STATE_TEXT),
         ),
     }
 )
@@ -177,15 +206,8 @@ def _operand_starts_with_token(value: str, token: str) -> bool:
     return normalized == token or normalized.startswith(f"{token} ")
 
 
-def match_canonical_directive_start(text: str, start: int) -> int | None:
-    """Locate a canonical directive prefix at a given character position.
-
-    This is a shallow syntax-start matcher: it classifies whether canonical
-    directive syntax begins at ``start`` and, when it does, returns the index
-    immediately after the directive keyword prefix. It does not parse operands,
-    validate the full directive payload, or evaluate multi-directive state
-    semantics.
-    """
+def _match_canonical_directive_start(text: str, start: int) -> int | None:
+    """Locate a canonical directive prefix at a given character position."""
     if start < 0 or start >= len(text):
         return None
 
@@ -242,27 +264,30 @@ def _match_directive_token(
     return index
 
 
-def contains_multiple_canonical_directives(text: str) -> bool:
-    """Report whether text contains more than one canonical directive start.
-
-    This detects compound directive structure by looking for multiple canonical
-    directive prefixes in the same input. It is not a replacement for full
-    directive validation, and it does not parse directive operands, repair
-    malformed text, or determine whether a whole string should be accepted as a
-    single directive.
-    """
-    first_start = match_canonical_directive_start(text, 0)
+def _contains_multiple_canonical_directives(text: str) -> bool:
+    """Report whether text contains more than one canonical directive start."""
+    first_start = _match_canonical_directive_start(text, 0)
     if first_start is None:
         return False
 
     for index in range(first_start, len(text)):
-        next_start = match_canonical_directive_start(text, index)
+        next_start = _match_canonical_directive_start(text, index)
         if next_start is not None:
             return True
 
     return False
 
 
+def _starts_with_directive_family(text: str) -> bool:
+    for token, require_space_or_end in _DIRECTIVE_FAMILY_STARTS:
+        if (
+            _match_directive_token(text, 0, token, require_space_or_end=require_space_or_end)
+            is not None
+        ):
+            return True
+    return False
+
+
 def _parse_replace_use(trimmed_text: str) -> CanonicalDirective | None:
     match = _REPLACE_RE.fullmatch(trimmed_text)
     if match is None:
@@ -280,67 +305,71 @@ def _parse_replace_use(trimmed_text: str) -> CanonicalDirective | None:
         return None
     return CanonicalDirective(
         text=trimmed_text,
-        kind=DirectiveKind.REPLACE_USE,
+        kind=_DirectiveKind.REPLACE_USE,
         operands=MappingProxyType({"new_item": new_item, "old_item": old_item}),
     )
 
 
-def decompose_directive(text: str) -> CanonicalDirective | None:
+def decompose_directive(text: str) -> CanonicalDirective | InvalidDirectiveSyntax | None:
     """Parse one canonical directive into its semantic kind and operands.
 
     This determines whether ``text`` is a single canonical directive and, when
     it is, returns the directive kind plus canonical operand names with the
-    original operand text preserved. Callers can determine whether ``text`` is
-    a complete canonical directive by checking whether this returns a non-`None`
-    result. It does not repair input, infer intent, or evaluate directive
-    effects against compiler state.
+    original operand text preserved. It returns ``None`` when no canonical
+    directive is present and returns ``InvalidDirectiveSyntax`` when the text is
+    directive-shaped but not valid canonical syntax. It does not repair input,
+    infer intent, or evaluate directive effects against compiler state.
     """
     trimmed_text = _trim_ascii_whitespace(text)
     if trimmed_text == "":
         return None
-    if contains_multiple_canonical_directives(trimmed_text):
+    if not _starts_with_directive_family(trimmed_text):
         return None
+    if _contains_multiple_canonical_directives(trimmed_text):
+        return InvalidDirectiveSyntax()
+
+    invalid_result = InvalidDirectiveSyntax()
 
     normalized = _normalized_for_matching(trimmed_text)
 
-    if normalized == "clear premise":
+    if normalized == _CLEAR_PREMISE_TEXT:
         return CanonicalDirective(
-            text=text, kind=DirectiveKind.CLEAR_PREMISE, operands=MappingProxyType({})
+            text=text, kind=_DirectiveKind.CLEAR_PREMISE, operands=MappingProxyType({})
         )
-    if normalized == "reset policies":
+    if normalized == _RESET_POLICIES_TEXT:
         return CanonicalDirective(
             text=text,
-            kind=DirectiveKind.RESET_POLICIES,
+            kind=_DirectiveKind.RESET_POLICIES,
             operands=MappingProxyType({}),
         )
-    if normalized == "clear state":
+    if normalized == _CLEAR_STATE_TEXT:
         return CanonicalDirective(
-            text=text, kind=DirectiveKind.CLEAR_STATE, operands=MappingProxyType({})
+            text=text, kind=_DirectiveKind.CLEAR_STATE, operands=MappingProxyType({})
         )
 
     if normalized.startswith("set premise "):
         match = _SET_PREMISE_RE.fullmatch(trimmed_text)
         if match is None:
-            return None
+            return invalid_result
         value = match.group("value")
         if not _operand_has_content(value) or _operand_starts_with_token(value, "to"):
-            return None
+            return invalid_result
         return CanonicalDirective(
             text=text,
-            kind=DirectiveKind.SET_PREMISE,
+            kind=_DirectiveKind.SET_PREMISE,
             operands=MappingProxyType({"value": value}),
         )
 
     if normalized.startswith("change premise to "):
         match = _CHANGE_PREMISE_RE.fullmatch(trimmed_text)
         if match is None:
-            return None
+            return invalid_result
         value = match.group("value")
         if not _operand_has_content(value):
-            return None
+            return invalid_result
         return CanonicalDirective(
             text=text,
-            kind=DirectiveKind.CHANGE_PREMISE,
+            kind=_DirectiveKind.CHANGE_PREMISE,
             operands=MappingProxyType({"value": value}),
         )
 
@@ -351,7 +380,7 @@ def decompose_directive(text: str) -> CanonicalDirective | None:
     if normalized.startswith("use "):
         match = _USE_RE.fullmatch(trimmed_text)
         if match is None:
-            return None
+            return invalid_result
         item = match.group("item")
         normalized_item = _normalized_for_matching(item)
         if (
@@ -360,52 +389,46 @@ def decompose_directive(text: str) -> CanonicalDirective | None:
             or normalized_item.endswith(" instead of")
             or _INSTEAD_OF_DELIMITER in normalized_item
         ):
-            return None
+            return invalid_result
         return CanonicalDirective(
             text=text,
-            kind=DirectiveKind.USE_ITEM,
+            kind=_DirectiveKind.USE_ITEM,
             operands=MappingProxyType({"item": item}),
         )
 
     if normalized.startswith("prohibit "):
         match = _PROHIBIT_RE.fullmatch(trimmed_text)
         if match is None:
-            return None
+            return invalid_result
         item = match.group("item")
         if not _operand_has_content(item):
-            return None
+            return invalid_result
         return CanonicalDirective(
             text=text,
-            kind=DirectiveKind.PROHIBIT_ITEM,
+            kind=_DirectiveKind.PROHIBIT_ITEM,
             operands=MappingProxyType({"item": item}),
         )
 
     if normalized.startswith("remove policy "):
         match = _REMOVE_POLICY_RE.fullmatch(trimmed_text)
         if match is None:
-            return None
+            return invalid_result
         item = match.group("item")
         if not _operand_has_content(item):
-            return None
+            return invalid_result
         return CanonicalDirective(
             text=text,
-            kind=DirectiveKind.REMOVE_POLICY,
+            kind=_DirectiveKind.REMOVE_POLICY,
             operands=MappingProxyType({"item": item}),
         )
 
-    return None
-
+    return invalid_result
 
-def render_directive(kind: DirectiveKind, /, **operands: str) -> str:
-    """Produce canonical directive text from a semantic kind and operands.
 
-    This determines the exact canonical spelling for an existing grammar
-    capability and rejects operand combinations that would not round-trip as the
-    requested directive kind. It does not infer missing operands, parse user
-    input, or extend the grammar with new behaviors.
-    """
+def _render_directive(kind: _DirectiveKind | str, /, **operands: str) -> str:
+    """Produce canonical directive text from a semantic kind and operands."""
     try:
-        normalized_kind = kind if isinstance(kind, DirectiveKind) else DirectiveKind(kind)
+        normalized_kind = kind if isinstance(kind, _DirectiveKind) else _DirectiveKind(kind)
         spec = _DIRECTIVE_SPECS[normalized_kind]
     except (KeyError, ValueError) as exc:
         raise ValueError(f"Unsupported directive kind: {kind!r}") from exc
@@ -416,33 +439,30 @@ def render_directive(kind: DirectiveKind, /, **operands: str) -> str:
     missing_names = expected_names - actual_names
     if missing_names:
         missing = ", ".join(sorted(missing_names))
-        raise ValueError(f"Missing required operands for {kind.value}: {missing}")
+        raise ValueError(f"Missing required operands for {normalized_kind.value}: {missing}")
     if unexpected_names:
         unexpected = ", ".join(sorted(unexpected_names))
-        raise ValueError(f"Unexpected operands for {kind.value}: {unexpected}")
+        raise ValueError(f"Unexpected operands for {normalized_kind.value}: {unexpected}")
 
     normalized_operands: dict[str, str] = {}
     for name in spec.operand_names:
         raw_value = operands[name]
         if not isinstance(raw_value, str):
-            raise ValueError(f"Operand {name!r} for {kind.value} must be a string.")
+            raise ValueError(f"Operand {name!r} for {normalized_kind.value} must be a string.")
         if raw_value.strip() == "":
-            raise ValueError(f"Operand {name!r} for {kind.value} cannot be empty.")
+            raise ValueError(f"Operand {name!r} for {normalized_kind.value} cannot be empty.")
         normalized_operands[name] = raw_value
 
     operand_view = MappingProxyType(normalized_operands)
     rendered = spec.renderer(operand_view)
     decomposed = decompose_directive(rendered)
-    if decomposed is None or decomposed.kind is not normalized_kind:
+    if not isinstance(decomposed, CanonicalDirective) or decomposed.kind is not normalized_kind:
         raise ValueError(f"Operands do not produce a canonical {normalized_kind.value} directive.")
     return rendered
 
 
 __all__ = [
     "CanonicalDirective",
-    "DirectiveKind",
-    "contains_multiple_canonical_directives",
+    "InvalidDirectiveSyntax",
     "decompose_directive",
-    "match_canonical_directive_start",
-    "render_directive",
 ]

{context_compiler-0.9.0.dev7 → context_compiler-0.9.0.dev8}/src/context_compiler/repl.py

@@ -5,7 +5,7 @@ import sys
 from collections.abc import Mapping
 from typing import TextIO
 
-from . import __version__, create_engine
+from . import __version__
 from .const import STATE_POLICIES, STATE_PREMISE, STATE_VERSION
 from .decision_helpers import is_error, is_no_directive, is_update
 from .engine import Decision, DecisionKind, Engine, PolicyValue
@@ -233,7 +233,7 @@ def run_repl(
     emit NDJSON records.
     """
 
-    active_engine = create_engine() if engine is None else engine
+    active_engine = Engine() if engine is None else engine
 
     if _is_interactive(in_stream, out_stream):
         print("Context Compiler REPL (0.5). Type help for commands.", file=out_stream)
@@ -420,7 +420,7 @@ def main() -> int:  # pragma: no cover
         print("error: --json requires non-interactive stdin/stdout.", file=sys.stderr)
         return 1
 
-    engine = create_engine()
+    engine = Engine()
     try:
         _apply_preload_from_options(engine, options)
     except (OSError, ValueError) as exc: