context-compiler 0.9.0.dev9__tar.gz → 0.9.0.dev11__tar.gz

{context_compiler-0.9.0.dev9 → context_compiler-0.9.0.dev11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: context-compiler
-Version: 0.9.0.dev9
+Version: 0.9.0.dev11
 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
@@ -414,10 +414,9 @@ Replacement:
 User: use podman instead of docker
 ```
 
-If `docker` is absent from saved state, that does not make the directive
-pending. The user's intended resulting state is still unambiguous, so the
-replacement follows the deterministic `use podman` transition when otherwise
-semantically valid.
+If `docker` is absent from saved state, that is a semantic `error`.
+Canonical replacement requires an active existing source `use` policy and
+does not degrade to plain `use podman`.
 
 Removal and reset:
 
@@ -435,8 +434,8 @@ 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 not, by itself,
-such a `error` case.
+An absent source item in a canonical replacement directive is itself a
+semantic `error` case and does not authorize degradation to plain `use`.
 
 Examples:
 

{context_compiler-0.9.0.dev9 → context_compiler-0.9.0.dev11}/README.md

@@ -392,10 +392,9 @@ Replacement:
 User: use podman instead of docker
 ```
 
-If `docker` is absent from saved state, that does not make the directive
-pending. The user's intended resulting state is still unambiguous, so the
-replacement follows the deterministic `use podman` transition when otherwise
-semantically valid.
+If `docker` is absent from saved state, that is a semantic `error`.
+Canonical replacement requires an active existing source `use` policy and
+does not degrade to plain `use podman`.
 
 Removal and reset:
 
@@ -413,8 +412,8 @@ 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 not, by itself,
-such a `error` case.
+An absent source item in a canonical replacement directive is itself a
+semantic `error` case and does not authorize degradation to plain `use`.
 
 Examples:
 

{context_compiler-0.9.0.dev9 → context_compiler-0.9.0.dev11}/demos/08_llm_replacement_precondition.py

@@ -1,10 +1,10 @@
-"""Demo 8: missing-source replacement applies deterministically from authoritative state."""
+"""Demo 8: missing-source replacement fails without mutating authoritative state."""
 
 from collections.abc import Mapping
 
 from context_compiler import (
     Engine,
-    is_update,
+    is_error,
 )
 from demos.common import (
     build_baseline_messages,
@@ -22,7 +22,7 @@ from demos.common import (
 )
 from demos.llm_client import complete_messages
 
-DEMO_NAME = "08_replacement_precondition — missing-source replacement applies deterministically"
+DEMO_NAME = "08_replacement_precondition — missing-source replacement requires active source"
 USER_INPUT = "use podman instead of docker"
 
 
@@ -69,38 +69,38 @@ def main() -> None:
     reinjected_output = complete_messages(reinjected_messages)
     print_model_output("Reinjected-state", reinjected_output)
 
-    if is_update(decision):
+    if is_error(decision):
         print_messages("compiler-mediated (full)", [])
-        mediated_output = "[no call] authoritative state applied deterministic replacement update"
+        mediated_output = "[no call] authoritative state blocked replacement without source use"
         print_model_output("Compiler-mediated (full)", mediated_output)
     else:
         print_messages("compiler-mediated (full)", [])
-        mediated_output = "[no call] expected update was not produced"
+        mediated_output = "[no call] expected semantic replacement error was not produced"
         print_model_output("Compiler-mediated (full)", mediated_output)
 
     compacted_turns, compacted_state, compacted_prompt = compact_user_turns(user_inputs)
-    if compacted_prompt is None:
+    if compacted_prompt is not None:
         print_messages("compiler-mediated + compact", [])
-        compact_output = "[no call] compaction preserved deterministic state update"
+        compact_output = "[no call] unexpected error was produced during compaction"
         print_model_output("Compiler-mediated + compact", compact_output)
     else:
         print_messages("compiler-mediated + compact", [])
-        compact_output = "[no call] unexpected error was produced during compaction"
+        compact_output = "[no call] compaction preserved replacement error without state mutation"
         print_model_output("Compiler-mediated + compact", compact_output)
 
     premise, policies = observe_engine(engine)
     compacted_premise, compacted_policies = state_observations(compacted_state)
-    state_applied = not _is_initial_authoritative_state(premise=premise, policies=policies)
-    compact_state_applied = not _is_initial_authoritative_state(
+    state_preserved = _is_initial_authoritative_state(premise=premise, policies=policies)
+    compact_state_preserved = _is_initial_authoritative_state(
         premise=compacted_premise,
         policies=compacted_policies,
     )
-    compact_no_pending = compacted_prompt is None
+    compact_error_preserved = compacted_prompt is not None
 
     baseline_has_authoritative_precondition = False
     reinjected_has_authoritative_precondition = False
-    compiler_pass = is_update(decision) and state_applied
-    compact_pass = compacted_prompt is None and compact_state_applied and compact_no_pending
+    compiler_pass = is_error(decision) and state_preserved
+    compact_pass = compact_error_preserved and compact_state_preserved
 
     print_host_check(
         "BASELINE_AUTHORITATIVE_PRECONDITION",
@@ -114,12 +114,12 @@ def main() -> None:
     )
     print_host_check(
         "COMPILER_BLOCKED_INVALID_REPLACEMENT",
-        yes_no(is_update(decision)),
+        yes_no(is_error(decision)),
         context="compiler-mediated",
     )
     print_host_check(
-        "COMPILER_STATE_APPLIED",
-        yes_no(state_applied),
+        "COMPILER_STATE_PRESERVED",
+        yes_no(state_preserved),
         context="compiler-mediated",
     )
 
@@ -130,18 +130,18 @@ def main() -> None:
         compiler_pass=compiler_pass,
         compiler_compact_pass=compact_pass,
         expected=(
-            "missing-source replacement should deterministically apply the resulting use update "
-            "without pending continuation"
+            "missing-source replacement should return semantic error without mutating "
+            "authoritative state"
         ),
         actual=(
-            "compiler applied deterministic replacement update; baseline and reinjected paths "
-            "still lack authoritative state enforcement"
+            "compiler blocked missing-source replacement without mutating state; baseline and "
+            "reinjected paths still lack authoritative state enforcement"
             if compiler_pass and compact_pass
-            else "compiler did not consistently apply deterministic replacement behavior"
+            else "compiler did not consistently enforce the replacement source precondition"
         ),
         passed=compiler_pass and compact_pass,
-        result_pass="missing-source replacement applied deterministically",
-        result_fail="missing-source replacement did not apply deterministically",
+        result_pass="missing-source replacement was rejected without mutation",
+        result_fail="missing-source replacement was not rejected correctly",
     )
 
 

{context_compiler-0.9.0.dev9 → context_compiler-0.9.0.dev11}/demos/09_llm_confirmation_no_directive.py

@@ -1,11 +1,11 @@
-"""Demo 9: confirmation-style followups remain ordinary no_directive."""
+"""Demo 9: replacement errors do not create confirmation-style followup state."""
 
 from collections.abc import Mapping
 
 from context_compiler import (
     Engine,
+    is_error,
     is_no_directive,
-    is_update,
 )
 from demos.common import (
     build_baseline_messages,
@@ -24,8 +24,7 @@ from demos.common import (
 from demos.llm_client import complete_messages
 
 DEMO_NAME = (
-    "09_confirmation_no_directive_boundary — "
-    "missing-source replacement does not create a confirmation state"
+    "09_confirmation_no_directive_boundary — replacement errors do not create a confirmation state"
 )
 TURN_1 = "use podman instead of docker"
 TURN_2 = "maybe"
@@ -34,10 +33,6 @@ INITIAL_PREMISE: str | None = None
 INITIAL_POLICIES: dict[str, str] = {}
 
 
-def _has_podman_use(policies: Mapping[str, str]) -> bool:
-    return policies.get("podman") == "use"
-
-
 def _is_initial_authoritative_state(*, premise: str | None, policies: Mapping[str, str]) -> bool:
     return premise == INITIAL_PREMISE and dict(policies) == INITIAL_POLICIES
 
@@ -50,12 +45,17 @@ def main() -> None:
     first = engine.step(TURN_1)
     premise, policies = observe_engine(engine)
     print_decision("turn 1", first, premise=premise, policies=policies)
-    state_applied_after_first = _has_podman_use(policies)
+    state_preserved_after_first = _is_initial_authoritative_state(
+        premise=premise, policies=policies
+    )
 
     second = engine.step(TURN_2)
     premise, policies = observe_engine(engine)
     print_decision("turn 2", second, premise=premise, policies=policies)
-    state_preserved_after_second = _has_podman_use(policies)
+    state_preserved_after_second = _is_initial_authoritative_state(
+        premise=premise,
+        policies=policies,
+    )
 
     third = engine.step(TURN_3)
     premise, policies = observe_engine(engine)
@@ -96,7 +96,7 @@ def main() -> None:
     compacted_turns, compacted_state, compacted_prompt = compact_user_turns(user_inputs)
     if compacted_prompt is not None:
         print_messages("compiler-mediated + compact", [])
-        compact_output = f"[no call] error required: {compacted_prompt}"
+        compact_output = f"[no call] replacement error preserved: {compacted_prompt}"
         print_model_output("Compiler-mediated + compact", compact_output)
     else:
         print_messages("compiler-mediated + compact", [])
@@ -105,32 +105,30 @@ def main() -> None:
         )
         print_model_output("Compiler-mediated + compact", compact_output)
 
-    deterministic_initial_update = is_update(first) and state_applied_after_first
+    deterministic_initial_error = is_error(first) and state_preserved_after_first
     unrelated_followup_no_directive = is_no_directive(second) and state_preserved_after_second
     confirmation_token_not_consumed = is_no_directive(third)
     premise, policies = observe_engine(engine)
-    deterministic_final_state = _has_podman_use(policies)
+    deterministic_final_state = _is_initial_authoritative_state(premise=premise, policies=policies)
     _, compacted_policies = state_observations(compacted_state)
 
     baseline_has_confirmation_state_machine = False
     reinjected_has_confirmation_state_machine = False
 
     compiler_pass = (
-        deterministic_initial_update
+        deterministic_initial_error
         and unrelated_followup_no_directive
         and confirmation_token_not_consumed
         and deterministic_final_state
     )
 
     compact_pass = (
-        compacted_prompt is None
-        and compacted_turns == [TURN_2, TURN_3]
-        and _has_podman_use(compacted_policies)
+        compacted_prompt is not None and compacted_turns == [TURN_1] and compacted_policies == {}
     )
 
     print_host_check(
-        "DETERMINISTIC_INITIAL_UPDATE",
-        yes_no(deterministic_initial_update),
+        "DETERMINISTIC_INITIAL_ERROR",
+        yes_no(deterministic_initial_error),
         context="compiler-mediated",
     )
     print_host_check(
@@ -144,7 +142,7 @@ def main() -> None:
         context="compiler-mediated",
     )
     print_host_check(
-        "FINAL_POLICY_PODMAN_PRESENT",
+        "FINAL_STATE_UNCHANGED",
         yes_no(deterministic_final_state),
         context="compiler-mediated",
     )
@@ -156,19 +154,18 @@ def main() -> None:
         compiler_pass=compiler_pass,
         compiler_compact_pass=compact_pass,
         expected=(
-            "missing-source replacement should apply without creating an engine-owned "
-            "confirmation state, and later yes/no-style input should remain ordinary "
-            "no_directive"
+            "replacement error should not create an engine-owned confirmation state, "
+            "and later yes/no-style input should remain ordinary no_directive"
         ),
         actual=(
-            "compiler applied deterministic replacement update and treated later inputs as "
-            "ordinary no_directive"
+            "compiler returned semantic error and treated later inputs as ordinary "
+            "no_directive without mutating state"
             if compiler_pass and compact_pass
             else "compiler did not consistently preserve the confirmation-no_directive boundary"
         ),
         passed=compiler_pass and compact_pass,
-        result_pass="missing-source replacement stayed outside engine-owned confirmation state",
-        result_fail="missing-source replacement still behaved like engine-owned confirmation state",
+        result_pass="replacement error stayed outside engine-owned confirmation state",
+        result_fail="replacement error still behaved like engine-owned confirmation state",
     )
 
 

{context_compiler-0.9.0.dev9 → context_compiler-0.9.0.dev11}/pyproject.toml

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

{context_compiler-0.9.0.dev9 → context_compiler-0.9.0.dev11}/src/context_compiler/engine.py

@@ -176,7 +176,7 @@ class Engine:
                     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}:
+            if old_state != POLICY_USE:
                 return _error(
                     f'"{old_item}" is not currently in use.\n'
                     "Replacement requires an active 'use' policy."
@@ -276,7 +276,12 @@ def _load_state_obj(raw: object) -> _State:
     if not isinstance(policies, dict):
         raise ValueError("Invalid state payload.")
 
+    sanitized_premise = None if premise is None else _sanitize_premise_value(premise)
+    if premise is not None and sanitized_premise == "":
+        raise ValueError("Invalid state payload.")
+
     normalized_policies: dict[str, PolicyValue] = {}
+    seen_policy_sources: dict[str, str] = {}
     for key, value in policies.items():
         if not isinstance(key, str):
             raise ValueError("Invalid state payload.")
@@ -285,10 +290,14 @@ def _load_state_obj(raw: object) -> _State:
         normalized_key = _normalize_item(key)
         if normalized_key == "":
             raise ValueError("Invalid state payload.")
+        prior_source = seen_policy_sources.get(normalized_key)
+        if prior_source is not None and prior_source != key:
+            raise ValueError("Invalid state payload.")
+        seen_policy_sources[normalized_key] = key
         normalized_policies[normalized_key] = value
 
     return {
-        STATE_PREMISE: None if premise is None else _sanitize_premise_value(premise),
+        STATE_PREMISE: sanitized_premise,
         STATE_POLICIES: dict(sorted(normalized_policies.items())),
         STATE_VERSION: SCHEMA_VERSION,
     }

{context_compiler-0.9.0.dev9 → context_compiler-0.9.0.dev11}/src/context_compiler/grammar.py

@@ -1,7 +1,7 @@
 """Immutable canonical grammar helpers for Context Compiler directives."""
 
 import re
-from collections.abc import Callable
+from collections.abc import Callable, Mapping
 from dataclasses import dataclass
 from enum import StrEnum
 from types import MappingProxyType
@@ -33,14 +33,24 @@ class DirectiveSyntaxFailure(StrEnum):
 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.
+    ``text`` is the canonical serialized directive text derived from ``kind``
+    and ``operands``.
     """
 
-    text: str
     kind: DirectiveKind
     operands: MappingProxyType[str, str]
 
+    def __post_init__(self) -> None:
+        normalized_kind = _normalize_directive_kind(self.kind)
+        normalized_operands = _normalize_canonical_operands(normalized_kind, self.operands)
+        object.__setattr__(self, "kind", normalized_kind)
+        object.__setattr__(self, "operands", MappingProxyType(normalized_operands))
+
+    @property
+    def text(self) -> str:
+        """Return the canonical serialized directive text."""
+        return _serialize_canonical_directive(self.kind, self.operands)
+
 
 @dataclass(frozen=True, slots=True)
 class InvalidDirectiveSyntax:
@@ -54,16 +64,31 @@ class InvalidDirectiveSyntax:
 @dataclass(frozen=True, slots=True)
 class _DirectiveSpec:
     kind: DirectiveKind
+    canonical_start: str
     operand_names: tuple[str, ...]
     exact_text: str | None
     renderer: Callable[[MappingProxyType[str, str]], str]
 
 
-_SET_PREMISE_PREFIX = "set premise "
-_CHANGE_PREMISE_PREFIX = "change premise to "
-_USE_PREFIX = "use "
-_PROHIBIT_PREFIX = "prohibit "
-_REMOVE_POLICY_PREFIX = "remove policy "
+@dataclass(frozen=True, slots=True)
+class DirectiveMetadata:
+    """Describe one canonical directive family without exposing parser internals."""
+
+    kind: DirectiveKind
+    canonical_start: str
+    operand_names: tuple[str, ...]
+
+
+_SET_PREMISE_START = "set premise"
+_CHANGE_PREMISE_START = "change premise to"
+_USE_START = "use"
+_PROHIBIT_START = "prohibit"
+_REMOVE_POLICY_START = "remove policy"
+_SET_PREMISE_PREFIX = f"{_SET_PREMISE_START} "
+_CHANGE_PREMISE_PREFIX = f"{_CHANGE_PREMISE_START} "
+_USE_PREFIX = f"{_USE_START} "
+_PROHIBIT_PREFIX = f"{_PROHIBIT_START} "
+_REMOVE_POLICY_PREFIX = f"{_REMOVE_POLICY_START} "
 _CLEAR_PREMISE_TEXT = "clear premise"
 _RESET_POLICIES_TEXT = "reset policies"
 _CLEAR_STATE_TEXT = "clear state"
@@ -81,39 +106,6 @@ _REPLACE_RE = re.compile(
     r"(?i)^use[ \t]+(?P<new_item>.*?)[ \t]+instead[ \t]+of[ \t]+(?P<old_item>.+)$"
 )
 
-_PREFIX_DIRECTIVE_STARTS: tuple[tuple[str, bool], ...] = (
-    (_CHANGE_PREMISE_PREFIX.removesuffix(" "), True),
-    (_SET_PREMISE_PREFIX.removesuffix(" "), True),
-    (_REMOVE_POLICY_PREFIX.removesuffix(" "), True),
-    (_PROHIBIT_PREFIX.removesuffix(" "), 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:],
-)
-
 
 def _render_with_prefix(
     prefix: str, operand_name: str
@@ -140,54 +132,63 @@ _DIRECTIVE_SPECS = MappingProxyType(
     {
         DirectiveKind.SET_PREMISE: _DirectiveSpec(
             kind=DirectiveKind.SET_PREMISE,
+            canonical_start=_SET_PREMISE_START,
             operand_names=("value",),
             exact_text=None,
             renderer=_render_with_prefix(_SET_PREMISE_PREFIX, "value"),
         ),
         DirectiveKind.CHANGE_PREMISE: _DirectiveSpec(
             kind=DirectiveKind.CHANGE_PREMISE,
+            canonical_start=_CHANGE_PREMISE_START,
             operand_names=("value",),
             exact_text=None,
             renderer=_render_with_prefix(_CHANGE_PREMISE_PREFIX, "value"),
         ),
         DirectiveKind.USE_ITEM: _DirectiveSpec(
             kind=DirectiveKind.USE_ITEM,
+            canonical_start=_USE_START,
             operand_names=("item",),
             exact_text=None,
             renderer=_render_with_prefix(_USE_PREFIX, "item"),
         ),
         DirectiveKind.PROHIBIT_ITEM: _DirectiveSpec(
             kind=DirectiveKind.PROHIBIT_ITEM,
+            canonical_start=_PROHIBIT_START,
             operand_names=("item",),
             exact_text=None,
             renderer=_render_with_prefix(_PROHIBIT_PREFIX, "item"),
         ),
         DirectiveKind.REMOVE_POLICY: _DirectiveSpec(
             kind=DirectiveKind.REMOVE_POLICY,
+            canonical_start=_REMOVE_POLICY_START,
             operand_names=("item",),
             exact_text=None,
             renderer=_render_with_prefix(_REMOVE_POLICY_PREFIX, "item"),
         ),
         DirectiveKind.REPLACE_USE: _DirectiveSpec(
             kind=DirectiveKind.REPLACE_USE,
+            canonical_start=_USE_START,
             operand_names=("new_item", "old_item"),
             exact_text=None,
             renderer=_render_replace_use,
         ),
         DirectiveKind.CLEAR_PREMISE: _DirectiveSpec(
             kind=DirectiveKind.CLEAR_PREMISE,
+            canonical_start=_CLEAR_PREMISE_TEXT,
             operand_names=(),
             exact_text=_CLEAR_PREMISE_TEXT,
             renderer=_render_exact(_CLEAR_PREMISE_TEXT),
         ),
         DirectiveKind.RESET_POLICIES: _DirectiveSpec(
             kind=DirectiveKind.RESET_POLICIES,
+            canonical_start=_RESET_POLICIES_TEXT,
             operand_names=(),
             exact_text=_RESET_POLICIES_TEXT,
             renderer=_render_exact(_RESET_POLICIES_TEXT),
         ),
         DirectiveKind.CLEAR_STATE: _DirectiveSpec(
             kind=DirectiveKind.CLEAR_STATE,
+            canonical_start=_CLEAR_STATE_TEXT,
             operand_names=(),
             exact_text=_CLEAR_STATE_TEXT,
             renderer=_render_exact(_CLEAR_STATE_TEXT),
@@ -196,6 +197,64 @@ _DIRECTIVE_SPECS = MappingProxyType(
 )
 
 
+def _starts_with_descriptor(spec: _DirectiveSpec) -> tuple[str, bool]:
+    return (spec.canonical_start, bool(spec.operand_names))
+
+
+def _unique_start_descriptors(specs: tuple[_DirectiveSpec, ...]) -> tuple[tuple[str, bool], ...]:
+    descriptors: list[tuple[str, bool]] = []
+    seen: set[tuple[str, bool]] = set()
+    for spec in specs:
+        descriptor = _starts_with_descriptor(spec)
+        if descriptor not in seen:
+            seen.add(descriptor)
+            descriptors.append(descriptor)
+    return tuple(descriptors)
+
+
+_CANONICAL_START_ORDER = (
+    DirectiveKind.CHANGE_PREMISE,
+    DirectiveKind.SET_PREMISE,
+    DirectiveKind.REMOVE_POLICY,
+    DirectiveKind.RESET_POLICIES,
+    DirectiveKind.CLEAR_PREMISE,
+    DirectiveKind.CLEAR_STATE,
+    DirectiveKind.PROHIBIT_ITEM,
+    DirectiveKind.USE_ITEM,
+)
+
+_CANONICAL_DIRECTIVE_STARTS = _unique_start_descriptors(
+    tuple(_DIRECTIVE_SPECS[kind] for kind in _CANONICAL_START_ORDER)
+)
+
+_DIRECTIVE_FAMILY_STARTS = (
+    (_CHANGE_PREMISE_FAMILY, True),
+    *_unique_start_descriptors(
+        tuple(
+            _DIRECTIVE_SPECS[kind]
+            for kind in (
+                DirectiveKind.SET_PREMISE,
+                DirectiveKind.REMOVE_POLICY,
+                DirectiveKind.RESET_POLICIES,
+                DirectiveKind.CLEAR_PREMISE,
+                DirectiveKind.CLEAR_STATE,
+                DirectiveKind.PROHIBIT_ITEM,
+                DirectiveKind.USE_ITEM,
+            )
+        )
+    ),
+)
+
+_PUBLIC_DIRECTIVE_METADATA = tuple(
+    DirectiveMetadata(
+        kind=spec.kind,
+        canonical_start=spec.canonical_start,
+        operand_names=spec.operand_names,
+    )
+    for spec in _DIRECTIVE_SPECS.values()
+)
+
+
 def _trim_ascii_whitespace(text: str) -> str:
     return text.strip(_ASCII_WHITESPACE)
 
@@ -316,7 +375,6 @@ def _parse_replace_use(trimmed_text: str) -> CanonicalDirective | None:
     if normalized_payload.count(_INSTEAD_OF_DELIMITER) != 1:
         return None
     return CanonicalDirective(
-        text=trimmed_text,
         kind=DirectiveKind.REPLACE_USE,
         operands=MappingProxyType({"new_item": new_item, "old_item": old_item}),
     )
@@ -335,6 +393,74 @@ def _invalid_directive_syntax(
     )
 
 
+def _normalize_directive_kind(kind: DirectiveKind | str) -> DirectiveKind:
+    try:
+        return kind if isinstance(kind, DirectiveKind) else DirectiveKind(kind)
+    except ValueError as exc:
+        raise ValueError(f"Unsupported directive kind: {kind!r}") from exc
+
+
+def _normalize_canonical_operands(
+    kind: DirectiveKind,
+    operands: Mapping[str, str],
+) -> dict[str, str]:
+    spec = _DIRECTIVE_SPECS[kind]
+    expected_names = set(spec.operand_names)
+    actual_names = set(operands)
+    unexpected_names = actual_names - expected_names
+    missing_names = expected_names - actual_names
+    if missing_names:
+        missing = ", ".join(sorted(missing_names))
+        raise ValueError(f"Missing required operands for {kind.value}: {missing}")
+    if unexpected_names:
+        unexpected = ", ".join(sorted(unexpected_names))
+        raise ValueError(f"Unexpected operands for {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.")
+        if not _operand_has_content(raw_value):
+            raise ValueError(f"Operand {name!r} for {kind.value} cannot be empty.")
+        normalized_operands[name] = raw_value
+
+    _validate_operand_constraints(kind, normalized_operands)
+    _validate_rendered_canonical_shape(kind, normalized_operands)
+    return normalized_operands
+
+
+def _validate_operand_constraints(kind: DirectiveKind, operands: Mapping[str, str]) -> None:
+    if kind is DirectiveKind.SET_PREMISE:
+        value = operands["value"]
+        if _operand_starts_with_token(value, "to"):
+            raise ValueError(f"Operands do not produce a canonical {kind.value} directive.")
+        return
+
+    if kind is DirectiveKind.USE_ITEM:
+        item = operands["item"]
+        normalized_item = _normalized_for_matching(item)
+        if normalized_item == "instead of" or normalized_item.startswith("instead of "):
+            raise ValueError(f"Operands do not produce a canonical {kind.value} directive.")
+        if _INSTEAD_OF_DELIMITER in normalized_item:
+            raise ValueError(f"Operands do not produce a canonical {kind.value} directive.")
+        return
+
+    if kind is DirectiveKind.REPLACE_USE:
+        new_item = operands["new_item"]
+        old_item = operands["old_item"]
+        if _INSTEAD_OF_DELIMITER in _normalized_for_matching(
+            new_item
+        ) or _INSTEAD_OF_DELIMITER in _normalized_for_matching(old_item):
+            raise ValueError(f"Operands do not produce a canonical {kind.value} directive.")
+
+
+def _validate_rendered_canonical_shape(kind: DirectiveKind, operands: Mapping[str, str]) -> None:
+    rendered = _serialize_canonical_directive(kind, MappingProxyType(dict(operands)))
+    if _contains_multiple_canonical_directives(rendered):
+        raise ValueError(f"Operands do not produce a canonical {kind.value} directive.")
+
+
 def decompose_directive(text: str) -> CanonicalDirective | InvalidDirectiveSyntax | None:
     """Parse one canonical directive into its semantic kind and operands.
 
@@ -356,19 +482,14 @@ def decompose_directive(text: str) -> CanonicalDirective | InvalidDirectiveSynta
     normalized = _normalized_for_matching(trimmed_text)
 
     if normalized == _CLEAR_PREMISE_TEXT:
-        return CanonicalDirective(
-            text=text, kind=DirectiveKind.CLEAR_PREMISE, operands=MappingProxyType({})
-        )
+        return CanonicalDirective(kind=DirectiveKind.CLEAR_PREMISE, operands=MappingProxyType({}))
     if normalized == _RESET_POLICIES_TEXT:
         return CanonicalDirective(
-            text=text,
             kind=DirectiveKind.RESET_POLICIES,
             operands=MappingProxyType({}),
         )
     if normalized == _CLEAR_STATE_TEXT:
-        return CanonicalDirective(
-            text=text, kind=DirectiveKind.CLEAR_STATE, operands=MappingProxyType({})
-        )
+        return CanonicalDirective(kind=DirectiveKind.CLEAR_STATE, operands=MappingProxyType({}))
 
     if normalized == "set premise":
         return _invalid_directive_syntax(
@@ -391,7 +512,6 @@ def decompose_directive(text: str) -> CanonicalDirective | InvalidDirectiveSynta
                 directive_kind=DirectiveKind.SET_PREMISE,
             )
         return CanonicalDirective(
-            text=text,
             kind=DirectiveKind.SET_PREMISE,
             operands=MappingProxyType({"value": value}),
         )
@@ -419,7 +539,6 @@ def decompose_directive(text: str) -> CanonicalDirective | InvalidDirectiveSynta
                 missing_operand="value",
             )
         return CanonicalDirective(
-            text=text,
             kind=DirectiveKind.CHANGE_PREMISE,
             operands=MappingProxyType({"value": value}),
         )
@@ -469,7 +588,6 @@ def decompose_directive(text: str) -> CanonicalDirective | InvalidDirectiveSynta
                 directive_kind=DirectiveKind.USE_ITEM,
             )
         return CanonicalDirective(
-            text=text,
             kind=DirectiveKind.USE_ITEM,
             operands=MappingProxyType({"item": item}),
         )
