stateforge 0.1.0__tar.gz

stateforge-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,41 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  ci:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+      fail-fast: false
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --locked --dev
+
+      - name: Lint (ruff)
+        run: uv run ruff check .
+
+      - name: mypy strict (src)
+        run: uv run mypy --strict src/
+
+      - name: mypy strict (examples)
+        run: uv run mypy --strict examples/
+
+      - name: pyright strict
+        run: uv run pyright
+
+      - name: pytest with coverage
+        run: uv run pytest

stateforge-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,41 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+
+      - name: Build
+        run: uv build
+
+      - name: Smoke test
+        run: |
+          WHL=$(ls dist/*.whl)
+          uv run --isolated --no-project --with "$WHL" python -c "
+          import stateforge, pathlib, importlib.metadata
+          pkg_path = pathlib.Path(stateforge.__file__).parent
+          assert (pkg_path / 'py.typed').exists(), 'py.typed missing from installed wheel'
+          ver = importlib.metadata.version('stateforge')
+          assert ver, 'version empty'
+          requires = importlib.metadata.distribution('stateforge').metadata.get_all('Requires-Dist') or []
+          assert requires == [], f'unexpected runtime deps: {requires}'
+          print(f'Smoke test passed: version={ver}, py.typed=present, deps={requires}')
+          "
+
+      - name: Publish to PyPI
+        run: uv publish --trusted-publishing always

stateforge-0.1.0/.planning/PROJECT.md

@@ -0,0 +1,72 @@
+# stateforge
+
+## What This Is
+
+A type-safe, async-native Python state machine library where your type hints are your state machine. Invalid transitions are caught by mypy/pyright at development time, not at runtime. Async is the default execution model — not bolted on. Designed for Python developers building async applications who want state machine correctness enforced by the type system.
+
+## Core Value
+
+Type hints define and enforce the state machine — if it type-checks, it's a valid state machine; if it doesn't, you find out before running a single line.
+
+## Requirements
+
+### Validated
+
+(None yet — ship to validate)
+
+### Active
+
+- [ ] Define states and events as plain Python enums
+- [ ] `StateMachine[S, E]` generic base class parameterized by state and event enums
+- [ ] `@transition` decorator declaring `(from_, on, to)` edges on async methods
+- [ ] `send(event)` as primary interface for triggering transitions
+- [ ] Guards: async callables that gate transitions, raising `GuardRejectedError` on rejection
+- [ ] Multiple source states via list in `from_`
+- [ ] Wildcard source state via `ANY` sentinel
+- [ ] Typed context as optional third generic parameter `StateMachine[S, E, C]`
+- [ ] Event payloads passed as kwargs to `send()` and received as typed method parameters
+- [ ] Lifecycle hooks: `on_enter_state`, `on_exit_state`, `on_transition`
+- [ ] Fail-fast validation at class definition time (duplicate transitions, invalid states/events, etc.)
+- [ ] Clear error hierarchy: `MachineDefinitionError`, `InvalidTransitionError`, `GuardRejectedError`
+- [ ] PEP 561 `py.typed` marker for downstream type checking
+- [ ] Zero third-party dependencies for core library
+- [ ] PyPI distribution with `pyproject.toml`
+- [ ] Validated by building a non-trivial example project that exercises the full API
+
+### Out of Scope
+
+- Sync `send_sync()` variant — users use `asyncio.run()` at boundary; add later if demand is clear
+- Hierarchical/nested states — significant complexity, defer to future version
+- Parallel/orthogonal states — defer to future version
+- Per-state typed `send()` (mypy plugin) — stretch goal, not blocking v1
+- Observability integrations (OpenTelemetry, structlog) — future optional extras
+- Docs site — README with examples is sufficient for v1
+- Metaclass-based registration — use `__init_subclass__` only
+
+## Context
+
+- Inspired by XState (design philosophy), Boost.SML (types-as-constraints mindset), and C++20 qlibs/sml (function signatures as DSL)
+- Python's typing ecosystem (3.10+) is mature enough to express state machine constraints via generics and decorators
+- No existing Python state machine library prioritizes static type safety as the core value proposition
+- Key design constraint: `@transition` decorated methods must remain normal methods — callable directly in tests without going through `send()`
+
+## Constraints
+
+- **Python version**: 3.10+ — enables `X | Y` union syntax and modern typing features
+- **Dependencies**: Zero for core — observability/integrations are optional extras
+- **Async-only**: All transition methods and hooks are async; no sync API
+- **No metaclasses**: `__init_subclass__` for transition collection — simpler, more debuggable
+- **Deterministic FSM**: No two transitions may share the same `(from_, on)` pair
+
+## Key Decisions
+
+| Decision | Rationale | Outcome |
+|----------|-----------|---------|
+| Async-only, no sync variant | Simplicity; async is the native model; sync users can use asyncio.run() | — Pending |
+| `__init_subclass__` over metaclass | Simpler, more debuggable, doesn't surprise users | — Pending |
+| Decorated methods are still callable methods | Enables direct testing without send(); no magic wrapping | — Pending |
+| Guards raise by default (not silently ignore) | Fail-fast philosophy; silent failures hide bugs | — Pending |
+| Plain enums, no magic base classes | Mypy understands them natively; minimal learning curve | — Pending |
+
+---
+*Last updated: 2026-03-13 after initialization*

stateforge-0.1.0/.planning/REQUIREMENTS.md

@@ -0,0 +1,153 @@
+# Requirements: stateforge
+
+**Defined:** 2026-03-13
+**Core Value:** Type hints define and enforce the state machine — if it type-checks, it's a valid state machine
+
+## v1 Requirements
+
+Requirements for initial release. Each maps to roadmap phases.
+
+### Core Machine
+
+- [x] **CORE-01**: User can define states as plain Python enum members
+- [x] **CORE-02**: User can define events as plain Python enum members
+- [x] **CORE-03**: User can create a state machine by subclassing `StateMachine[S, E]` with state and event enum type parameters
+- [x] **CORE-04**: User can declare transitions via `@transition(from_=State, on=Event, to=State)` on async methods
+- [x] **CORE-05**: User can trigger transitions via `await machine.send(event)`
+- [x] **CORE-06**: Machine raises `InvalidTransitionError` when no transition matches `(current_state, event)`
+- [x] **CORE-07**: Machine validates all transitions at class definition time, raising `MachineDefinitionError` for invalid state/event references or duplicate `(from_, on)` pairs
+- [x] **CORE-08**: `send()` is typed as `async def send(self, event: E, **kwargs) -> None` so mypy/pyright catches wrong event enum usage
+- [x] **CORE-09**: `@transition` decorated methods remain directly callable as normal async methods (no wrapping)
+- [x] **CORE-10**: `initial_state` class attribute sets the starting state and is validated as a member of the state enum
+
+### Guards
+
+- [x] **GUARD-01**: User can attach an async guard callable to a transition via `guard=` parameter
+- [x] **GUARD-02**: Guard receives the machine instance for context inspection
+- [x] **GUARD-03**: Machine raises `GuardRejectedError` (subclass of `InvalidTransitionError`) when guard returns `False`
+
+### Transitions
+
+- [x] **TRANS-01**: User can specify multiple source states via `from_=[State.A, State.B]` list
+- [x] **TRANS-02**: User can specify wildcard source state via `from_=ANY` for transitions valid from any state
+- [x] **TRANS-03**: User can pass typed kwargs to `send(event, key=value)` that are forwarded to the transition handler
+- [x] **TRANS-04**: Transition handler parameters are optional — unmatched kwargs are silently ignored
+
+### Context
+
+- [x] **CTX-01**: User can define typed context via `StateMachine[S, E, C]` with a third generic parameter
+- [x] **CTX-02**: Context is accessible as `self.context` within transition methods and guards
+- [x] **CTX-03**: Context type parameter is optional — omitting it defaults context to `None`
+
+### Lifecycle Hooks
+
+- [x] **HOOK-01**: User can override `on_enter_state(state)` to run logic when any state is entered
+- [x] **HOOK-02**: User can override `on_exit_state(state)` to run logic when any state is exited
+- [x] **HOOK-03**: User can override `on_transition(from_, event, to)` to run logic after any successful transition
+
+### Errors
+
+- [x] **ERR-01**: `StateforgeError` is the base exception for all library errors
+- [x] **ERR-02**: `MachineDefinitionError` is raised at class definition time for invalid machine configurations
+- [x] **ERR-03**: `InvalidTransitionError` is raised at runtime when no transition matches
+- [x] **ERR-04**: `GuardRejectedError` is a subclass of `InvalidTransitionError` raised when a guard rejects
+
+### Packaging
+
+- [x] **PKG-01**: Library is distributed as a PyPI package installable via `pip install stateforge`
+- [x] **PKG-02**: Package has zero runtime dependencies
+- [x] **PKG-03**: Package includes `py.typed` PEP 561 marker for downstream type checking
+- [x] **PKG-04**: Package uses `pyproject.toml` for build configuration
+- [x] **PKG-05**: Package supports Python 3.10+
+
+### Validation
+
+- [x] **VAL-01**: A non-trivial example project exercises the full API (states, events, transitions, guards, context, hooks, payloads)
+- [x] **VAL-02**: Example project type-checks cleanly under both mypy strict and pyright strict
+- [x] **VAL-03**: Test suite covers all core functionality with pytest + pytest-asyncio
+
+## v2 Requirements
+
+Deferred to future release. Tracked but not in current roadmap.
+
+### Sync Support
+
+- **SYNC-01**: Optional `send_sync()` wrapper for sync-only codebases
+
+### Visualization
+
+- **VIZ-01**: Optional `stateforge[viz]` extra for Graphviz/Mermaid diagram export
+- **VIZ-02**: Machine introspection API exposing transition graph programmatically
+
+### Observability
+
+- **OBS-01**: Optional `stateforge[otel]` extra for OpenTelemetry spans per transition
+- **OBS-02**: Optional `stateforge[structlog]` extra for structured logging integration
+
+## Out of Scope
+
+Explicitly excluded. Documented to prevent scope creep.
+
+| Feature | Reason |
+|---------|--------|
+| Hierarchical/nested states | Massively increases complexity; breaks plain generic type model; defer to v2+ |
+| Parallel/orthogonal states | Requires different execution model; `current_state` no longer single value |
+| String-based state/event names | Defeats static type safety goal; enums only |
+| Dynamic `add_transition()` at runtime | Cannot be statically typed; makes `StateMachine[S, E]` meaningless |
+| Auto-generated trigger methods (`machine.melt()`) | The exact feature that breaks static analysis in `transitions` (issue #658) |
+| Metaclass-based registration | Harder to debug, interacts poorly with other metaclasses; use `__init_subclass__` |
+| State persistence/serialization | Out of scope for core FSM library; user serializes `state.value` |
+| Framework integrations (Django, FastAPI) | Contradicts zero-dependency core; future optional extras |
+| SCXML import/export | Only relevant for compound/parallel states which are out of scope |
+| Per-state typed `send()` (mypy plugin) | Stretch goal for v2+; not blocking v1 |
+
+## Traceability
+
+Which phases cover which requirements. Updated during roadmap creation.
+
+| Requirement | Phase | Status |
+|-------------|-------|--------|
+| CORE-01 | Phase 1 | Complete |
+| CORE-02 | Phase 1 | Complete |
+| CORE-03 | Phase 1 | Complete |
+| CORE-04 | Phase 1 | Complete |
+| CORE-05 | Phase 1 | Complete |
+| CORE-06 | Phase 1 | Complete |
+| CORE-07 | Phase 1 | Complete |
+| CORE-08 | Phase 1 | Complete |
+| CORE-09 | Phase 1 | Complete |
+| CORE-10 | Phase 1 | Complete |
+| ERR-01 | Phase 1 | Complete |
+| ERR-02 | Phase 1 | Complete |
+| ERR-03 | Phase 1 | Complete |
+| ERR-04 | Phase 1 | Complete |
+| GUARD-01 | Phase 2 | Complete |
+| GUARD-02 | Phase 2 | Complete |
+| GUARD-03 | Phase 2 | Complete |
+| TRANS-01 | Phase 2 | Complete |
+| TRANS-02 | Phase 2 | Complete |
+| TRANS-03 | Phase 2 | Complete |
+| TRANS-04 | Phase 2 | Complete |
+| CTX-01 | Phase 2 | Complete |
+| CTX-02 | Phase 2 | Complete |
+| CTX-03 | Phase 2 | Complete |
+| HOOK-01 | Phase 2 | Complete |
+| HOOK-02 | Phase 2 | Complete |
+| HOOK-03 | Phase 2 | Complete |
+| VAL-01 | Phase 3 | Complete |
+| VAL-02 | Phase 3 | Complete |
+| VAL-03 | Phase 3 | Complete |
+| PKG-01 | Phase 4 | Complete |
+| PKG-02 | Phase 4 | Complete |
+| PKG-03 | Phase 4 | Complete |
+| PKG-04 | Phase 4 | Complete |
+| PKG-05 | Phase 4 | Complete |
+
+**Coverage:**
+- v1 requirements: 35 total
+- Mapped to phases: 35
+- Unmapped: 0
+
+---
+*Requirements defined: 2026-03-13*
+*Last updated: 2026-03-13 after roadmap creation*

stateforge-0.1.0/.planning/ROADMAP.md

@@ -0,0 +1,93 @@
+# Roadmap: stateforge
+
+## Overview
+
+stateforge ships in four phases that follow the natural build order of the library. Phase 1 establishes the core generic base and error hierarchy — all critical pitfalls are concentrated here. Phase 2 layers on every feature extension (guards, multi-source transitions, typed context, lifecycle hooks, event payloads) once the foundation is proven sound. Phase 3 validates the complete implementation with a non-trivial example project and CI pipeline running both type checkers. Phase 4 packages and publishes to PyPI, completing the v1 release.
+
+## Phases
+
+**Phase Numbering:**
+- Integer phases (1, 2, 3): Planned milestone work
+- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)
+
+Decimal phases appear between their surrounding integers in numeric order.
+
+- [x] **Phase 1: Core Foundation** - Working `StateMachine[S, E]` base with async `send()`, `@transition` decorator, fail-fast validation, and full error hierarchy (completed 2026-03-16)
+- [x] **Phase 2: Full Feature Parity** - Guards, typed context, multi-source transitions, `ANY` sentinel, event payloads, and lifecycle hooks (completed 2026-03-16)
+- [x] **Phase 3: Validation** - Non-trivial example project, test suite with 100% coverage, and CI running both mypy strict and pyright strict (completed 2026-03-16)
+- [x] **Phase 4: Packaging and Release** - PyPI package with `py.typed`, `pyproject.toml`, zero-dependency verification, and 0.1.0 release (completed 2026-03-16)
+
+## Phase Details
+
+### Phase 1: Core Foundation
+**Goal**: Developers can define and run a type-safe async state machine using `StateMachine[S, E]` with enum states and events, `@transition` decorated methods, and `send()`
+**Depends on**: Nothing (first phase)
+**Requirements**: CORE-01, CORE-02, CORE-03, CORE-04, CORE-05, CORE-06, CORE-07, CORE-08, CORE-09, CORE-10, ERR-01, ERR-02, ERR-03, ERR-04
+**Success Criteria** (what must be TRUE):
+  1. Developer can subclass `StateMachine[S, E]` with plain Python enums and declare transitions via `@transition(from_=..., on=..., to=...)` on async methods
+  2. `await machine.send(event)` drives the machine to the next state; `InvalidTransitionError` is raised for unmatched `(state, event)` pairs
+  3. Duplicate or invalid transitions raise `MachineDefinitionError` at class definition time — before any instance is created
+  4. `@transition` decorated methods remain directly callable as ordinary async methods with their original signatures intact
+  5. mypy and pyright reject `machine.send(WrongEventEnum.value)` at type-check time without any runtime check
+**Plans:** 3/3 plans complete
+
+Plans:
+- [x] 01-01-PLAN.md — Project scaffold, toolchain setup (uv, ruff, mypy, pyright, pytest-asyncio), src/ layout
+- [x] 01-02-PLAN.md — Error hierarchy (_errors.py), @transition decorator (_decorators.py), TransitionRegistry (_registry.py)
+- [x] 01-03-PLAN.md — StateMachine[S, E] base class (_core.py) with __init_subclass__ validation, send(), initial state, __init__.py public surface
+
+### Phase 2: Full Feature Parity
+**Goal**: Developers can use the complete stateforge API — guards, typed context, `ANY` sentinel, multi-source transitions, event payload kwargs, and all lifecycle hooks
+**Depends on**: Phase 1
+**Requirements**: GUARD-01, GUARD-02, GUARD-03, TRANS-01, TRANS-02, TRANS-03, TRANS-04, CTX-01, CTX-02, CTX-03, HOOK-01, HOOK-02, HOOK-03
+**Success Criteria** (what must be TRUE):
+  1. Developer can attach an async guard to a transition; the machine raises `GuardRejectedError` when the guard returns `False`
+  2. Developer can write `StateMachine[S, E, C]` with a typed context accessible as `self.context` inside transition methods and guards
+  3. Developer can use `from_=[State.A, State.B]` or `from_=ANY` to declare transitions valid from multiple or all states
+  4. Developer can pass typed kwargs to `send(event, key=value)` that the transition handler receives; unmatched kwargs are ignored without error
+  5. Developer can override `on_enter_state`, `on_exit_state`, and `on_transition` to run logic during the async transition chain
+**Plans:** 3/3 plans complete
+
+Plans:
+- [ ] 02-01-PLAN.md — Guards (guard= on @transition, GuardRejectedError.guard_name), ANY sentinel module, multi-source from_ expansion in registry
+- [ ] 02-02-PLAN.md — Typed context third generic parameter (StateMachine[S, E, C]), frozen dataclass enforcement, kwargs filtering for handlers
+- [ ] 02-03-PLAN.md — Lifecycle hooks (on_enter_state, on_exit_state, on_transition), full 6-step send() chain integrating all features
+
+### Phase 3: Validation
+**Goal**: The complete API is exercised by a non-trivial example that type-checks cleanly under both mypy strict and pyright strict, and a pytest suite achieves 100% coverage
+**Depends on**: Phase 2
+**Requirements**: VAL-01, VAL-02, VAL-03
+**Success Criteria** (what must be TRUE):
+  1. A non-trivial example machine (e.g., order workflow) exercises states, events, guards, context, hooks, and payload kwargs and runs correctly end-to-end
+  2. `mypy --strict` and `pyright --strict` both pass on the example and the library source with zero errors
+  3. `pytest` with `pytest-asyncio` achieves 100% line coverage across all library modules
+**Plans:** 1/1 plans complete
+
+Plans:
+- [ ] 03-01-PLAN.md — Example order workflow, pyproject.toml config (branch coverage + pyright include), branch coverage regression test, GitHub Actions CI pipeline, uat_phase2.py cleanup
+
+### Phase 4: Packaging and Release
+**Goal**: `pip install stateforge` works, the installed package carries `py.typed`, has zero runtime dependencies, and version 0.1.0 is published on PyPI
+**Depends on**: Phase 3
+**Requirements**: PKG-01, PKG-02, PKG-03, PKG-04, PKG-05
+**Success Criteria** (what must be TRUE):
+  1. `pip install stateforge` succeeds on Python 3.10, 3.11, 3.12, and 3.13 with no additional dependencies installed
+  2. The installed package contains a `py.typed` marker and downstream type checkers (mypy, pyright) infer types from stateforge without any `# type: ignore` workarounds
+  3. `pip show stateforge` shows zero `Requires` entries
+**Plans:** 2/2 plans complete
+
+Plans:
+- [x] 04-01-PLAN.md — Package metadata (pyproject.toml enrichment, LICENSE, __version__, README)
+- [x] 04-02-PLAN.md — Release workflow (GitHub Actions tag-triggered build, smoke test, OIDC publish to PyPI)
+
+## Progress
+
+**Execution Order:**
+Phases execute in numeric order: 1 → 2 → 3 → 4
+
+| Phase | Plans Complete | Status | Completed |
+|-------|----------------|--------|-----------|
+| 1. Core Foundation | 3/3 | Complete   | 2026-03-16 |
+| 2. Full Feature Parity | 3/3 | Complete   | 2026-03-16 |
+| 3. Validation | 1/1 | Complete   | 2026-03-16 |
+| 4. Packaging and Release | 2/2 | Complete   | 2026-03-16 |

stateforge-0.1.0/.planning/STATE.md

@@ -0,0 +1,118 @@
+---
+gsd_state_version: 1.0
+milestone: v1.0
+milestone_name: milestone
+status: completed
+stopped_at: Completed 04-packaging-and-release 04-02-PLAN.md
+last_updated: "2026-03-16T17:29:23Z"
+last_activity: 2026-03-16 — Plan 04-02 complete (GitHub Actions release workflow, OIDC trusted publisher)
+progress:
+  total_phases: 4
+  completed_phases: 4
+  total_plans: 9
+  completed_plans: 9
+  percent: 100
+---
+
+# Project State
+
+## Project Reference
+
+See: .planning/PROJECT.md (updated 2026-03-13)
+
+**Core value:** Type hints define and enforce the state machine — if it type-checks, it's a valid state machine
+**Current focus:** Phase 2 — Full Feature Parity
+
+## Current Position
+
+Phase: 4 of 4 (Packaging and Release)
+Plan: 2 of 2 in current phase — PHASE COMPLETE
+Status: All 4 phases complete — PROJECT COMPLETE
+Last activity: 2026-03-16 — Plan 04-02 complete (GitHub Actions release workflow, OIDC trusted publisher)
+
+Progress: [██████████] 100%
+
+## Performance Metrics
+
+**Velocity:**
+- Total plans completed: 0
+- Average duration: -
+- Total execution time: 0 hours
+
+**By Phase:**
+
+| Phase | Plans | Total | Avg/Plan |
+|-------|-------|-------|----------|
+| - | - | - | - |
+
+**Recent Trend:**
+- Last 5 plans: none yet
+- Trend: -
+
+*Updated after each plan completion*
+
+| Phase | Duration | Tasks | Files |
+|-------|----------|-------|-------|
+| Phase 01-core-foundation P01 | 2min | 2 tasks | 5 files |
+| Phase 01-core-foundation P02 | 4min | 2 tasks | 6 files |
+| Phase 01-core-foundation P03 | 3min | 2 tasks | 6 files |
+| Phase 02-full-feature-parity P01 | 7min | 2 tasks | 8 files |
+| Phase 02-full-feature-parity P02 | 45 | 2 tasks | 3 files |
+| Phase 02-full-feature-parity P03 | 25min | 2 tasks | 2 files |
+| Phase 03-validation P01 | 9min | 2 tasks | 4 files |
+| Phase 04-packaging-and-release P01 | 4min | 2 tasks | 5 files |
+| Phase 04-packaging-and-release P02 | 5min | 2 tasks | 1 file |
+
+## Accumulated Context
+
+### Decisions
+
+Decisions are logged in PROJECT.md Key Decisions table.
+Recent decisions affecting current work:
+
+- All transitions: `@transition` must NOT wrap the function — attach metadata as attribute, return original callable unchanged
+- All transitions: Async-only; no sync API; guards must be `async def`
+- Phase 1 risk: `asyncio.Lock` reentrancy deadlock — use `_processing: bool` flag instead of a lock
+- Phase 1 risk: `__init_subclass__` fires on base class — guard with `if cls is StateMachine: return`
+- Phase 1–2 open: `__aenter__`/`__aexit__` vs deferred-hook pattern for initial state activation — decide in Phase 1 before hooks in Phase 2
+- [Phase 01-core-foundation]: hatchling chosen as build backend for maximum compatibility
+- [Phase 01-core-foundation]: both mypy and pyright run in strict mode for dual type checker enforcement
+- [Phase 01-core-foundation]: ruff rules E/F/I/UP/ANN for errors, imports, modernization, annotations
+- [Phase 01-core-foundation]: noqa: ANN401 on Any-typed params for generic enum-agnostic APIs in _errors.py, _decorators.py, _registry.py
+- [Phase 01-core-foundation]: TransitionRegistry.build() returns (registry, errors) tuple — caller raises MachineDefinitionError if non-empty
+- [Phase 01-core-foundation]: inspect.iscoroutinefunction replaces deprecated asyncio.iscoroutinefunction for Python 3.14+ compatibility
+- [Phase 01-core-foundation]: _processing: bool flag for reentrancy protection (not asyncio.Lock) to avoid deadlock on re-entrant send()
+- [Phase 01-core-foundation]: stateforge.errors public re-export module for stable import surface independent of internal _errors.py
+- [Phase 01-core-foundation]: __init_subclass__ skips TypeVar type args to allow abstract intermediate classes without triggering validation
+- [Phase 02-full-feature-parity P01]: ANY sentinel in _sentinel.py (not __init__.py) to break circular import between _decorators.py and _registry.py
+- [Phase 02-full-feature-parity P01]: guard stored as tuple[Callable...] (not list) in frozen dataclass TransitionMeta/TransitionEntry for hashability
+- [Phase 02-full-feature-parity P01]: lookup_entry() added alongside lookup() for backward compat; Plan 03 send() uses lookup_entry()
+- [Phase 02-full-feature-parity P01]: from_=list expanded at build() time (not runtime) to keep lookup O(1)
+- [Phase 02-full-feature-parity]: __class_getitem__ normalization only on StateMachine (not subclasses) to preserve abstract intermediate class support
+- [Phase 02-full-feature-parity]: ty rules added to pyproject.toml to suppress invalid-type-arguments (2-arg form intentional) and unused-type-ignore-comment (mypy-only ignores)
+- [Phase 02-full-feature-parity]: Tasks 1 and 2 committed together due to 100% coverage compliance requirement for _filter_kwargs var-keyword path
+- [Phase 02-full-feature-parity P03]: getattr(guard_fn, '__name__', '') instead of guard_fn.__name__ — Callable[..., Any] has no __name__ per ty's type system; getattr is more robust for non-function callables
+- [Phase 02-full-feature-parity P03]: No type: ignore[assignment] needed on self._context = new_context — mypy infers correctly after the non-None check
+- [Phase 03-validation]: Guard checks machine.context.amount at guard time; initial context must have amount > 0 for guard to pass
+- [Phase 03-validation]: examples/ not added to mypy_path (search path only); checked explicitly with uv run mypy --strict examples/
+- [Phase 03-validation]: types.GenericAlias patching of __orig_bases__ works to cover _core.py:54 false branch via synthetic test
+- [Phase 04-packaging-and-release]: importlib.metadata.version() for __version__ — single source of truth stays in pyproject.toml
+- [Phase 04-packaging-and-release]: PackageNotFoundError fallback to 'unknown'; test_version.py re-imports module via sys.modules.pop() + patch to cover 100% branch
+- [Phase 04-packaging-and-release P02]: OIDC trusted publisher (no API tokens) — --trusted-publishing always fails hard if misconfigured
+- [Phase 04-packaging-and-release P02]: WHL=$(ls dist/*.whl) pattern avoids shell glob expansion issues in --with argument
+- [Phase 04-packaging-and-release P02]: No GitHub Release creation — PyPI publish only, per user decision
+
+### Pending Todos
+
+None yet.
+
+### Blockers/Concerns
+
+- Phase 1: TypeVar variance on `Generic[S, E, C]` — RESOLVED: all three invariant; mypy strict + pyright strict both pass
+- Phase 1–2: Whether v1 accepts sync guards (needs `inspect.iscoroutinefunction` check) or requires all guards to be `async def` — unresolved per research
+
+## Session Continuity
+
+Last session: 2026-03-16T17:29:23Z
+Stopped at: Completed 04-packaging-and-release 04-02-PLAN.md
+Resume file: None

stateforge-0.1.0/.planning/config.json

@@ -0,0 +1,13 @@
+{
+  "mode": "yolo",
+  "granularity": "coarse",
+  "parallelization": true,
+  "commit_docs": true,
+  "model_profile": "balanced",
+  "workflow": {
+    "research": true,
+    "plan_check": true,
+    "verifier": true,
+    "nyquist_validation": true
+  }
+}