functualize-state 0.1.0__tar.gz

functualize_state-0.1.0/.gitignore

@@ -0,0 +1,101 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+dist/
+build/
+*.whl
+
+# Agents
+.spec/archive/
+.spec/features/
+.spec/scrutiny-reports/
+.spec/.agentic-coding
+.spec/STATE.md
+.spec/PROJECT.md
+.spec/REQUIREMENTS.md
+.spec/ROADMAP.md
+.opencode/
+
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+
+# Testing
+.coverage
+.pytest_cache/
+htmlcov/
+.hypothesis/
+snapshot_report.html
+_*_result*.txt
+_debug.txt
+_tui_debug.txt
+_tui_eval_debug.txt
+
+# IDE
+.idea/
+*.swp
+*.swo
+*~
+*.code-workspace
+
+# Coding-agent tooling state (guards — these dirs are not part of the repo)
+.kiro/
+.moai/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment / secrets
+.env
+.env.*
+!.env.example
+
+# Agent scratch space (test output, temp scripts)
+tmp/
+
+# Local-only files (not for the repo)
+*.local.md
+*.local.*
+
+# Personal notes
+HUMAN_NOTE.md
+
+# Distribution
+dist/
+
+# Documentation site build output
+site/
+
+# uv
+.python-version
+.functualize/cache.json
+.functualize_cache.json
+.todos/
+.sidecar/
+.sidecar-agent
+.sidecar-task
+.sidecar-pr
+.sidecar-start.sh
+.sidecar-base
+.td-root
+.functualize/
+.import_linter_cache/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# OmO / OpenCode agent run-continuation scratch state
+.omo/
+.mcp.json
+.agentsroom/handoff-transcript-*.txt
+.agentsroom/handoff-summary-*.md
+
+# Internal pre-release audit reports (contain session IDs / local infra notes)
+.release/

functualize_state-0.1.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: functualize-state
+Version: 0.1.0
+Summary: State Domain SDK providing protocols for state persistence and execution tracking
+Author-email: Mohammad Hakim Adiprasetya <viltohmyst@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest>=7.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# functualize-state
+
+> **Status: Published** — Independently installable from PyPI.
+
+State Domain SDK for functualize providing well-defined protocols for key-value state persistence and execution tracking. Enables custom storage backend implementations (SQLite, Redis, DynamoDB, etc.) without coupling your application to any specific database.
+
+## Installation
+
+```bash
+pip install functualize-state
+```
+
+## Quick Start
+
+```python
+from functualize_state import InMemoryState, StateNamespace
+
+# Create a backend (use InMemoryState for testing, or implement StateBackend)
+backend = InMemoryState()
+
+# Use namespaces to isolate keys by concern
+ns = StateNamespace(backend, prefix="deploy:")
+ns.set("version", "1.2.0")
+ns.set("status", "pending")
+
+print(ns.get("version"))  # "1.2.0"
+print(ns.keys())          # ["version", "status"]
+```
+
+## Features
+
+- **Backend-agnostic protocols** — `StateBackend` and `ExecutionStore` define the interface; bring your own storage implementation
+- **Namespace isolation** — `StateNamespace` provides prefix-scoped views over any backend, preventing key collisions between components
+- **Execution tracking** — Record job executions, phases, and session metadata with structured `ExecutionRecord` and `PhaseRecord` types
+- **Event-driven observability** — Built-in event constants (`STATE_EXECUTION_STARTED`, `STATE_EXECUTION_COMPLETED`, `STATE_PHASE_CHANGED`) for lifecycle hooks
+- **Test-friendly** — Ships `InMemoryState`, a dict-backed backend for fast, deterministic unit tests
+- **Fully typed** — PEP 561 compliant with `py.typed` marker; all protocols are `@runtime_checkable`
+
+## API Reference
+
+### Protocols
+
+- `StateBackend` — Key-value state operations protocol (`get`, `set`, `delete`, `keys`)
+- `ExecutionStore` — Execution record persistence protocol (`insert_execution`, `update_execution`, `get_session_executions`, `insert_phase`, `get_execution_phases`)
+
+### Classes
+
+- `StateNamespace` — Prefix-scoped view over a `StateBackend` for isolated key access
+- `InMemoryState` — Dict-backed `StateBackend` implementation for testing
+- `DomainMetadata` — Self-describing metadata dataclass for the state domain SDK
+
+### Data Types
+
+- `ExecutionRecord` — Frozen dataclass representing a single job execution (id, job name, session, status, timing, result)
+- `PhaseRecord` — Frozen dataclass representing a phase within an execution
+- `SessionRecord` — Frozen dataclass representing a session with metadata
+
+### Errors
+
+- `StateNotAvailable` — Raised when a state backend is not available
+- `KeyNotFoundError` — Raised when a requested key is not found
+
+### Event Constants
+
+- `STATE_EXECUTION_STARTED` — Fired when an execution begins
+- `STATE_EXECUTION_COMPLETED` — Fired when an execution finishes
+- `STATE_PHASE_CHANGED` — Fired when a phase transition occurs
+
+### Module-Level
+
+- `domain_metadata` — Pre-configured `DomainMetadata` instance for the state domain
+
+## Development
+
+Run plugin tests:
+
+```bash
+uv run pytest plugins/functualize-state/tests/ -v
+```

