context-compiler 0.9.0.dev2__py3-none-any.whl → 0.9.0.dev4__py3-none-any.whl

context_compiler/__init__.py

@@ -1,8 +1,8 @@
 from importlib.metadata import version
 
 from .const import (
-    DECISION_CLARIFY,
-    DECISION_PASSTHROUGH,
+    DECISION_ERROR,
+    DECISION_NO_DIRECTIVE,
     DECISION_UPDATE,
     POLICY_PROHIBIT,
     POLICY_USE,
@@ -14,18 +14,20 @@ from .controller import (
     step,
 )
 from .decision_helpers import (
-    get_clarify_prompt,
     get_decision_state,
-    is_clarify,
-    is_passthrough,
+    get_error_message,
+    is_error,
+    is_no_directive,
     is_update,
 )
 from .engine import (
     Decision,
-    DecisionKind,
     Engine,
+    ErrorDecision,
+    NoDirectiveDecision,
     PolicyValue,
     State,
+    UpdateDecision,
     create_engine,
 )
 
@@ -33,23 +35,25 @@ __version__ = version("context-compiler")
 
 __all__ = [
     "Decision",
-    "DecisionKind",
-    "DECISION_CLARIFY",
-    "DECISION_PASSTHROUGH",
+    "DECISION_ERROR",
+    "DECISION_NO_DIRECTIVE",
     "DECISION_UPDATE",
+    "ErrorDecision",
     "Engine",
+    "NoDirectiveDecision",
     "POLICY_PROHIBIT",
     "POLICY_USE",
     "PolicyValue",
     "State",
     "StepResult",
+    "UpdateDecision",
     "create_engine",
-    "get_clarify_prompt",
+    "get_error_message",
     "get_decision_state",
     "get_step_decision",
     "get_step_state",
-    "is_clarify",
-    "is_passthrough",
+    "is_error",
+    "is_no_directive",
     "is_update",
     "step",
 ]

context_compiler/const.py

@@ -12,9 +12,9 @@ POLICY_USE: Final = "use"
 POLICY_PROHIBIT: Final = "prohibit"
 
 # Decision kinds
-DECISION_PASSTHROUGH: Final = "passthrough"
+DECISION_NO_DIRECTIVE: Final = "no_directive"
 DECISION_UPDATE: Final = "update"
-DECISION_CLARIFY: Final = "clarify"
+DECISION_ERROR: Final = "error"
 
 # Schema version
 SCHEMA_VERSION: Final = 2

context_compiler/controller.py

@@ -8,29 +8,39 @@ OUTPUT_VERSION: Literal[1] = 1
 
 
 class PremiseDiff(TypedDict):
+    """Describe how the authoritative premise changed between two states."""
+
     before: str | None
     after: str | None
     changed: bool
 
 
 class ChangedPolicyDiff(TypedDict):
+    """Capture the old and new value for one policy item."""
+
     before: Literal["use", "prohibit"]
     after: Literal["use", "prohibit"]
 
 
 class PoliciesDiff(TypedDict):
+    """Summarize policy items added, removed, or changed between two states."""
+
     added: dict[str, Literal["use", "prohibit"]]
     removed: dict[str, Literal["use", "prohibit"]]
     changed: dict[str, ChangedPolicyDiff]
 
 
 class StructuralDiff(TypedDict):
+    """Describe whether and how authoritative state changed structurally."""
+
     changed: bool
     premise: PremiseDiff
     policies: PoliciesDiff
 
 
 class StepResult(TypedDict):
+    """Return the committed outcome of one controller-driven engine step."""
+
     output_version: Literal[1]
     mode: Literal["step"]
     decision: Decision
@@ -38,6 +48,8 @@ class StepResult(TypedDict):
 
 
 class PreviewResult(TypedDict):
+    """Return the dry-run outcome of one controller preview evaluation."""
+
     output_version: Literal[1]
     mode: Literal["preview"]
     decision: Decision
@@ -48,30 +60,44 @@ class PreviewResult(TypedDict):
 
 
 def get_step_decision(step_result: StepResult) -> Decision:
+    """Return the decision emitted by a committed controller step."""
+
     return step_result["decision"]
 
 
 def get_step_state(step_result: StepResult) -> State:
+    """Return the authoritative state after a committed controller step."""
+
     return step_result["state"]
 
 
 def get_preview_decision(preview_result: PreviewResult) -> Decision:
+    """Return the decision that preview computed without mutating live state."""
+
     return preview_result["decision"]
 
 
 def get_preview_state_after(preview_result: PreviewResult) -> State:
+    """Return the simulated post-transition state from preview."""
+
     return preview_result["state_after"]
 
 
 def preview_would_mutate(preview_result: PreviewResult) -> bool:
+    """Return whether preview observed any structural state change."""
+
     return preview_result["would_mutate"]
 
 
 def diff_has_changes(diff: StructuralDiff) -> bool:
+    """Return whether a structural diff reports any state change."""
+
     return diff["changed"]
 
 
 def state_diff(before: State, after: State) -> StructuralDiff:
+    """Compute a structural diff between two authoritative engine states."""
+
     before_premise = before["premise"]
     after_premise = after["premise"]
     premise_changed = before_premise != after_premise
@@ -112,6 +138,8 @@ def state_diff(before: State, after: State) -> StructuralDiff:
 
 
 def step(engine: Engine, user_input: str) -> StepResult:
+    """Commit one engine transition and package the resulting decision and state."""
+
     decision = engine.step(user_input)
     return {
         "output_version": OUTPUT_VERSION,
@@ -122,19 +150,19 @@ def step(engine: Engine, user_input: str) -> StepResult:
 
 
 def preview(engine: Engine, user_input: str) -> PreviewResult:
-    state_json = engine.export_json()
-    state_before = engine.state
+    """Evaluate one transition without mutating the engine's live state.
 
-    decision: Decision | None = None
-    state_after: State | None = None
-    try:
-        decision = engine.step(user_input)
-        state_after = engine.state
-    finally:
-        engine.import_json(state_json)
+    Preview uses the same transition evaluation path as committed execution,
+    then returns the simulated decision, before/after states, and a structural
+    diff that callers can inspect before deciding whether to step.
+    """
 
-    assert decision is not None
-    assert state_after is not None
+    state_before = engine.state
+    # Preview intentionally consumes the engine's private evaluator so preview and
+    # committed execution share one transition path without making evaluation public.
+    evaluated = engine._evaluate_transition(state_before, user_input)  # noqa: SLF001
+    decision = evaluated.decision
+    state_after = evaluated.next_state
 
     diff = state_diff(state_before, state_after)
     would_mutate = diff["changed"]

context_compiler/decision_helpers.py

@@ -1,24 +1,46 @@
 """Public helpers for safer decision inspection in host-side code."""
 
-from .const import DECISION_CLARIFY, DECISION_PASSTHROUGH, DECISION_UPDATE
-from .engine import Decision, State
+from typing import TypeGuard
 
+from .const import DECISION_ERROR, DECISION_NO_DIRECTIVE, DECISION_UPDATE
+from .engine import (
+    Decision,
+    ErrorDecision,
+    NoDirectiveDecision,
+    State,
+    UpdateDecision,
+)
+
+
+def is_update(decision: Decision) -> TypeGuard[UpdateDecision]:
+    """Return whether a decision represents a successful state update."""
 
-def is_update(decision: Decision) -> bool:
     return decision["kind"] == DECISION_UPDATE
 
 
-def is_clarify(decision: Decision) -> bool:
-    return decision["kind"] == DECISION_CLARIFY
+def is_error(decision: Decision) -> TypeGuard[ErrorDecision]:
+    """Return whether a decision represents an error outcome."""
+
+    return decision["kind"] == DECISION_ERROR
 
 
-def is_passthrough(decision: Decision) -> bool:
-    return decision["kind"] == DECISION_PASSTHROUGH
+def is_no_directive(decision: Decision) -> TypeGuard[NoDirectiveDecision]:
+    """Return whether a decision reports that no directive was recognized."""
 
+    return decision["kind"] == DECISION_NO_DIRECTIVE
 
-def get_clarify_prompt(decision: Decision) -> str | None:
-    return decision["prompt_to_user"]
+
+def get_error_message(decision: Decision) -> str | None:
+    """Return the error message for an error decision, if present."""
+
+    if not is_error(decision):
+        return None
+    return decision["message"]
 
 
 def get_decision_state(decision: Decision) -> State | None:
+    """Return the updated authoritative state for an update decision, if present."""
+
+    if not is_update(decision):
+        return None
     return decision["state"]

context_compiler/engine.py

@@ -5,11 +5,13 @@ 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
 
 from .const import (
+    DECISION_ERROR,
+    DECISION_NO_DIRECTIVE,
+    DECISION_UPDATE,
     POLICY_PROHIBIT,
     POLICY_USE,
     SCHEMA_VERSION,
@@ -17,7 +19,7 @@ from .const import (
     STATE_PREMISE,
     STATE_VERSION,
 )
-from .grammar import DirectiveKind, _parse_canonical_directive
+from .grammar import DirectiveKind, decompose_directive
 
 PolicyValue = Literal["use", "prohibit"]
 
@@ -30,20 +32,33 @@ class State(TypedDict):
     version: Literal[2]
 
 
-class DecisionKind(StrEnum):
-    UPDATE = "update"
-    PASSTHROUGH = "passthrough"
-    CLARIFY = "clarify"
+class NoDirectiveDecision(TypedDict):
+    """Report that input did not match any recognized canonical directive."""
 
+    kind: Literal["no_directive"]
 
-class Decision(TypedDict):
-    kind: DecisionKind
-    state: State | None
-    prompt_to_user: str | None
+
+class UpdateDecision(TypedDict):
+    """Report a successful transition and the resulting authoritative state."""
+
+    kind: Literal["update"]
+    state: State
+
+
+class ErrorDecision(TypedDict):
+    """Report a rejected transition together with a user-facing error message."""
+
+    kind: Literal["error"]
+    message: str
+
+
+Decision = NoDirectiveDecision | UpdateDecision | ErrorDecision
 
 
 @dataclass(frozen=True)
 class Action:
+    """Represent one parsed engine action before state validation or mutation."""
+
     kind: Literal[
         "set_premise",
         "change_premise",
@@ -61,65 +76,100 @@ class Action:
     old_item: str | None = None
 
 
-_PASSTHROUGH: Decision = {
-    "kind": DecisionKind.PASSTHROUGH,
-    "state": None,
-    "prompt_to_user": None,
-}
+@dataclass(frozen=True)
+class _EvaluatedTransition:
+    decision: Decision
+    next_state: State
+
+
+_NO_DIRECTIVE: NoDirectiveDecision = {"kind": DECISION_NO_DIRECTIVE}
 
 
 def create_engine(state: State | None = None) -> "Engine":
+    """Create an engine initialized from validated state or the empty state."""
+
     return Engine(state=state)
 
 
 class Engine:
+    """Own the authoritative state and apply one directive transition at a time."""
+
     def __init__(self, state: State | None = None) -> None:
         self._state: State
         self._replace_state(_initial_state() if state is None else _load_state_obj(state))
 
     @property
     def premise(self) -> str | None:
+        """Return the current premise from authoritative state."""
+
         return self._state[STATE_PREMISE]
 
     @property
     def policies(self) -> Mapping[str, PolicyValue]:
+        """Return a defensive copy of the current policy mapping."""
+
         return deepcopy(self._state[STATE_POLICIES])
 
     @property
     def state(self) -> State:
+        """Return a defensive copy of the full authoritative state."""
+
         return deepcopy(self._state)
 
     def export_json(self) -> str:
+        """Serialize the current authoritative state to canonical JSON text."""
+
         return json.dumps(self._state, sort_keys=True, separators=(",", ":"))
 
     def import_json(self, payload: str) -> None:
+        """Replace authoritative state from previously exported JSON text.
+
+        The payload must match the current state schema and is normalized using
+        the same validation rules applied to other engine state inputs.
+        """
+
         self._replace_state(_load_state_json(payload))
 
     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
+        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
+
+    def _evaluate_transition(self, state: State, user_input: str) -> _EvaluatedTransition:
         action = _parse_directive(user_input)
         if action is None:
-            return _PASSTHROUGH.copy()
+            return _EvaluatedTransition(decision=_NO_DIRECTIVE.copy(), next_state=deepcopy(state))
 
-        clarify_decision = self._pre_mutation_clarify(action)
-        if clarify_decision is not None:
-            return clarify_decision
+        error_decision = self._pre_mutation_error(action, state=state)
+        if error_decision is not None:
+            return _EvaluatedTransition(decision=error_decision, next_state=deepcopy(state))
 
-        return self._apply_action(action)
+        next_state = self._apply_action(action, state=state)
+        return _EvaluatedTransition(decision=_update_decision(next_state), next_state=next_state)
 
     def _replace_state(self, state: State) -> None:
         self._state = state
 
-    def _pre_mutation_clarify(self, action: Action) -> Decision | None:
-        # Single clarify path: all clarify outcomes are detected before any mutation.
+    def _pre_mutation_error(self, action: Action, *, 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":
-                    return _clarify(
+                    return _error(
                         "Premise value cannot be empty.\n"
                         "Use 'set premise <value>' with a non-empty value."
                     )
-                return _clarify(
+                return _error(
                     "Premise value cannot be empty.\n"
                     "Use 'change premise to <value>' with a non-empty value."
                 )
@@ -127,7 +177,7 @@ class Engine:
         if action.kind == "remove_policy_item":
             assert action.item is not None
             if _normalize_item(action.item) == "":
-                return _clarify(
+                return _error(
                     "Policy item cannot be empty.\n"
                     "Use 'remove policy <item>' with a non-empty value."
                 )
@@ -135,36 +185,36 @@ class Engine:
         if action.kind == "use_item":
             assert action.item is not None
             if _normalize_item(action.item) == "":
-                return _clarify(
+                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 _clarify(
+                return _error(
                     "Policy item cannot be empty.\nUse 'prohibit <item>' with a non-empty value."
                 )
 
-        if action.kind == "set_premise" and self._state[STATE_PREMISE] is not None:
-            return _clarify("Premise already set.\nUse 'change premise to <value>' to modify it.")
+        if action.kind == "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 self._state[STATE_PREMISE] is None:
-            return _clarify("No premise is set.\nUse 'set premise <value>' to define one.")
+        if action.kind == "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 self._state[STATE_POLICIES].get(item_key) == POLICY_PROHIBIT:
-                return _clarify(
+            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 self._state[STATE_POLICIES].get(item_key) == POLICY_USE:
-                return _clarify(
+            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."
                 )
@@ -177,91 +227,89 @@ class Engine:
             if new_key == old_key:
                 return None
 
-            old_state = self._state[STATE_POLICIES].get(old_key)
-            new_state = self._state[STATE_POLICIES].get(new_key)
+            old_state = candidate_state[STATE_POLICIES].get(old_key)
+            new_state = candidate_state[STATE_POLICIES].get(new_key)
             if old_state == POLICY_PROHIBIT:
-                return _clarify(
+                return _error(
                     f'"{action.old_item}" is currently prohibited.\n'
                     "Submit explicit directive(s) to remove it or use a different item."
                 )
             if new_state == POLICY_PROHIBIT:
-                return _clarify(
+                return _error(
                     f'"{action.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 _clarify(
+                return _error(
                     f'"{action.old_item}" is not currently in use.\n'
                     "Replacement requires an active 'use' policy."
                 )
 
         return None
 
-    def _apply_action(self, action: Action) -> Decision:
+    def _apply_action(self, action: Action, *, state: State) -> State:
+        next_state = deepcopy(state)
         kind = action.kind
 
         if kind == "set_premise":
             assert action.value is not None
-            self._state[STATE_PREMISE] = _sanitize_premise_value(action.value)
-            return _update_decision(self._state)
+            next_state[STATE_PREMISE] = _sanitize_premise_value(action.value)
+            return next_state
 
         if kind == "change_premise":
             assert action.value is not None
-            self._state[STATE_PREMISE] = _sanitize_premise_value(action.value)
-            return _update_decision(self._state)
+            next_state[STATE_PREMISE] = _sanitize_premise_value(action.value)
+            return next_state
 
         if kind == "use_item":
             assert action.item is not None
             item_key = _normalize_item(action.item)
             # Idempotent directives are updates even if state does not change.
-            self._state[STATE_POLICIES][item_key] = POLICY_USE
-            return _update_decision(self._state)
+            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)
             # Idempotent directives are updates even if state does not change.
-            self._state[STATE_POLICIES][item_key] = POLICY_PROHIBIT
-            return _update_decision(self._state)
+            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(action.new_item, action.old_item)
-            return _update_decision(self._state)
+            self._apply_replacement_explicit(next_state, action.new_item, action.old_item)
+            return next_state
 
         if kind == "remove_policy_item":
             assert action.item is not None
             item_key = _normalize_item(action.item)
-            self._state[STATE_POLICIES].pop(item_key, None)
-            return _update_decision(self._state)
+            next_state[STATE_POLICIES].pop(item_key, None)
+            return next_state
 
         if kind == "clear_premise":
-            self._state[STATE_PREMISE] = None
-            return _update_decision(self._state)
+            next_state[STATE_PREMISE] = None
+            return next_state
 
         if kind == "reset_policies":
-            self._state[STATE_POLICIES] = {}
-            return _update_decision(self._state)
+            next_state[STATE_POLICIES] = {}
+            return next_state
 
-        self._state = _initial_state()
-        return _update_decision(self._state)
+        return _initial_state()
 
-    def _apply_replacement_explicit(self, new_item: str, old_item: str) -> None:
+    def _apply_replacement_explicit(self, state: State, new_item: str, old_item: str) -> None:
         new_key = _normalize_item(new_item)
         old_key = _normalize_item(old_item)
 
         if new_key == old_key:
             return
 
-        self._state[STATE_POLICIES].pop(old_key, None)
-        self._state[STATE_POLICIES][new_key] = POLICY_USE
+        state[STATE_POLICIES].pop(old_key, None)
+        state[STATE_POLICIES][new_key] = POLICY_USE
 
 
 def _parse_directive(user_input: str) -> Action | None:
-    # Engine semantics intentionally depend on grammar's internal parsed form.
-    # This keeps syntax authority in grammar without making the parser a public API.
-    parsed = _parse_canonical_directive(user_input)
+    parsed = decompose_directive(user_input)
     if parsed is None:
         return None
 
@@ -357,17 +405,9 @@ def _normalize_item(value: str) -> str:
     return normalized.strip()
 
 
-def _clarify(prompt: str) -> Decision:
-    return {
-        "kind": DecisionKind.CLARIFY,
-        "state": None,
-        "prompt_to_user": prompt,
-    }
+def _error(message: str) -> ErrorDecision:
+    return {"kind": DECISION_ERROR, "message": message}
 
 
-def _update_decision(state: State) -> Decision:
-    return {
-        "kind": DecisionKind.UPDATE,
-        "state": deepcopy(state),
-        "prompt_to_user": None,
-    }
+def _update_decision(state: State) -> UpdateDecision:
+    return {"kind": DECISION_UPDATE, "state": deepcopy(state)}

context_compiler/grammar.py

@@ -8,6 +8,8 @@ from types import MappingProxyType
 
 
 class DirectiveKind(StrEnum):
+    """Enumerate the supported canonical directive families."""
+
     SET_PREMISE = "set_premise"
     CHANGE_PREMISE = "change_premise"
     USE_ITEM = "use_item"
@@ -21,12 +23,16 @@ class DirectiveKind(StrEnum):
 
 @dataclass(frozen=True, slots=True)
 class ValidatedDirective:
+    """Classify text as one canonical directive kind without exposing operands."""
+
     text: str
     kind: DirectiveKind
 
 
 @dataclass(frozen=True, slots=True)
-class _GrammarParsedDirective:
+class CanonicalDirective:
+    """Represent one parsed canonical directive and its named operands."""
+
     text: str
     kind: DirectiveKind
     operands: MappingProxyType[str, str]
@@ -173,7 +179,14 @@ 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:
+def match_canonical_directive_start(text: str, start: int) -> int | None:
+    """Locate a canonical directive prefix at a given character position.
+
+    This 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.
+    """
     if start < 0 or start >= len(text):
         return None
 
@@ -230,20 +243,27 @@ def _match_directive_token(
     return index
 
 
-def _contains_multiple_canonical_directives(text: str) -> bool:
-    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.
+
+    This detects compound directive text by looking for multiple canonical
+    directive prefixes in the same input. 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)
     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 _parse_replace_use(trimmed_text: str) -> _GrammarParsedDirective | None:
+def _parse_replace_use(trimmed_text: str) -> CanonicalDirective | None:
     match = _REPLACE_RE.fullmatch(trimmed_text)
     if match is None:
         return None
@@ -258,34 +278,41 @@ def _parse_replace_use(trimmed_text: str) -> _GrammarParsedDirective | None:
     normalized_payload = _normalized_for_matching(trimmed_text)
     if normalized_payload.count(_INSTEAD_OF_DELIMITER) != 1:
         return None
-    return _GrammarParsedDirective(
+    return CanonicalDirective(
         text=trimmed_text,
         kind=DirectiveKind.REPLACE_USE,
         operands=MappingProxyType({"new_item": new_item, "old_item": old_item}),
     )
 
 
-def _parse_directive(text: str) -> _GrammarParsedDirective | None:
+def decompose_directive(text: str) -> CanonicalDirective | 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. 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 contains_multiple_canonical_directives(trimmed_text):
         return None
 
     normalized = _normalized_for_matching(trimmed_text)
 
     if normalized == "clear premise":
-        return _GrammarParsedDirective(
+        return CanonicalDirective(
             text=text, kind=DirectiveKind.CLEAR_PREMISE, operands=MappingProxyType({})
         )
     if normalized == "reset policies":
-        return _GrammarParsedDirective(
+        return CanonicalDirective(
             text=text,
             kind=DirectiveKind.RESET_POLICIES,
             operands=MappingProxyType({}),
         )
     if normalized == "clear state":
-        return _GrammarParsedDirective(
+        return CanonicalDirective(
             text=text, kind=DirectiveKind.CLEAR_STATE, operands=MappingProxyType({})
         )
 
@@ -296,7 +323,7 @@ def _parse_directive(text: str) -> _GrammarParsedDirective | None:
         value = match.group("value")
         if not _operand_has_content(value) or _operand_starts_with_token(value, "to"):
             return None
-        return _GrammarParsedDirective(
+        return CanonicalDirective(
             text=text,
             kind=DirectiveKind.SET_PREMISE,
             operands=MappingProxyType({"value": value}),
@@ -309,7 +336,7 @@ def _parse_directive(text: str) -> _GrammarParsedDirective | None:
         value = match.group("value")
         if not _operand_has_content(value):
             return None
-        return _GrammarParsedDirective(
+        return CanonicalDirective(
             text=text,
             kind=DirectiveKind.CHANGE_PREMISE,
             operands=MappingProxyType({"value": value}),
@@ -332,7 +359,7 @@ def _parse_directive(text: str) -> _GrammarParsedDirective | None:
             or _INSTEAD_OF_DELIMITER in normalized_item
         ):
             return None
-        return _GrammarParsedDirective(
+        return CanonicalDirective(
             text=text,
             kind=DirectiveKind.USE_ITEM,
             operands=MappingProxyType({"item": item}),
@@ -345,7 +372,7 @@ def _parse_directive(text: str) -> _GrammarParsedDirective | None:
         item = match.group("item")
         if not _operand_has_content(item):
             return None
-        return _GrammarParsedDirective(
+        return CanonicalDirective(
             text=text,
             kind=DirectiveKind.PROHIBIT_ITEM,
             operands=MappingProxyType({"item": item}),
@@ -358,7 +385,7 @@ def _parse_directive(text: str) -> _GrammarParsedDirective | None:
         item = match.group("item")
         if not _operand_has_content(item):
             return None
-        return _GrammarParsedDirective(
+        return CanonicalDirective(
             text=text,
             kind=DirectiveKind.REMOVE_POLICY,
             operands=MappingProxyType({"item": item}),
@@ -368,29 +395,37 @@ def _parse_directive(text: str) -> _GrammarParsedDirective | None:
 
 
 def validate_directive(text: str) -> ValidatedDirective | None:
-    parsed = _parse_directive(text)
+    """Classify whether text is a canonical directive.
+
+    This determines whether ``text`` belongs to one canonical directive family
+    and returns only the normalized semantic kind needed for classification. It
+    does not expose operands, render directives, repair malformed text, or
+    evaluate any state transition.
+    """
+    parsed = decompose_directive(text)
     if parsed is None:
         return None
     return ValidatedDirective(text=parsed.text, kind=parsed.kind)
 
 
-def _parse_canonical_directive(text: str) -> _GrammarParsedDirective | None:
-    return _parse_directive(text)
-
-
-def match_canonical_directive_start(text: str, start: int) -> int | None:
-    return _match_canonical_directive_start(text, start)
-
-
-def contains_multiple_canonical_directives(text: str) -> bool:
-    return _contains_multiple_canonical_directives(text)
-
-
 def is_canonical_directive(text: str) -> bool:
+    """Return whether text is exactly one canonical directive.
+
+    This provides boolean directive classification for callers that only need a
+    yes-or-no answer. It does not parse operands, explain rejection reasons, or
+    perform validation beyond canonical grammar recognition.
+    """
     return validate_directive(text) is not None
 
 
 def render_directive(kind: DirectiveKind, /, **operands: str) -> str:
+    """Render 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.
+    """
     try:
         normalized_kind = kind if isinstance(kind, DirectiveKind) else DirectiveKind(kind)
         spec = _DIRECTIVE_SPECS[normalized_kind]
@@ -426,9 +461,13 @@ def render_directive(kind: DirectiveKind, /, **operands: str) -> str:
 
 
 __all__ = [
+    "CanonicalDirective",
     "DirectiveKind",
     "ValidatedDirective",
+    "contains_multiple_canonical_directives",
+    "decompose_directive",
     "is_canonical_directive",
+    "match_canonical_directive_start",
     "render_directive",
     "validate_directive",
 ]

context_compiler/repl.py

@@ -1,9 +1,11 @@
+"""Command-line and REPL entry points for interacting with the engine."""
+
 import json
 import sys
 from typing import TextIO
 
 from . import __version__, create_engine
-from .const import DECISION_CLARIFY, DECISION_PASSTHROUGH
+from .const import DECISION_ERROR
 from .controller import (
     OUTPUT_VERSION,
     PreviewResult,
@@ -14,7 +16,8 @@ from .controller import (
 )
 from .controller import preview as controller_preview
 from .controller import step as controller_step
-from .engine import Decision, DecisionKind, Engine, State
+from .decision_helpers import is_error, is_no_directive, is_update
+from .engine import Decision, Engine, State
 
 _EXIT_TOKENS = {"exit", "quit"}
 _HELP_TOKENS = {"help", "?"}
@@ -44,11 +47,7 @@ def _has_embedded_newline(raw_line: str) -> bool:
 
 
 def _multi_command_decision() -> Decision:
-    return {
-        "kind": DecisionKind.CLARIFY,
-        "state": None,
-        "prompt_to_user": _MULTI_COMMAND_PROMPT,
-    }
+    return {"kind": DECISION_ERROR, "message": _MULTI_COMMAND_PROMPT}
 
 
 def _print_interactive_help(out_stream: TextIO) -> None:
@@ -69,7 +68,7 @@ def _print_interactive_help(out_stream: TextIO) -> None:
     print("  clear state", file=out_stream)
     print("Bare input behavior remains unchanged.", file=out_stream)
     print("preview is a deterministic dry-run and never mutates live state.", file=out_stream)
-    print("clarify results are immediate messages and do not reserve later input.", file=out_stream)
+    print("error results are immediate messages and do not reserve later input.", file=out_stream)
 
 
 def _render_state_lines(state: State) -> list[str]:
@@ -89,16 +88,15 @@ def _render_state_lines(state: State) -> list[str]:
 
 
 def _render_decision_lines(decision: Decision) -> list[str]:
-    kind = decision["kind"]
-    if kind == DECISION_PASSTHROUGH:
-        return ["passthrough"]
-    if kind == DECISION_CLARIFY:
-        prompt = decision["prompt_to_user"] or ""
-        prompt_lines = prompt.splitlines() if prompt else [""]
+    if is_no_directive(decision):
+        return ["no_directive"]
+    if is_error(decision):
+        message = decision["message"]
+        prompt_lines = message.splitlines() if message else [""]
         return [f"error: {prompt_lines[0]}", *prompt_lines[1:]]
 
+    assert is_update(decision)
     state = decision["state"]
-    assert state is not None
     return ["updated", *_render_state_lines(state)]
 
 
@@ -249,11 +247,19 @@ def run_repl(
     json_mode: bool = False,
     engine: Engine | None = None,
 ) -> None:
+    """Run the interactive or line-oriented REPL against one engine instance.
+
+    Interactive mode exposes command helpers such as ``state`` and ``preview``.
+    Non-interactive mode consumes one input line at a time and can optionally
+    emit NDJSON records. Preview requests are evaluated through the shared
+    controller preview path and never mutate the live engine state.
+    """
+
     active_engine = create_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)
-        print("Non-directive input is passthrough.", file=out_stream)
+        print("Non-directive input is no_directive.", file=out_stream)
 
         while True:
             line = in_stream.readline()
@@ -425,6 +431,8 @@ def run_repl(
 
 
 def main() -> int:  # pragma: no cover
+    """Run the command-line entry point and return the process exit status."""
+
     args = sys.argv[1:]
     if not args:
         run_repl(sys.stdin, sys.stdout)

{context_compiler-0.9.0.dev2.dist-info → context_compiler-0.9.0.dev4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: context-compiler
-Version: 0.9.0.dev2
+Version: 0.9.0.dev4
 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
@@ -36,7 +36,7 @@ Description-Content-Type: text/markdown
 
 Context Compiler is a deterministic conversational state authority for LLM applications.
 It handles canonical directive execution, semantic validation, deterministic
-clarify decisions, runtime semantic continuation boundaries, and structured authoritative state for
+error decisions, runtime semantic continuation boundaries, and structured authoritative state for
 the host.
 
 ## What Context Compiler provides
@@ -44,7 +44,7 @@ the host.
 Context Compiler gives hosts fixed state rules:
 
 - handle canonical explicit state changes with deterministic rules
-- clarification instead of silent overwrite for blocked/ambiguous changes
+- error instead of silent overwrite for blocked/ambiguous changes
 - preserve supported pending continuation when explicit confirmation is required
 - export and import authoritative state for host-managed persistence
 - produce structured authoritative state for downstream host decisions
@@ -89,7 +89,7 @@ Context Compiler makes state-change rules explicit so behavior stays repeatable.
 The architecture has three layers:
 
 - syntax classification decides whether input is a canonical directive, invalid
-  directive-shaped syntax, or ordinary passthrough
+  directive-shaped syntax, or ordinary no_directive
 - semantic evaluation decides whether a canonical directive updates state,
   clarifies, or no-ops
 - semantic continuation optionally preserves a deterministic blocked transition
@@ -123,7 +123,7 @@ use podman instead of docker
 - Without explicit state transition rules: behavior depends on host/model handling
 - Context Compiler: applies the deterministic resulting transition when
   `docker` is absent and `use podman` is otherwise valid; other semantic
-  conflicts may still clarify
+  conflicts may still error
 
 ### Lifecycle enforcement
 
@@ -133,7 +133,7 @@ change premise to formal tone
 ```
 
 - Without explicit transition checks: behavior depends on host/model handling
-- Context Compiler: asks for clarification and keeps saved state unchanged
+- Context Compiler: asks for error and keeps saved state unchanged
 
 ---
 
@@ -150,9 +150,9 @@ Decision
      │
      ▼
 Host Application
- ├─ clarify → ask user
- ├─ passthrough → call LLM
- └─ update → authoritative state mutated; host may call LLM with compiled state
+ ├─ error → ask user
+ ├─ no_directive → no canonical directive recognized; host decides what to do next
+ └─ update → authoritative state mutated; host may use compiled state downstream
 ```
 
 The compiler never calls the LLM. Your app decides what to do with the returned
@@ -167,8 +167,7 @@ Use Context Compiler in your host application first:
 ```python
 from context_compiler import (
     create_engine,
-    get_clarify_prompt,
-    is_clarify,
+    is_error,
     is_update,
 )
 
@@ -177,8 +176,8 @@ engine = create_engine()
 user_input = "set premise current project uses uv"
 decision = engine.step(user_input)
 
-if is_clarify(decision):
-    show_to_user(get_clarify_prompt(decision))
+if is_error(decision):
+    show_to_user(decision["message"])
 elif is_update(decision):
     messages = build_messages(engine.state, user_input)
     render(call_llm(messages))
@@ -277,22 +276,30 @@ uv run pytest
 Each user message produces a `Decision`.
 
 ```python
-class Decision(TypedDict):
-    kind: Literal["passthrough", "update", "clarify"]
-    state: dict | None
-    prompt_to_user: str | None
+class NoDirectiveDecision(TypedDict):
+    kind: Literal["no_directive"]
+
+class UpdateDecision(TypedDict):
+    kind: Literal["update"]
+    state: State
+
+class ErrorDecision(TypedDict):
+    kind: Literal["error"]
+    message: str
+
+Decision = NoDirectiveDecision | UpdateDecision | ErrorDecision
 ```
 
 Meaning:
 
 | kind | host behavior |
 | --- | --- |
-| passthrough | forward user input to LLM |
-| update | authoritative state mutated; host may call LLM with updated state |
-| clarify | show `prompt_to_user` and do not call the LLM |
+| no_directive | no canonical directive recognized; no authoritative state change; host decides what to do next |
+| update | authoritative state mutated; host may use updated state downstream |
+| error | show `message` and do not continue normal downstream processing yet |
 
-For normal app code, prefer the exported decision helpers (`is_clarify`,
-`is_update`, `is_passthrough`, `get_clarify_prompt`, `get_decision_state`)
+For normal app code, prefer the exported decision helpers (`is_error`,
+`is_update`, `is_no_directive`, `get_error_message`, `get_decision_state`)
 instead of direct key traversal.
 
 See [docs/api-reference.md](docs/api-reference.md) for the full public API
@@ -303,8 +310,8 @@ Common API entry points:
 - engine lifecycle: `create_engine(...)`, `engine.step(...)`, `engine.state`,
   `engine.premise`, `engine.policies`, `engine.export_json(...)`,
   `engine.import_json(...)`
-- decision helpers: `is_clarify(...)`, `is_update(...)`, `is_passthrough(...)`,
-  `get_clarify_prompt(...)`, `get_decision_state(...)`
+- decision helpers: `is_error(...)`, `is_update(...)`, `is_no_directive(...)`,
+  `get_error_message(...)`, `get_decision_state(...)`
 - state transport: `engine.export_json(...)`, `engine.import_json(...)`
 - controller API: `step(...)`
 - audit APIs: `preview(...)`, `state_diff(...)`
@@ -441,14 +448,14 @@ User: clear state
 
 Grammar invariant: one input may contain at most one canonical directive.
 Directive-shaped invalid input is outside the canonical language, and
-`clarify` is reserved for canonical directives that later fail semantic
+`error` is reserved for canonical directives that later fail semantic
 evaluation against authoritative state.
 
 Pending continuation is a separate runtime layer. It may exist only after a
-canonical directive reaches a supported semantic `clarify` case. It never
+canonical directive reaches a supported semantic `error` case. It never
 repairs malformed syntax or reinterprets non-canonical input as a directive.
 An absent source item in a canonical replacement directive is not, by itself,
-such a `clarify` case.
+such a `error` case.
 
 Examples:
 
@@ -496,7 +503,7 @@ boundary, see [DirectiveGrammarSpec.md](docs/DirectiveGrammarSpec.md).
 **Isn't this just prompt reinjection?**
 No. Prompt construction is one downstream use of authoritative state.
 Context Compiler is the authority layer that decides when state changes are
-allowed, when clarification is required, and how continuation state is
+allowed, when error is required, and how continuation state is
 restored. For runnable application-layer examples, see
 [`context-compiler-example-integrations`](https://github.com/rlippmann/context-compiler-example-integrations).
 
@@ -519,7 +526,7 @@ User: prohibit python_script
 
 Without an authority layer, the application must invent conflict-resolution and
 continuation rules itself. Context Compiler applies deterministic
-state-transition rules and can return clarification instead of silently
+state-transition rules and can return error instead of silently
 overwriting state.
 
 ---
@@ -531,7 +538,7 @@ overwriting state.
 - State changes only through explicit user directives or confirmation.
 - Identical input sequences produce identical compiler state.
 - Model responses never modify compiler state.
-- Ambiguous directives trigger clarification instead of changing state.
+- Ambiguous directives trigger error instead of changing state.
 - Syntax errors never create pending continuation.
 
 Behavioral tests and Hypothesis-based property tests verify these invariants.

context_compiler-0.9.0.dev4.dist-info/RECORD

@@ -0,0 +1,14 @@
+context_compiler/__init__.py,sha256=acFX-oUeMASVlReQrzmHIL04dy06kdeKaL8yEfE4RwY,1067
+context_compiler/audit.py,sha256=AhDYy1G-xc4Ov9Jnjf_k11-hqWEp5BVIFztBJWbMpBM,476
+context_compiler/const.py,sha256=WeEGDXY8lepFghH9wko0hH51oxoZQBfDnFxSyeIaaWI,465
+context_compiler/controller.py,sha256=Op1-RTKltIhSDLwfhohmH3k7x4q5XdeE7ZtKPJIzqZo,5229
+context_compiler/decision_helpers.py,sha256=1UFg3E3epSjuH_5ErXGigTTacKCs_IgTYV3kxBvdV-4,1302
+context_compiler/engine.py,sha256=igGomL7NTELgdBCB1Z0LpD2H2nA2DC-7BY4-Rb-PxPU,14721
+context_compiler/grammar.py,sha256=vWOK7Hp5_-X_2XfkhosPM4MlIyGZZ6EV3DtGsZUv-8A,16182
+context_compiler/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+context_compiler/repl.py,sha256=OWEfdK8q0dmI3QXdYwxy_pl5gfxwNesqQgkPx3ne62g,17018
+context_compiler-0.9.0.dev4.dist-info/METADATA,sha256=-XLo94NJg0qCC0PalXt92wfbhwPPH1lgPs06bjsHKk0,18346
+context_compiler-0.9.0.dev4.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+context_compiler-0.9.0.dev4.dist-info/entry_points.txt,sha256=xnk4WE9zaC2NAMIF59WD3Y_45E8aA9KH-pZ4lqSzH-U,64
+context_compiler-0.9.0.dev4.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+context_compiler-0.9.0.dev4.dist-info/RECORD,,

context_compiler-0.9.0.dev2.dist-info/RECORD

@@ -1,14 +0,0 @@
-context_compiler/__init__.py,sha256=2nVa-dMpdcT_7BfP6dTBoLWanBItTWBBQ--AXEgNA7I,977
-context_compiler/audit.py,sha256=AhDYy1G-xc4Ov9Jnjf_k11-hqWEp5BVIFztBJWbMpBM,476
-context_compiler/const.py,sha256=DgqVhkaNQ3hx2tToqHi9ZA6X6EYZj618vXacKxU-TDM,467
-context_compiler/controller.py,sha256=U9n9MVjbrIqlrcpqMkDTwvt_WC-FzOE2CZqbwcOXjQg,3858
-context_compiler/decision_helpers.py,sha256=RDl7TYeM7QywEFpWd3d4vw6fRnSfzgWXtgFFv044pe4,659
-context_compiler/engine.py,sha256=june_5yvUF8oyWJQzoL3SINqwoY8BG-MPbjgqETwSMc,13004
-context_compiler/grammar.py,sha256=PGBS5dZHx9GLHd-Emj-9TAna5PlN8MkaBMcr4HsVGLM,14165
-context_compiler/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-context_compiler/repl.py,sha256=ZjjiKSj88KHKYJiaZ_YOkCncsOY8RYrHtvXUkdYVkgs,16549
-context_compiler-0.9.0.dev2.dist-info/METADATA,sha256=Z2kBw2FJGEV2T9IOf3Va-JQv4Rf1nYdAfhnAp2qvnGY,18132
-context_compiler-0.9.0.dev2.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-context_compiler-0.9.0.dev2.dist-info/entry_points.txt,sha256=xnk4WE9zaC2NAMIF59WD3Y_45E8aA9KH-pZ4lqSzH-U,64
-context_compiler-0.9.0.dev2.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-context_compiler-0.9.0.dev2.dist-info/RECORD,,