pretense-py 0.2.0__py3-none-any.whl

pretense/__init__.py

@@ -0,0 +1,82 @@
+"""Pretense: Unified State-Machine Verification & Fake Synthesis Engine."""
+
+import os
+import sys
+from pathlib import Path
+
+_curr = Path(__file__).resolve().parent
+_REPO_ROOT = _curr
+while _curr and _curr != _curr.parent:
+    if (_curr / "pyproject.toml").is_file():
+        _REPO_ROOT = _curr
+        break
+    _curr = _curr.parent
+
+for _p in (_REPO_ROOT, _REPO_ROOT / "autofab_python", _REPO_ROOT / "autofab", _REPO_ROOT / "pretense"):
+    _str_p = str(_p)
+    if _p.is_dir() and _str_p not in sys.path:
+        sys.path.insert(0, _str_p)
+
+from pretense.parts.pretense.lib.pretense import (
+    AmbiguousTransitionError,
+    Domain,
+    EnsuresCheck,
+    FakeAdapter,
+    NoMatchingTransitionError,
+    NotBound,
+    NotBoundType,
+    Outcome,
+    PretenseEngine,
+    PretenseError,
+    PretenseRunResult,
+    PretenseRunnerConfig,
+    PretenseSpecificationError,
+    Raised,
+    RequiresCheck,
+    StateMachine,
+    StateMachineProto,
+    TraceStep,
+    Transition,
+    TransitionContext,
+    Value,
+    transition,
+)
+from pretense.collections import PretenseDict, PretenseSet, choose_weighted, make_tup
+from pretense.context import get_current_draw, with_draw
+from pretense.compiler import compile_hypothesis_test_case
+from pretense.synthesis import synthesize_unit_test
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "AmbiguousTransitionError",
+    "Domain",
+    "EnsuresCheck",
+    "FakeAdapter",
+    "NoMatchingTransitionError",
+    "NotBound",
+    "NotBoundType",
+    "Outcome",
+    "PretenseDict",
+    "PretenseEngine",
+    "PretenseError",
+    "PretenseRunResult",
+    "PretenseRunnerConfig",
+    "PretenseSet",
+    "PretenseSpecificationError",
+    "Raised",
+    "RequiresCheck",
+    "StateMachine",
+    "StateMachineProto",
+    "TraceStep",
+    "Transition",
+    "TransitionContext",
+    "Value",
+    "choose_weighted",
+    "compile_hypothesis_test_case",
+    "get_current_draw",
+    "make_tup",
+    "synthesize_unit_test",
+    "transition",
+    "with_draw",
+]

pretense/cli.py

@@ -0,0 +1,35 @@
+"""CLI runner for Pretense state machines (uv run pretense)."""
+
+import os
+import sys
+from pathlib import Path
+
+_curr = Path(__file__).resolve().parent
+_REPO_ROOT = _curr
+while _curr and _curr != _curr.parent:
+    if (_curr / "pyproject.toml").is_file():
+        _REPO_ROOT = _curr
+        break
+    _curr = _curr.parent
+
+for _p in (_REPO_ROOT, _REPO_ROOT / "autofab_python", _REPO_ROOT / "autofab", _REPO_ROOT / "pretense"):
+    _str_p = str(_p)
+    if _p.is_dir() and _str_p not in sys.path:
+        sys.path.insert(0, _str_p)
+
+# Also discover support/lib if run within a role workspace
+_curr = Path.cwd().resolve()
+while _curr and _curr != _curr.parent:
+    if (_curr / "support" / "lib").is_dir():
+        _sup = str(_curr / "support" / "lib")
+        if _sup not in sys.path:
+            sys.path.insert(0, _sup)
+        break
+    _curr = _curr.parent
+
+from pretense.parts.pretense.lib.pretense_impl import main, run_pretense_cli
+
+if __name__ == "__main__":
+    sys.exit(main())
+
+__all__ = ["main", "run_pretense_cli"]

pretense/collections.py