functualize_state-0.1.0/README.md

@@ -0,0 +1,79 @@
+# functualize-state
+
+> **Status: Published** — Independently installable from PyPI.
+
+State Domain SDK for functualize providing well-defined protocols for key-value state persistence and execution tracking. Enables custom storage backend implementations (SQLite, Redis, DynamoDB, etc.) without coupling your application to any specific database.
+
+## Installation
+
+```bash
+pip install functualize-state
+```
+
+## Quick Start
+
+```python
+from functualize_state import InMemoryState, StateNamespace
+
+# Create a backend (use InMemoryState for testing, or implement StateBackend)
+backend = InMemoryState()
+
+# Use namespaces to isolate keys by concern
+ns = StateNamespace(backend, prefix="deploy:")
+ns.set("version", "1.2.0")
+ns.set("status", "pending")
+
+print(ns.get("version"))  # "1.2.0"
+print(ns.keys())          # ["version", "status"]
+```
+
+## Features
+
+- **Backend-agnostic protocols** — `StateBackend` and `ExecutionStore` define the interface; bring your own storage implementation
+- **Namespace isolation** — `StateNamespace` provides prefix-scoped views over any backend, preventing key collisions between components
+- **Execution tracking** — Record job executions, phases, and session metadata with structured `ExecutionRecord` and `PhaseRecord` types
+- **Event-driven observability** — Built-in event constants (`STATE_EXECUTION_STARTED`, `STATE_EXECUTION_COMPLETED`, `STATE_PHASE_CHANGED`) for lifecycle hooks
+- **Test-friendly** — Ships `InMemoryState`, a dict-backed backend for fast, deterministic unit tests
+- **Fully typed** — PEP 561 compliant with `py.typed` marker; all protocols are `@runtime_checkable`
+
+## API Reference
+
+### Protocols
+
+- `StateBackend` — Key-value state operations protocol (`get`, `set`, `delete`, `keys`)
+- `ExecutionStore` — Execution record persistence protocol (`insert_execution`, `update_execution`, `get_session_executions`, `insert_phase`, `get_execution_phases`)
+
+### Classes
+
+- `StateNamespace` — Prefix-scoped view over a `StateBackend` for isolated key access
+- `InMemoryState` — Dict-backed `StateBackend` implementation for testing
+- `DomainMetadata` — Self-describing metadata dataclass for the state domain SDK
+
+### Data Types
+
+- `ExecutionRecord` — Frozen dataclass representing a single job execution (id, job name, session, status, timing, result)
+- `PhaseRecord` — Frozen dataclass representing a phase within an execution
+- `SessionRecord` — Frozen dataclass representing a session with metadata
+
+### Errors
+
+- `StateNotAvailable` — Raised when a state backend is not available
+- `KeyNotFoundError` — Raised when a requested key is not found
+
+### Event Constants
+
+- `STATE_EXECUTION_STARTED` — Fired when an execution begins
+- `STATE_EXECUTION_COMPLETED` — Fired when an execution finishes
+- `STATE_PHASE_CHANGED` — Fired when a phase transition occurs
+
+### Module-Level
+
+- `domain_metadata` — Pre-configured `DomainMetadata` instance for the state domain
+
+## Development
+
+Run plugin tests:
+
+```bash
+uv run pytest plugins/functualize-state/tests/ -v
+```

functualize_state-0.1.0/examples/README.md