@@ -497,7 +615,6 @@ def decompose_directive(text: str) -> CanonicalDirective | InvalidDirectiveSynta
                 missing_operand="item",
             )
         return CanonicalDirective(
-            text=text,
             kind=DirectiveKind.PROHIBIT_ITEM,
             operands=MappingProxyType({"item": item}),
         )
@@ -525,7 +642,6 @@ def decompose_directive(text: str) -> CanonicalDirective | InvalidDirectiveSynta
                 missing_operand="item",
             )
         return CanonicalDirective(
-            text=text,
             kind=DirectiveKind.REMOVE_POLICY,
             operands=MappingProxyType({"item": item}),
         )
@@ -533,46 +649,37 @@ def decompose_directive(text: str) -> CanonicalDirective | InvalidDirectiveSynta
     return _invalid_directive_syntax(DirectiveSyntaxFailure.MALFORMED_DIRECTIVE)
 
 
-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)
-        spec = _DIRECTIVE_SPECS[normalized_kind]
-    except (KeyError, ValueError) as exc:
-        raise ValueError(f"Unsupported directive kind: {kind!r}") from exc
+def get_directive_metadata() -> tuple[DirectiveMetadata, ...]:
+    """Return immutable public directive metadata derived from internal specs."""
 
-    expected_names = set(spec.operand_names)
-    actual_names = set(operands)
-    unexpected_names = actual_names - expected_names
-    missing_names = expected_names - actual_names
-    if missing_names:
-        missing = ", ".join(sorted(missing_names))
-        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 {normalized_kind.value}: {unexpected}")
+    return _PUBLIC_DIRECTIVE_METADATA
 
-    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 {normalized_kind.value} must be a string.")
-        if raw_value.strip() == "":
-            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 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
+def _serialize_canonical_directive(
+    kind: DirectiveKind | str, operands: MappingProxyType[str, str]
+) -> str:
+    """Serialize a validated semantic directive without reparsing it."""
+    normalized_kind = _normalize_directive_kind(kind)
+    spec = _DIRECTIVE_SPECS[normalized_kind]
+
+    return spec.renderer(operands)
+
+
+def _render_directive(kind: DirectiveKind | str, /, **operands: str) -> str:
+    """Produce canonical directive text from a semantic kind and operands."""
+    normalized_kind = _normalize_directive_kind(kind)
+    return CanonicalDirective(
+        kind=normalized_kind,
+        operands=MappingProxyType(dict(operands)),
+    ).text
 
 
 __all__ = [
     "DirectiveKind",
     "DirectiveSyntaxFailure",
+    "DirectiveMetadata",
     "CanonicalDirective",
     "InvalidDirectiveSyntax",
+    "get_directive_metadata",
     "decompose_directive",
 ]