@@ -0,0 +1,206 @@
+"""Bidirectional collection helpers and recognizers/generators for Pretense."""
+
+import random
+from collections import deque
+from typing import Any, Callable, Dict, List, Optional, Set, Tuple, TypeVar, Union
+
+from pretense.context import get_current_draw
+from pretense.sentinels import NotBound, NotBoundType
+
+T = TypeVar("T")
+K = TypeVar("K")
+V = TypeVar("V")
+
+
+def make_tup(*choosers: Callable[..., Any]) -> Callable[..., Optional[Tuple[Any, ...]]]:
+    """Compose multiple argument recognizers/generators into a single joint tuple chooser.
+    
+    If any individual chooser returns None, the combined chooser returns None (rejection).
+    """
+    def combined(state: Any, this: Any, *args: Any) -> Optional[Tuple[Any, ...]]:
+        res: List[Any] = []
+        for chooser, arg in zip(choosers, args):
+            val = chooser(state, this, arg)
+            if val is None:
+                return None
+            res.append(val)
+        return tuple(res)
+    return combined
+
+
+def choose_weighted(*weighted_options: Tuple[float, Callable[[Any], Any]]) -> Any:
+    """Statistical selection across weighted alternatives.
+    
+    Under Hypothesis, uses st.frequency() to allow full byte-stream shrinking.
+    Outside Hypothesis, falls back to random.choices.
+    """
+    draw = get_current_draw()
+    if draw is not None:
+        try:
+            import hypothesis.strategies as st
+            st_mod: Any = st
+            freq_strategies = []
+            for weight, builder in weighted_options:
+                int_weight = max(1, int(round(weight * 100)))
+                try:
+                    strat = builder(st_mod)
+                    if isinstance(strat, st.SearchStrategy):
+                        freq_strategies.append((int_weight, strat))
+                    else:
+                        freq_strategies.append((int_weight, st.just(strat)))
+                except Exception:
+                    freq_strategies.append((int_weight, st.just(builder(random))))
+            return draw(st_mod.frequency(freq_strategies))
+        except ImportError:
+            pass
+
+    # Deterministic fallback / PRNG
+    weights = [w for w, _ in weighted_options]
+    builders = [b for _, b in weighted_options]
+    chosen_builder = random.choices(builders, weights=weights, k=1)[0]
+    return chosen_builder(random)
+
+
+class PretenseSet(Set[T]):
+    """State collection tracking rolling tombstones and providing bidirectional helpers."""
+
+    def __init__(self, elements: Any = ()) -> None:
+        super().__init__(elements)
+        self._tombstones: deque[T] = deque(maxlen=50)
+
+    def remove(self, element: T) -> None:
+        super().remove(element)
+        self._tombstones.append(element)
+
+    def discard(self, element: object) -> None:
+        if element in self:
+            super().discard(element)
+            self._tombstones.append(element)  # type: ignore
+
+    def get_in(self, val: Union[T, NotBoundType]) -> Optional[T]:
+        """Recognize membership or generate an existing element from the set."""
+        if isinstance(val, NotBoundType):
+            if not self:
+                return None
+            draw = get_current_draw()
+            if draw is not None:
+                try:
+                    import hypothesis.strategies as st
+                    return draw(st.sampled_from(list(self)))
+                except ImportError:
+                    pass
+            return next(iter(self))
+        return val if val in self else None
+
+    def get_not_in(self, val: Union[T, NotBoundType], prefix: str = "item_") -> Optional[T]:
+        """Recognize non-membership or generate an absent element across 4 tiers."""
+        if isinstance(val, NotBoundType):
+            draw = get_current_draw()
+            if draw is not None:
+                try:
+                    import hypothesis.strategies as st
+                    # Tier 1: The Graveyard (Tombstone History) - 40% probability if available
+                    if self._tombstones and draw(st.booleans()) and draw(st.booleans()):
+                        candidate = draw(st.sampled_from(list(self._tombstones)))
+                        if candidate not in self:
+                            return candidate
+
+                    # Tier 2: Near-Miss Mutations - 30% probability if string elements exist
+                    if self and all(isinstance(x, str) for x in self) and draw(st.booleans()):
+                        base = str(draw(st.sampled_from(list(self))))
+                        mutation_type = draw(st.integers(0, 3))
+                        if mutation_type == 0:
+                            candidate_str = base.upper() if base.islower() else base.lower()
+                        elif mutation_type == 1:
+                            candidate_str = base + " "
+                        elif mutation_type == 2:
+                            candidate_str = "_" + base
+                        else:
+                            candidate_str = base + "_alt"
+                        if candidate_str not in self:
+                            return candidate_str  # type: ignore
+
+                    # Tier 3: Open Universe Fuzzing
+                    if not self or all(isinstance(x, str) for x in self):
+                        fresh_str = draw(st.text(min_size=1, max_size=10).filter(lambda s: s not in self))
+                        return fresh_str  # type: ignore
+                except ImportError:
+                    pass
+
+            # Tier 4: Deterministic Sequential Fallback
+            idx = len(self)
+            candidate = f"{prefix}{idx}"
+            while candidate in self:
+                idx += 1
+                candidate = f"{prefix}{idx}"
+            return candidate  # type: ignore
+
+        return val if val not in self else None
+
+    def get_subset(self, val: Union[Set[T], NotBoundType]) -> Optional[Set[T]]:
+        """Recognize a subset or generate a valid subset from this set."""
+        if isinstance(val, NotBoundType):
+            draw = get_current_draw()
+            if draw is not None:
+                try:
+                    import hypothesis.strategies as st
+                    return set(draw(st.lists(st.sampled_from(list(self)), unique=True))) if self else set()
+                except ImportError:
+                    pass
+            return set()
+        return val if isinstance(val, (set, frozenset)) and val.issubset(self) else None
+
+
+class PretenseDict(Dict[K, V]):
+    """Dictionary collection tracking key tombstones for bidirectional key recognition/generation."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._tombstones: deque[K] = deque(maxlen=50)
+
+    def __delitem__(self, key: K) -> None:
+        super().__delitem__(key)
+        self._tombstones.append(key)
+
+    def pop(self, key: K, *args: Any) -> V:
+        res = super().pop(key, *args)
+        self._tombstones.append(key)
+        return res
+
+    def get_key_in(self, key: Union[K, NotBoundType]) -> Optional[K]:
+        """Recognize key existence or generate an existing key."""
+        if isinstance(key, NotBoundType):
+            if not self:
+                return None
+            draw = get_current_draw()
+            if draw is not None:
+                try:
+                    import hypothesis.strategies as st
+                    return draw(st.sampled_from(list(self.keys())))
+                except ImportError:
+                    pass
+            return next(iter(self.keys()))
+        return key if key in self else None
+
+    def get_key_not_in(self, key: Union[K, NotBoundType], prefix: str = "key_") -> Optional[K]:
+        """Recognize key absence or generate an absent key."""
+        if isinstance(key, NotBoundType):
+            draw = get_current_draw()
+            if draw is not None:
+                try:
+                    import hypothesis.strategies as st
+                    if self._tombstones and draw(st.booleans()):
+                        cand = draw(st.sampled_from(list(self._tombstones)))
+                        if cand not in self:
+                            return cand
+                    if not self or all(isinstance(k, str) for k in self.keys()):
+                        return draw(st.text(min_size=1, max_size=10).filter(lambda s: s not in self))  # type: ignore
+                except ImportError:
+                    pass
+            idx = len(self)
+            cand_str = f"{prefix}{idx}"
+            while cand_str in self:
+                idx += 1
+                cand_str = f"{prefix}{idx}"
+            return cand_str  # type: ignore
+        return key if key not in self else None

pretense/compiler.py

@@ -0,0 +1,47 @@
+"""Hypothesis stateful test case generation for Pretense prototypes."""
+
+from typing import Any, List, Optional
+import pretense.parts.pretense.lib.pretense_impl as _impl
+
+_ACTIVE_STEP: Any = None
+_ACTIVE_TRACE: List[Any] = []
+
+
+def get_active_step() -> Any:
+    global _ACTIVE_STEP
+    if _ACTIVE_STEP is not None:
+        return _ACTIVE_STEP
+    return _impl.get_active_step()
+
+
+def get_active_trace() -> List[Any]:
+    global _ACTIVE_TRACE
+    if _ACTIVE_TRACE:
+        return list(_ACTIVE_TRACE)
+    return _impl.get_active_trace()
+
+
+def format_active_step_diagnostic(*args: Any, **kwargs: Any) -> Optional[str]:
+    global _ACTIVE_STEP, _ACTIVE_TRACE
+    if _ACTIVE_STEP is not None:
+        lines = [
+            f"Active Pretense Transition: '{_ACTIVE_STEP.transition_name}' (method: {_ACTIVE_STEP.target_name or '<seeding>'})",
+            f"Arguments: {_ACTIVE_STEP.args!r}",
+        ]
+        if len(_ACTIVE_TRACE) > 1:
+            lines.append(f"Preceding Steps ({len(_ACTIVE_TRACE) - 1}):")
+            for i, step in enumerate(_ACTIVE_TRACE[:-1], 1):
+                args_str = ", ".join(repr(a) for a in step.args)
+                lines.append(f"  {i}. {step.transition_name}({args_str})")
+        return "\n".join(lines)
+    return _impl.format_active_step_diagnostic(*args, **kwargs)
+
+
+compile_hypothesis_test_case = _impl.compile_hypothesis_test_case
+
+__all__ = [
+    "compile_hypothesis_test_case",
+    "format_active_step_diagnostic",
+    "get_active_step",
+    "get_active_trace",
+]

pretense/context.py

@@ -0,0 +1,9 @@
+"""Dynamic scope context for Hypothesis draw integration in Pretense."""
+
+from pretense.parts.pretense.lib.pretense import (
+    DrawContext,
+    get_current_draw,
+    with_draw,
+)
+
+__all__ = ["DrawContext", "get_current_draw", "with_draw"]

pretense/fake.py

@@ -0,0 +1,5 @@
+"""In-memory Fake adapter synthesis."""
+
+from pretense.parts.pretense.lib.pretense import FakeAdapter
+
+__all__ = ["FakeAdapter"]

pretense/parts/autofab.toml

@@ -0,0 +1,4 @@
+# autofab.toml
+# Methodology binding for pretense/parts
+
+methodology = "//autofab_python"

pretense/parts/pretense/__init__.py

@@ -0,0 +1 @@
+# Pretense part package marker.

pretense/parts/pretense/description.md

@@ -0,0 +1,20 @@
+# Pretense Part (`update_python_with_ai/parts/pretense`)
+
+## Purpose
+
+The **pretense** part provides Cleanroom's unified state-machine-driven testing, verification, and fake synthesis engine.
+
+Software verification driven purely by example-based testing or AST statement coverage suffers from severe blind spots in LLM-generated code: high statement coverage often greenlights state desynchronization, omission bugs, and boundary condition regressions. Pretense solves this by expressing behavioral specifications as executable state transition models. Powered by property-based conjecture search and minimal counterexample shrinking, Pretense verifies state-transition invariants, synthesizes zero-maintenance interface fakes, enforces execution watchdogs against infinite loops, and drives differential testing between specifications and implementations.
+
+## Key Components & Specifications
+
+- [`pretense.md`](file:///Users/seanmcdirmid/projects/cleanroom/update_python_with_ai/parts/pretense/high/pretense.md): Defines the core state machine abstractions, sentinels, outcome descriptors, transition models, stateful collection structures, hypothesis draw contexts, fake adapter contracts, and the `PretenseEngine` interface.
+- [`pretense_impl.md`](file:///Users/seanmcdirmid/projects/cleanroom/update_python_with_ai/parts/pretense/high/pretense_impl.md): Realizes the dynamic Hypothesis state machine compiler, active step diagnostic tracking, minimal counterexample unit test synthesis, watchdog timeout enforcement, test discovery, and the `pretense` command-line test runner.
+
+## How It Is Used by Other Parts
+
+Pretense serves as Cleanroom's primary state-machine testing and contract verification engine:
+- **`cleanroom_roles.toml`**: Configures the `pretense`, `pretense_qa`, and `pretense_coverage` roles to invoke `uv run pretense ...` across all parts.
+- **`update_python_with_ai/support`**: `pretense_lint.py` enforces structural rules on `*_pretense.py` files and validates that state machines conform to Pretense contracts.
+- **`benchmark`**: Provisions `.env` watchdogs (`PYTHONFAULTHANDLER=1`, `PRETENSE_TIMEOUT=45.0`) and provides baseline developer models with Pretense verification tools.
+- **All constituent parts**: Every Cleanroom part maintains executable state machine specifications under `parts/<name>/pretense/` targeting the part's implementation modules.

pretense/parts/pretense/high/pretense.md

@@ -0,0 +1,23 @@
+# pretense interface component
+
+## Purpose
+
+The pretense interface component defines the declarative state machine abstractions, sentinels, collection models, transition specifications, fake adapters, and verification engine contracts for stateful software testing in Cleanroom.
+
+Example-based testing and AST statement coverage frequently miss critical state desynchronizations, boundary regressions, and omitted invariant logic in neural-generated code. By defining stateful systems as executable state transition models rather than static unit test sequences, this component enables automated property-based exploration, invariant checking across arbitrary operation orderings, and automatic fake synthesis. Centralizing these state abstractions prevents fragmentation across test harnesses and ensures that specification contracts remain mathematically verifiable.
+
+**Out of scope:** Subprocess invocation, filesystem scanning, and shell argument parsing; these are handled by other components.
+
+## Types and Behavior
+
+A system's *pretense engine* coordinates state machine compilation, test suite execution, and fake generation.
+
+A *pretense sentinel* distinguishes unprovided inputs and specific runtime states from standard program values. The sentinel *not bound* indicates that a parameter was omitted by a caller. An *execution outcome* encapsulates the result of evaluating an operation against an implementation under test. A *value outcome* wraps a successful return value. A *raised outcome* wraps an expected or intercepted exception instance. A *specification error* indicates that a state machine contract, transition invariant, or antecedent predicate was violated.
+
+A *draw context* provides a dynamically bound generator for sampling values during property-based test exploration. A *pretense collection* provides an observable state container that tracks mutations and verifies invariants. A *pretense dictionary* provides an observable key-value mapping with existence assertions and weighted key selection. A *pretense set* provides an observable unique item container with element sampling and existence assertions.
+
+A *state transition* defines a single atomic operation step within a state machine. Each state transition specifies a *requires* condition that must hold before the operation executes, an *argument binder* that generates or recognizes operation arguments, an expected return outcome or contracted exception, an *ensures* postcondition verified against the concrete singleton under test during real test execution, and an *update* condition that applies reference model state mutations. An *argument domain* unifies generative sampling with analytical validation for an operation parameter. A domain produces randomized values conforming to its specification during property fuzzing and validates whether arbitrary candidate values belong to its domain during adapter dispatch. Argument domains support scalar categoricals, discrete ranges, lexical patterns, structural data types, dependent parameter domains whose boundaries derive dynamically from preceding arguments, and constructive perturbations that derive candidate values from anchor values via targeted near-boundary mutations. An argument binder binds transition arguments exclusively from explicit domains, native collections, ranges, patterns, data types, dependent domain functions, and keyword domain mappings. An unresolved domain placeholder enforces explicit domain definition by failing at runtime if left unspecialized. An argument binder generates operation arguments from direct values, callables, domains, or property-based search strategies treated directly as values, automatically drawing randomized instances from active draw contexts during property fuzzing while drawing default examples when evaluated outside fuzzing contexts. A *transition context* provides methods for specifying requires preconditions, argument binders, expected returns, contracted exceptions, ensures postconditions, and model updates for a single transition method. A transition context provides a *check helper* for evaluating requirements without exception overhead and evaluating postconditions against immediate and collaborating singletons under test during real test runs while omitting ensures verification during fake adapter dispatch. A transition context strictly enforces mutual exclusivity between expected returns and contracted exceptions: declaring both on the same transition context raises an invalid transition definition error. When synthesizing fake exceptions from contracted exception types, the transition context safely instantiates exception classes that declare mandatory positional parameters. A *transition decorator* registers a transition method against a target singleton class operation.
+
+A *state machine* declares the complete behavioral contract of an interface or implementation through a collection of state transitions and system invariants. A state machine stores singletons under test as direct references in its state representation to drive implementation logic under test, or provides synthesized in-memory fake adapters backed by the shared reference model. A *fake adapter* acts as a dynamic test double conforming to an interface protocol, delegating method invocations directly to matching state transitions and verifying preconditions. A *trace step* records the operation name, arguments, and outcome of an executed transition within a state machine run.
+
+A *runner configuration* specifies test execution parameters including target paths, fuzzing iterations, statement coverage thresholds, execution timeout durations, and active step diagnostic reporting. A *run result* reports execution metrics, including passed test counts, failure counts, statement coverage percentages, and synthesized counterexamples.

pretense/parts/pretense/high/pretense_impl.md

@@ -0,0 +1,23 @@
+# pretense_impl implementation component
+
+implements: pretense
+
+## Purpose
+
+The pretense_impl implementation component realizes the state machine compiler, diagnostic tracer, fake adapter proxy, execution watchdog, and test runner for the pretense engine.
+
+Executing stateful test suites against neural implementations requires robust test case synthesis, minimal counterexample shrinking, and failsafe execution bounds. Without automatic shrinking and active step tracing, developers and models struggle to debug complex multi-step failures. Without execution watchdogs, unbounded loops or blocking operations hang test runners indefinitely. This component bridges abstract state models to property-based test engines, synthesizes reproducible unit test files from minimized counterexamples, and guarantees execution termination through signal-based watchdogs.
+
+**Out of scope:** Static type checking, code generation templates, and language server protocols; these are handled by other components.
+
+## Types and Behavior
+
+The *pretense engine realization* implements the pretense engine service on the system tier.
+
+A *state machine compiler* translates declarative state machine specifications into executable property-based test suites. The compiler inspects each declared state transition on a state machine, binding requires guards to test generation preconditions, and evaluating ensures postconditions against the concrete system under test after invocation and outcome recognition, while applying model update mutations to backing state. When a postcondition or invariant fails during property search, the compiler shrinks the failure sequence to a minimal sequence of trace steps and formats an *active step diagnostic* detailing the active transition, input arguments, and current state snapshot. When the system under test produces an outcome rejected by the transition's return recognizer, the active step diagnostic details whether the transition was configured expecting an exception or a return value.
+
+A *unit test synthesizer* generates a standalone, reproducible Python test function from a shrunken counterexample sequence. The synthesized test instantiates the system under test, applies each step in sequence with literal arguments, and verifies that the failure reproduces deterministically.
+
+A *watchdog monitor* oversees test execution using a dual-layer timeout mechanism. A software timer emits a warning before expiration, dumping active step diagnostics to standard error. Concurrently, a system-level fault handler registers an abrupt termination alarm that interrupts blocking system calls or infinite loops, exiting with a non-zero status code to prevent test runner hangs.
+
+A *test runner coordinator* scans target directories for state machine test files, rejecting loading errors or missing test targets with diagnostics and a non-zero exit status code rather than reporting success. The coordinator executes test cases within configured execution phases, verifies statement coverage thresholds against the corresponding implementation modules under test (excluding abstract interface stubs), suppresses property fuzzing during coverage evaluation to bound execution to deterministic test suites while reserving fuzzing for QA verification, formats and reports all failure and error details across all executed test methods in failing test targets to prevent defect masking, formats auditor guidance reminders upon test failures and coverage deficits directing the agent to formulate blame feedback strictly in terms of how the blamed file is not compliant with the common source of truth specification, permitting line numbers only within the blamed file while strictly forbidding exposing details of other files, and reports aggregated test outcomes through a run result payload, exiting with a non-zero exit status code whenever any test fails, any test target fails to load, zero test targets are executed, or coverage thresholds are not met.