@@ -0,0 +1,13 @@
+# functualize-state Examples
+
+The state domain SDK: `StateBackend` protocol, `StateNamespace` scoping, and the `InMemoryState` testing double.
+
+| Directory | Demonstrates |
+|-----------|--------------|
+| [`counter/`](counter/) | Namespace-scoped key-value state across job runs, using `InMemoryState` |
+
+```bash
+uv run pytest plugins/functualize-state/examples/ -v
+```
+
+For durable storage, see [`functualize-state-sqlite/examples/`](../../functualize-state-sqlite/examples/). To implement your own backend, see [`examples/plugins/custom_state_backend/`](../../../examples/plugins/custom_state_backend/).

functualize_state-0.1.0/examples/counter/counter.py

@@ -0,0 +1,23 @@
+"""Namespace-scoped state: count how many times a job has run.
+
+Uses the InMemoryState testing double directly so the example is
+self-contained; in a real app the framework injects a `State` capability
+backed by whichever state provider is installed (e.g. SQLite).
+"""
+
+from functualize_state import StateNamespace
+from functualize_state.testing import InMemoryState
+
+from functualize.job import RunContext
+
+# Shared backend for the module (a real app injects this per-scope)
+_backend = InMemoryState()
+
+
+def bump(rc: RunContext) -> int:
+    """Increment and report this job's run counter."""
+    state = StateNamespace(_backend, prefix="counter:")
+    count = state.get("runs", 0) + 1
+    state.set("runs", count)
+    rc.log(f"This job has now run {count} time(s)")
+    return count

functualize_state-0.1.0/examples/counter/test_counter.py

@@ -0,0 +1,22 @@
+"""Tests for the counter example."""
+
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+import counter
+
+
+def test_counter_increments_across_runs():
+    rc = MagicMock()
+    first = counter.bump(rc)
+    second = counter.bump(rc)
+    assert second == first + 1
+
+
+def test_namespace_isolates_keys():
+    # The raw backend key carries the namespace prefix
+    assert counter._backend.get("counter:runs") is not None
+    assert counter._backend.get("runs") is None

