context-compiler 0.9.0.dev12__tar.gz → 0.9.0.dev14__tar.gz

{context_compiler-0.9.0.dev12 → context_compiler-0.9.0.dev14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: context-compiler
-Version: 0.9.0.dev12
+Version: 0.9.0.dev14
 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
@@ -25,11 +25,11 @@ Description-Content-Type: text/markdown
 [![PyPI version](https://img.shields.io/pypi/v/context-compiler)](https://pypi.org/project/context-compiler/)
 [![Python versions](https://img.shields.io/pypi/pyversions/context-compiler)](https://pypi.org/project/context-compiler/)
 [![License](https://img.shields.io/pypi/l/context-compiler)](https://pypi.org/project/context-compiler/)
+[![codecov](https://codecov.io/gh/rlippmann/context-compiler/branch/main/graph/badge.svg)](https://codecov.io/gh/rlippmann/context-compiler)
 
 Context Compiler is a deterministic conversational state authority for LLM applications.
-It handles canonical directive execution, semantic validation, deterministic
-error decisions, runtime semantic continuation boundaries, and structured authoritative state for
-the host.
+It handles canonical directive execution, semantic validation, terminal error
+decisions, advisory repairs, and structured authoritative state for the host.
 
 ## What Context Compiler provides
 
@@ -37,7 +37,7 @@ Context Compiler gives hosts fixed state rules:
 
 - handle canonical explicit state changes with deterministic rules
 - error instead of silent overwrite for blocked/ambiguous changes
-- preserve supported pending continuation when explicit confirmation is required
+- return structured terminal errors with explicitly selectable advisory repairs
 - export and import authoritative state for host-managed persistence
 - produce structured authoritative state for downstream host decisions
 
@@ -84,8 +84,8 @@ The architecture has three layers:
   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
-  that needs explicit `yes` / `no`
+- semantic evaluation returns an update or a terminal error with structured
+  advisory repairs when a canonical directive conflicts with state
 
 ### Explicit directive
 
@@ -96,14 +96,14 @@ set premise concise replies
 - Base model: silently accepts / rewrites
 - Context Compiler: applies a repeatable state update
 
-### Single-directive grammar
+### Compound directive rejection
 
 ```text
 use docker and prohibit peanuts
 ```
 
 - Without an authority layer: host/model behavior varies
-- Context Compiler: treats this as invalid directive-shaped syntax, keeps authoritative state unchanged, and does not create pending continuation
+- Context Compiler: treats this as invalid directive-shaped syntax and keeps authoritative state unchanged
 
 ### State-dependent operation
 
@@ -114,7 +114,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
+  `docker` is present and `use podman` is otherwise valid; other semantic
   conflicts may still error
 
 ### Lifecycle enforcement
@@ -159,8 +159,9 @@ Use Context Compiler in your host application first:
 ```python
 from context_compiler import (
     Engine,
-    is_error,
-    is_update,
+    NoDirectiveDecision,
+    SemanticErrorDecision,
+    UpdateDecision,
 )
 
 engine = Engine()
@@ -168,16 +169,16 @@ engine = Engine()
 user_input = "set premise current project uses uv"
 decision = engine.step(user_input)
 
-if is_error(decision):
-    show_to_user(decision["message"])
-elif is_update(decision):
+if isinstance(decision, SemanticErrorDecision):
+    show_to_user(decision.message)
+elif isinstance(decision, UpdateDecision):
     messages = build_messages(
         premise=engine.premise,
         policies=engine.policies,
         user_input=user_input,
     )
     render(call_llm(messages))
-else:
+elif isinstance(decision, NoDirectiveDecision):
     render(call_llm(user_input))
 ```
 
@@ -188,7 +189,7 @@ For runnable application-layer examples, see
 [`context-compiler-example-integrations`](https://github.com/rlippmann/context-compiler-example-integrations).
 That companion repository shows enforcement points built on compiler state,
 including retrieval filtering, schema selection, tool gating, execution
-authorization, gateway middleware, runtime continuation handling, and prompt
+authorization, gateway middleware, runtime state handling, and prompt
 construction.
 
 ## Does it Work?
@@ -235,6 +236,12 @@ for non-interactive usage.
 context-compiler --json < input.txt
 ```
 
+The JSON output uses `output_version: 2`. Decision payloads expose structured
+fields: updates include `changed`; semantic errors include `failure`, the
+failed canonical `directive`, ordered advisory `repairs`, and `message`.
+These fields are a CLI projection of ephemeral Decisions, not Decision object
+serialization. Repairs are never applied automatically.
+
 Preload options load authoritative state:
 
 - `--initial-state-json` / `--initial-state-file` load saved state
@@ -266,9 +273,15 @@ uv sync --dev
 uv run pytest
 ```
 
+CI enforces 100% coverage for the core `src/context_compiler` package. The
+coverage badge represents that authoritative core-package target, not the
+entire repository.
+
 ## Decision API
 
-Each user message produces a `Decision`.
+Each user message produces one immutable `Decision` variant. Use concrete
+variants with `isinstance` or pattern matching; use `kind` when generic code
+needs the stable discriminator.
 
 ```python
 class DecisionKind(StrEnum):
@@ -276,26 +289,72 @@ class DecisionKind(StrEnum):
     UPDATE = "update"
     ERROR = "error"
 
-class Decision(TypedDict):
-    kind: DecisionKind
-    message: str | None
+Decision = NoDirectiveDecision | UpdateDecision | SemanticErrorDecision
+
+@dataclass(frozen=True, slots=True)
+class NoDirectiveDecision:
+    kind = DecisionKind.NO_DIRECTIVE
+
+@dataclass(frozen=True, slots=True)
+class UpdateDecision:
+    kind = DecisionKind.UPDATE
+    changed: bool
+
+@dataclass(frozen=True, slots=True)
+class SemanticErrorDecision:
+    kind = DecisionKind.ERROR
+    failure: SemanticFailure
+    directive: CanonicalDirective
+    repairs: tuple[CanonicalDirective, ...]
+    message: str
 ```
 
-`message` is structurally present on every `Decision`, but it is semantically
-meaningful only for `error`. For `no_directive` and `update`, `message` is
-`None`.
+`UpdateDecision.changed` reports whether authoritative state actually changed.
+An accepted idempotent directive is still an `update` with
+`changed=False`.
+
+`SemanticErrorDecision.message` is derived human-readable text. Callers should
+use `failure` for machine decisions rather than parsing the message.
+
+`directive` is the canonical directive that failed semantic evaluation.
+`repairs` is an ordered tuple of advisory canonical directives. Repairs are
+never applied automatically; a host must explicitly submit a selected repair
+through `engine.apply_directive(...)`.
+
+The normative repair mapping is:
+
+| Failure | Ordered advisory repairs |
+| --- | --- |
+| `PREMISE_ALREADY_SET` | `change premise to <requested value>` |
+| `PREMISE_NOT_SET` | `set premise <requested value>` |
+| `ITEM_PROHIBITED` | `remove policy <item>`; `use <item>` |
+| `ITEM_ALREADY_IN_USE` | `remove policy <item>`; `prohibit <item>` |
+| `REPLACEMENT_TARGET_PROHIBITED` | `remove policy <target>`; retry the original replacement directive |
+| `REPLACEMENT_SOURCE_PROHIBITED` | no repair (`()`) |
+| `REPLACEMENT_SOURCE_MISSING` | no repair (`()`) |
+
+Repairs are canonical, ordered, and advisory only. The engine never applies
+them automatically; hosts explicitly select and submit any repair they want to
+use. `message` is presentation data, so control flow must use `failure` and
+the structured directives rather than parse message text.
 
 Meaning:
 
 | kind | host behavior |
 | --- | --- |
 | 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 |
+| update | canonical directive was accepted; inspect `changed` and use updated state downstream |
+| error | canonical directive was rejected semantically; inspect `failure`, show `message`, and optionally offer `repairs` |
+
+`engine.step(...)` is the raw input boundary: it parses user input, may return
+`NoDirectiveDecision` when no canonical directive is produced, and performs
+semantic evaluation only after canonical parsing succeeds. The canonical
+execution boundary is `engine.apply_directive(...)`, which accepts only a
+`CanonicalDirective` and returns only `UpdateDecision` or
+`SemanticErrorDecision`.
 
-For normal app code, prefer the exported decision helpers (`is_error`,
-`is_update`, `is_no_directive`, `get_error_message`)
-instead of direct key traversal.
+Grammar failures do not produce semantic errors. A semantic error is possible
+only after a canonical directive has parsed successfully.
 
 See [docs/api-reference.md](docs/api-reference.md) for the full public API
 reference.
@@ -305,8 +364,8 @@ Common API entry points:
 - engine lifecycle: `Engine()`, `engine.step(...)`,
   `engine.premise`, `engine.policies`, `engine.export_json(...)`,
   `engine.import_json(...)`
-- decision helpers: `is_error(...)`, `is_update(...)`, `is_no_directive(...)`,
-  `get_error_message(...)`
+- decision variants: `NoDirectiveDecision`, `UpdateDecision`,
+  `SemanticErrorDecision`, `SemanticFailure`
 - state transport: `engine.export_json(...)`, `engine.import_json(...)`
 
 ---
@@ -387,8 +446,8 @@ the compiler.
 
 - They transport **authoritative state only**
 - Hosts own any broader interaction or session workflow around that state
-- Pending continuation, if supported by the active engine contract, remains a
-  runtime semantic concept rather than a documented persisted artifact
+- Decision objects and advisory repairs are not persisted; persistence carries
+  authoritative state only
 
 ---
 
@@ -426,16 +485,20 @@ User: reset policies
 User: clear state
 ```
 
-Grammar invariant: one input may contain at most one canonical directive.
+Grammar invariant: a single input never applies more than one canonical
+directive.
 Directive-shaped invalid input is outside the canonical language, and
 `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 `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 itself a
-semantic `error` case and does not authorize degradation to plain `use`.
+A semantic error is a terminal result for the current input. It leaves
+authoritative state unchanged and returns the failure classification, failed
+canonical directive, ordered advisory repairs, and presentation message.
+Repairs are canonical directives. They are advisory only, are never applied
+automatically, and require explicit host selection and submission through
+`engine.apply_directive(...)`. An absent source item in a canonical replacement
+directive is a semantic `error` and does not authorize degradation to plain
+`use`.
 
 Examples:
 
@@ -447,18 +510,25 @@ clear state
 
 Invalid:
 use docker and prohibit peanuts
-set premise vegetarian and use docker
 clear state then set premise new project
+
+Premise payload (opaque):
+set premise vegetarian and use docker
 ```
 
+Policy compounds such as `use docker and prohibit peanuts` remain invalid;
+premise `VALUE` is opaque and may contain directive-like words.
+
 Quote behavior follows the current grammar literally:
 
 ```text
-Passthrough:
+Passthrough (`no_directive`):
 "use docker and prohibit peanuts"
 
-Invalid:
+Invalid directive:
 use "docker and prohibit peanuts"
+
+Canonical directive (`set premise`):
 set premise "use docker and prohibit peanuts"
 ```
 
@@ -483,8 +553,8 @@ 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 error is required, and how continuation state is
-restored. For runnable application-layer examples, see
+allowed, when a terminal error is required, and which advisory repairs are
+available. For runnable application-layer examples, see
 [`context-compiler-example-integrations`](https://github.com/rlippmann/context-compiler-example-integrations).
 
 Human-facing interpretation is a separate concern. If you want to recognize
@@ -505,8 +575,8 @@ 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 error instead of silently
+repair rules itself. Context Compiler applies deterministic state-transition
+rules and can return a terminal error instead of silently
 overwriting state.
 
 ---
@@ -515,11 +585,11 @@ overwriting state.
 
 ### Guarantees
 
-- State changes only through explicit user directives or confirmation.
+- State changes only through canonical directives that pass semantic evaluation.
 - Identical input sequences produce identical compiler state.
 - Model responses never modify compiler state.
 - Ambiguous directives trigger error instead of changing state.
-- Syntax errors never create pending continuation.
+- Syntax errors never produce semantic errors or state changes.
 
 Behavioral tests and Hypothesis-based property tests verify these invariants.
 

{context_compiler-0.9.0.dev12 → context_compiler-0.9.0.dev14}/README.md

@@ -3,11 +3,11 @@
 [![PyPI version](https://img.shields.io/pypi/v/context-compiler)](https://pypi.org/project/context-compiler/)
 [![Python versions](https://img.shields.io/pypi/pyversions/context-compiler)](https://pypi.org/project/context-compiler/)
 [![License](https://img.shields.io/pypi/l/context-compiler)](https://pypi.org/project/context-compiler/)
+[![codecov](https://codecov.io/gh/rlippmann/context-compiler/branch/main/graph/badge.svg)](https://codecov.io/gh/rlippmann/context-compiler)
 
 Context Compiler is a deterministic conversational state authority for LLM applications.
-It handles canonical directive execution, semantic validation, deterministic
-error decisions, runtime semantic continuation boundaries, and structured authoritative state for
-the host.
+It handles canonical directive execution, semantic validation, terminal error
+decisions, advisory repairs, and structured authoritative state for the host.
 
 ## What Context Compiler provides
 
@@ -15,7 +15,7 @@ Context Compiler gives hosts fixed state rules:
 
 - handle canonical explicit state changes with deterministic rules
 - error instead of silent overwrite for blocked/ambiguous changes
-- preserve supported pending continuation when explicit confirmation is required
+- return structured terminal errors with explicitly selectable advisory repairs
 - export and import authoritative state for host-managed persistence
 - produce structured authoritative state for downstream host decisions
 
@@ -62,8 +62,8 @@ The architecture has three layers:
   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
-  that needs explicit `yes` / `no`
+- semantic evaluation returns an update or a terminal error with structured
+  advisory repairs when a canonical directive conflicts with state
 
 ### Explicit directive
 
@@ -74,14 +74,14 @@ set premise concise replies
 - Base model: silently accepts / rewrites
 - Context Compiler: applies a repeatable state update
 
-### Single-directive grammar
+### Compound directive rejection
 
 ```text
 use docker and prohibit peanuts
 ```
 
 - Without an authority layer: host/model behavior varies
-- Context Compiler: treats this as invalid directive-shaped syntax, keeps authoritative state unchanged, and does not create pending continuation
+- Context Compiler: treats this as invalid directive-shaped syntax and keeps authoritative state unchanged
 
 ### State-dependent operation
 
@@ -92,7 +92,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
+  `docker` is present and `use podman` is otherwise valid; other semantic
   conflicts may still error
 
 ### Lifecycle enforcement
@@ -137,8 +137,9 @@ Use Context Compiler in your host application first:
 ```python
 from context_compiler import (
     Engine,
-    is_error,
-    is_update,
+    NoDirectiveDecision,
+    SemanticErrorDecision,
+    UpdateDecision,
 )
 
 engine = Engine()
@@ -146,16 +147,16 @@ engine = Engine()
 user_input = "set premise current project uses uv"
 decision = engine.step(user_input)
 
-if is_error(decision):
-    show_to_user(decision["message"])
-elif is_update(decision):
+if isinstance(decision, SemanticErrorDecision):
+    show_to_user(decision.message)
+elif isinstance(decision, UpdateDecision):
     messages = build_messages(
         premise=engine.premise,
         policies=engine.policies,
         user_input=user_input,
     )
     render(call_llm(messages))
-else:
+elif isinstance(decision, NoDirectiveDecision):
     render(call_llm(user_input))
 ```
 
@@ -166,7 +167,7 @@ For runnable application-layer examples, see
 [`context-compiler-example-integrations`](https://github.com/rlippmann/context-compiler-example-integrations).
 That companion repository shows enforcement points built on compiler state,
 including retrieval filtering, schema selection, tool gating, execution
-authorization, gateway middleware, runtime continuation handling, and prompt
+authorization, gateway middleware, runtime state handling, and prompt
 construction.
 
 ## Does it Work?
@@ -213,6 +214,12 @@ for non-interactive usage.
 context-compiler --json < input.txt
 ```
 
+The JSON output uses `output_version: 2`. Decision payloads expose structured
+fields: updates include `changed`; semantic errors include `failure`, the
+failed canonical `directive`, ordered advisory `repairs`, and `message`.
+These fields are a CLI projection of ephemeral Decisions, not Decision object
+serialization. Repairs are never applied automatically.
+
 Preload options load authoritative state:
 
 - `--initial-state-json` / `--initial-state-file` load saved state
@@ -244,9 +251,15 @@ uv sync --dev
 uv run pytest
 ```
 
+CI enforces 100% coverage for the core `src/context_compiler` package. The
+coverage badge represents that authoritative core-package target, not the
+entire repository.
+
 ## Decision API
 
-Each user message produces a `Decision`.
+Each user message produces one immutable `Decision` variant. Use concrete
+variants with `isinstance` or pattern matching; use `kind` when generic code
+needs the stable discriminator.
 
 ```python
 class DecisionKind(StrEnum):
@@ -254,26 +267,72 @@ class DecisionKind(StrEnum):
     UPDATE = "update"
     ERROR = "error"
 
-class Decision(TypedDict):
-    kind: DecisionKind
-    message: str | None
+Decision = NoDirectiveDecision | UpdateDecision | SemanticErrorDecision
+
+@dataclass(frozen=True, slots=True)
+class NoDirectiveDecision:
+    kind = DecisionKind.NO_DIRECTIVE
+
+@dataclass(frozen=True, slots=True)
+class UpdateDecision:
+    kind = DecisionKind.UPDATE
+    changed: bool
+
+@dataclass(frozen=True, slots=True)
+class SemanticErrorDecision:
+    kind = DecisionKind.ERROR
+    failure: SemanticFailure
+    directive: CanonicalDirective
+    repairs: tuple[CanonicalDirective, ...]
+    message: str
 ```
 
-`message` is structurally present on every `Decision`, but it is semantically
-meaningful only for `error`. For `no_directive` and `update`, `message` is
-`None`.
+`UpdateDecision.changed` reports whether authoritative state actually changed.
+An accepted idempotent directive is still an `update` with
+`changed=False`.
+
+`SemanticErrorDecision.message` is derived human-readable text. Callers should
+use `failure` for machine decisions rather than parsing the message.
+
+`directive` is the canonical directive that failed semantic evaluation.
+`repairs` is an ordered tuple of advisory canonical directives. Repairs are
+never applied automatically; a host must explicitly submit a selected repair
+through `engine.apply_directive(...)`.
+
+The normative repair mapping is:
+
+| Failure | Ordered advisory repairs |
+| --- | --- |
+| `PREMISE_ALREADY_SET` | `change premise to <requested value>` |
+| `PREMISE_NOT_SET` | `set premise <requested value>` |
+| `ITEM_PROHIBITED` | `remove policy <item>`; `use <item>` |
+| `ITEM_ALREADY_IN_USE` | `remove policy <item>`; `prohibit <item>` |
+| `REPLACEMENT_TARGET_PROHIBITED` | `remove policy <target>`; retry the original replacement directive |
+| `REPLACEMENT_SOURCE_PROHIBITED` | no repair (`()`) |
+| `REPLACEMENT_SOURCE_MISSING` | no repair (`()`) |
+
+Repairs are canonical, ordered, and advisory only. The engine never applies
+them automatically; hosts explicitly select and submit any repair they want to
+use. `message` is presentation data, so control flow must use `failure` and
+the structured directives rather than parse message text.
 
 Meaning:
 
 | kind | host behavior |
 | --- | --- |
 | 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 |
+| update | canonical directive was accepted; inspect `changed` and use updated state downstream |
+| error | canonical directive was rejected semantically; inspect `failure`, show `message`, and optionally offer `repairs` |
+
+`engine.step(...)` is the raw input boundary: it parses user input, may return
+`NoDirectiveDecision` when no canonical directive is produced, and performs
+semantic evaluation only after canonical parsing succeeds. The canonical
+execution boundary is `engine.apply_directive(...)`, which accepts only a
+`CanonicalDirective` and returns only `UpdateDecision` or
+`SemanticErrorDecision`.
 
-For normal app code, prefer the exported decision helpers (`is_error`,
-`is_update`, `is_no_directive`, `get_error_message`)
-instead of direct key traversal.
+Grammar failures do not produce semantic errors. A semantic error is possible
+only after a canonical directive has parsed successfully.
 
 See [docs/api-reference.md](docs/api-reference.md) for the full public API
 reference.
@@ -283,8 +342,8 @@ Common API entry points:
 - engine lifecycle: `Engine()`, `engine.step(...)`,
   `engine.premise`, `engine.policies`, `engine.export_json(...)`,
   `engine.import_json(...)`
-- decision helpers: `is_error(...)`, `is_update(...)`, `is_no_directive(...)`,
-  `get_error_message(...)`
+- decision variants: `NoDirectiveDecision`, `UpdateDecision`,
+  `SemanticErrorDecision`, `SemanticFailure`
 - state transport: `engine.export_json(...)`, `engine.import_json(...)`
 
 ---
@@ -365,8 +424,8 @@ the compiler.
 
 - They transport **authoritative state only**
 - Hosts own any broader interaction or session workflow around that state
-- Pending continuation, if supported by the active engine contract, remains a
-  runtime semantic concept rather than a documented persisted artifact
+- Decision objects and advisory repairs are not persisted; persistence carries
+  authoritative state only
 
 ---
 
@@ -404,16 +463,20 @@ User: reset policies
 User: clear state
 ```
 
-Grammar invariant: one input may contain at most one canonical directive.
+Grammar invariant: a single input never applies more than one canonical
+directive.
 Directive-shaped invalid input is outside the canonical language, and
 `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 `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 itself a
-semantic `error` case and does not authorize degradation to plain `use`.
+A semantic error is a terminal result for the current input. It leaves
+authoritative state unchanged and returns the failure classification, failed
+canonical directive, ordered advisory repairs, and presentation message.
+Repairs are canonical directives. They are advisory only, are never applied
+automatically, and require explicit host selection and submission through
+`engine.apply_directive(...)`. An absent source item in a canonical replacement
+directive is a semantic `error` and does not authorize degradation to plain
+`use`.
 
 Examples:
 
@@ -425,18 +488,25 @@ clear state
 
 Invalid:
 use docker and prohibit peanuts
-set premise vegetarian and use docker
 clear state then set premise new project
+
+Premise payload (opaque):
+set premise vegetarian and use docker
 ```
 
+Policy compounds such as `use docker and prohibit peanuts` remain invalid;
+premise `VALUE` is opaque and may contain directive-like words.
+
 Quote behavior follows the current grammar literally:
 
 ```text
-Passthrough:
+Passthrough (`no_directive`):
 "use docker and prohibit peanuts"
 
-Invalid:
+Invalid directive:
 use "docker and prohibit peanuts"
+
+Canonical directive (`set premise`):
 set premise "use docker and prohibit peanuts"
 ```
 
@@ -461,8 +531,8 @@ 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 error is required, and how continuation state is
-restored. For runnable application-layer examples, see
+allowed, when a terminal error is required, and which advisory repairs are
+available. For runnable application-layer examples, see
 [`context-compiler-example-integrations`](https://github.com/rlippmann/context-compiler-example-integrations).
 
 Human-facing interpretation is a separate concern. If you want to recognize
@@ -483,8 +553,8 @@ 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 error instead of silently
+repair rules itself. Context Compiler applies deterministic state-transition
+rules and can return a terminal error instead of silently
 overwriting state.
 
 ---
@@ -493,11 +563,11 @@ overwriting state.
 
 ### Guarantees
 
-- State changes only through explicit user directives or confirmation.
+- State changes only through canonical directives that pass semantic evaluation.
 - Identical input sequences produce identical compiler state.
 - Model responses never modify compiler state.
 - Ambiguous directives trigger error instead of changing state.
-- Syntax errors never create pending continuation.
+- Syntax errors never produce semantic errors or state changes.
 
 Behavioral tests and Hypothesis-based property tests verify these invariants.