functualize_state-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "functualize-state"
+version = "0.1.0"
+description = "State Domain SDK providing protocols for state persistence and execution tracking"
+readme = "README.md"
+license = "MIT"
+authors = [
+    { name = "Mohammad Hakim Adiprasetya", email = "viltohmyst@gmail.com" }
+]
+requires-python = ">=3.11"
+dependencies = [
+    "pydantic>=2.0.0",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+
+[project.entry-points."functualize.domains"]
+state = "functualize_state._metadata:domain_metadata"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-cov>=4.1.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/functualize_state"]

functualize_state-0.1.0/src/functualize_state/__init__.py

@@ -0,0 +1,41 @@
+"""functualize-state: State Domain SDK for state persistence and execution tracking.
+
+Provides well-defined protocols for state persistence and execution tracking,
+enabling custom storage backend implementations without coupling to SQLite.
+"""
+
+from functualize_state._errors import KeyNotFoundError, StateNotAvailableError
+from functualize_state._events import (
+    STATE_EXECUTION_COMPLETED,
+    STATE_EXECUTION_STARTED,
+    STATE_PHASE_CHANGED,
+)
+from functualize_state._metadata import DomainMetadata, domain_metadata
+from functualize_state._namespace import StateNamespace
+from functualize_state._protocols import ExecutionStore, StateBackend
+from functualize_state._types import ExecutionRecord, PhaseRecord, SessionRecord
+from functualize_state.testing._in_memory import InMemoryState
+
+__all__ = [
+    # Protocols
+    "StateBackend",
+    "ExecutionStore",
+    # Utility
+    "StateNamespace",
+    # Types
+    "ExecutionRecord",
+    "PhaseRecord",
+    "SessionRecord",
+    # Errors
+    "StateNotAvailableError",
+    "KeyNotFoundError",
+    # Event Constants
+    "STATE_EXECUTION_STARTED",
+    "STATE_EXECUTION_COMPLETED",
+    "STATE_PHASE_CHANGED",
+    # Testing Doubles
+    "InMemoryState",
+    # Metadata
+    "DomainMetadata",
+    "domain_metadata",
+]

functualize_state-0.1.0/src/functualize_state/_errors.py

@@ -0,0 +1,13 @@
+"""Error classes for the State Domain SDK."""
+
+
+class StateNotAvailableError(Exception):
+    """Raised when a state backend is not available."""
+
+    pass
+
+
+class KeyNotFoundError(Exception):
+    """Raised when a requested key is not found in the state backend."""
+
+    pass

functualize_state-0.1.0/src/functualize_state/_events.py

@@ -0,0 +1,5 @@
+"""Event name constants for the State Domain SDK."""
+
+STATE_EXECUTION_STARTED: str = "state.execution.started"
+STATE_EXECUTION_COMPLETED: str = "state.execution.completed"
+STATE_PHASE_CHANGED: str = "state.phase.changed"

functualize_state-0.1.0/src/functualize_state/_metadata.py

@@ -0,0 +1,37 @@
+"""Domain metadata for the State SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class DomainMetadata:
+    """Self-describing metadata for a domain SDK."""
+
+    name: str
+    display_name: str
+    description: str
+    capability_class: str
+    provider_protocol: str
+    config_section: str
+    entry_point_group: str
+    events_prefix: str
+    scaffold_template: str | None = None
+    documentation_url: str | None = None
+    mock_factory: str | None = None
+
+
+domain_metadata = DomainMetadata(
+    name="state",
+    display_name="State / Persistence",
+    description="State persistence and execution tracking",
+    capability_class="functualize_state.StateBackend",
+    provider_protocol="functualize_state.StateBackend",
+    config_section="state",
+    entry_point_group="functualize.state_providers",
+    events_prefix="state.",
+    scaffold_template=None,
+    documentation_url=None,
+    mock_factory="functualize_state.testing:InMemoryState",
+)

functualize_state-0.1.0/src/functualize_state/_namespace.py

@@ -0,0 +1,37 @@
+"""StateNamespace utility for prefix-scoped state operations."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from functualize_state._protocols import StateBackend
+
+
+class StateNamespace:
+    """Prefix-scoped view over a StateBackend.
+
+    All key operations are transparently prefixed, providing isolated
+    read/write access to a specific key namespace within the backend.
+    """
+
+    def __init__(self, backend: StateBackend, prefix: str) -> None:
+        self._backend = backend
+        self._prefix = prefix
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get a value by key, scoped to this namespace's prefix."""
+        return self._backend.get(self._prefix + key, default)
+
+    def set(self, key: str, value: Any) -> None:
+        """Set a value for a key, scoped to this namespace's prefix."""
+        self._backend.set(self._prefix + key, value)
+
+    def delete(self, key: str) -> None:
+        """Delete a key, scoped to this namespace's prefix."""
+        self._backend.delete(self._prefix + key)
+
+    def keys(self) -> list[str]:
+        """Return all keys in this namespace with the prefix stripped."""
+        prefix_len = len(self._prefix)
+        return [k[prefix_len:] for k in self._backend.keys(self._prefix)]

functualize_state-0.1.0/src/functualize_state/_protocols.py

@@ -0,0 +1,56 @@
+"""Protocol definitions for the State Domain SDK."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from functualize_state._types import ExecutionRecord, PhaseRecord
+
+
+@runtime_checkable
+class StateBackend(Protocol):
+    """Backend-agnostic key-value state operations."""
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get a value by key, returning default if not found."""
+        ...
+
+    def set(self, key: str, value: Any) -> None:
+        """Set a value for a key."""
+        ...
+
+    def delete(self, key: str) -> None:
+        """Delete a key from the state backend."""
+        ...
+
+    def keys(self, prefix: str = "") -> list[str]:
+        """Return all keys, optionally filtered by prefix."""
+        ...
+
+
+@runtime_checkable
+class ExecutionStore(Protocol):
+    """Backend-agnostic execution record persistence operations."""
+
+    def insert_execution(self, record: ExecutionRecord) -> str:
+        """Insert an execution record, returning the execution ID."""
+        ...
+
+    def update_execution(self, execution_id: str, **updates: Any) -> None:
+        """Update fields on an existing execution record."""
+        ...
+
+    def get_session_executions(
+        self, session_id: str, limit: int = 50
+    ) -> list[ExecutionRecord]:
+        """Get execution records for a session, limited by count."""
+        ...
+
+    def insert_phase(self, execution_id: str, phase: PhaseRecord) -> None:
+        """Insert a phase record for an execution."""
+        ...
+
+    def get_execution_phases(self, execution_id: str) -> list[PhaseRecord]:
+        """Get all phase records for an execution."""
+        ...

functualize_state-0.1.0/src/functualize_state/_types.py

@@ -0,0 +1,41 @@
+"""Shared types for the State Domain SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class ExecutionRecord:
+    """A record of a single job execution."""
+
+    execution_id: str
+    job_name: str
+    session_id: str
+    status: str  # "running" | "success" | "failure"
+    started_at: float
+    ended_at: float | None = None
+    duration_ms: float | None = None
+    kwargs: dict[str, Any] = field(default_factory=dict)
+    result: Any = None
+
+
+@dataclass(frozen=True)
+class PhaseRecord:
+    """A record of a phase within an execution."""
+
+    name: str
+    status: str
+    started_at: float
+    ended_at: float | None = None
+    duration_ms: float | None = None
+
+
+@dataclass(frozen=True)
+class SessionRecord:
+    """A record of a session."""
+
+    session_id: str
+    started_at: float
+    metadata: dict[str, Any] = field(default_factory=dict)

functualize_state-0.1.0/src/functualize_state/testing/__init__.py

@@ -0,0 +1,10 @@
+"""Testing doubles for the State Domain SDK.
+
+Provides in-memory implementations usable without installing any implementation plugin.
+"""
+
+from functualize_state.testing._in_memory import InMemoryState
+
+__all__ = [
+    "InMemoryState",
+]

functualize_state-0.1.0/src/functualize_state/testing/_in_memory.py

@@ -0,0 +1,34 @@
+"""In-memory StateBackend implementation for testing."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class InMemoryState:
+    """Dict-backed StateBackend for testing.
+
+    Satisfies the StateBackend protocol using a plain dict as the backing store.
+    Useful for unit tests and integration tests that don't need persistence.
+    """
+
+    def __init__(self) -> None:
+        self._store: dict[str, Any] = {}
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Retrieve a value by key, returning default if not found."""
+        return self._store.get(key, default)
+
+    def set(self, key: str, value: Any) -> None:
+        """Store a value under the given key."""
+        self._store[key] = value
+
+    def delete(self, key: str) -> None:
+        """Remove a key from the store. No-op if key doesn't exist."""
+        self._store.pop(key, None)
+
+    def keys(self, prefix: str = "") -> list[str]:
+        """Return all keys matching the given prefix."""
+        if not prefix:
+            return list(self._store.keys())
+        return [k for k in self._store if k.startswith(prefix)]

functualize_state-0.1.0/tests/conftest.py

@@ -0,0 +1 @@
+"""Shared fixtures for functualize-state plugin tests."""

functualize_state-0.1.0/tests/test_plugin.py

@@ -0,0 +1,53 @@
+"""Unit tests for functualize-state domain SDK.
+
+Tests the state protocols, namespace isolation, and in-memory testing backend.
+"""
+
+from __future__ import annotations
+
+from functualize_state._namespace import StateNamespace
+from functualize_state.testing._in_memory import InMemoryState
+
+
+class TestInMemoryBackend:
+    """Tests for the InMemoryState test double."""
+
+    def test_get_missing_returns_default(self):
+        state = InMemoryState()
+        assert state.get("missing") is None
+        assert state.get("missing", "default") == "default"
+
+    def test_set_and_get(self):
+        state = InMemoryState()
+        state.set("key", "value")
+        assert state.get("key") == "value"
+
+    def test_delete(self):
+        state = InMemoryState()
+        state.set("key", "value")
+        state.delete("key")
+        assert state.get("key") is None
+
+
+class TestStateNamespace:
+    """Tests for the StateNamespace prefix isolation."""
+
+    def test_prefixes_keys(self):
+        backend = InMemoryState()
+        ns = StateNamespace(backend, prefix="app.")
+        ns.set("name", "functualize")
+        # The key in the backend should be prefixed
+        assert backend.get("app.name") == "functualize"
+
+    def test_get_uses_prefix(self):
+        backend = InMemoryState()
+        backend.set("app.version", "1.0")
+        ns = StateNamespace(backend, prefix="app.")
+        assert ns.get("version") == "1.0"
+
+    def test_delete_uses_prefix(self):
+        backend = InMemoryState()
+        backend.set("app.key", "val")
+        ns = StateNamespace(backend, prefix="app.")
+        ns.delete("key")
+        assert backend.get("app.key") is None