voodoo-framework 2.6.0__tar.gz → 2.6.2__tar.gz

voodoo_framework-2.6.2/PKG-INFO

@@ -0,0 +1,284 @@
+Metadata-Version: 2.4
+Name: voodoo-framework
+Version: 2.6.2
+Summary: The programmable runtime for adaptive applications and operational systems — web, APIs, agents, workers, human workflows, distributed systems, and physical systems in one runtime.
+Author-email: Helder Perez <contact@helderperez.com>
+Maintainer-email: Helder Perez <contact@helderperez.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/helderperez-dev/voodoo
+Project-URL: Documentation, https://github.com/helderperez-dev/voodoo#documentation
+Project-URL: Repository, https://github.com/helderperez-dev/voodoo
+Project-URL: Changelog, https://github.com/helderperez-dev/voodoo/blob/main/CHANGELOG.md
+Project-URL: Roadmap, https://github.com/helderperez-dev/voodoo/blob/main/ROADMAP.md
+Project-URL: Issues, https://github.com/helderperez-dev/voodoo/issues
+Project-URL: Discussions, https://github.com/helderperez-dev/voodoo/discussions
+Keywords: ai,agent,application-framework,async,durable-execution,mcp,realtime,reactive,web-framework
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: starlette
+Requires-Dist: uvicorn
+Requires-Dist: pydantic
+Requires-Dist: aiosqlite
+Requires-Dist: websockets
+Requires-Dist: httpx
+Requires-Dist: python-dotenv
+Requires-Dist: pyyaml
+Requires-Dist: typer
+Requires-Dist: rich
+Requires-Dist: aiofiles
+Provides-Extra: ai
+Requires-Dist: openai; extra == "ai"
+Requires-Dist: anthropic; extra == "ai"
+Requires-Dist: google-generativeai; extra == "ai"
+Requires-Dist: ollama; extra == "ai"
+Provides-Extra: mcp
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.3.4; extra == "postgres"
+Provides-Extra: s3
+Requires-Dist: boto3>=1.34; extra == "s3"
+Requires-Dist: botocore>=1.34; extra == "s3"
+Provides-Extra: redis
+Requires-Dist: redis>=5.0; extra == "redis"
+Provides-Extra: edge
+Requires-Dist: paho-mqtt>=2.0; extra == "edge"
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.20; extra == "otel"
+Requires-Dist: opentelemetry-sdk>=1.20; extra == "otel"
+Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.20; extra == "otel"
+Dynamic: license-file
+
+# Voodoo
+
+**The programmable runtime for adaptive applications and operational systems.**
+
+Voodoo lets Python applications grow from a page or API into durable workers, agents, human approvals, realtime communication and production infrastructure without replacing the execution model underneath them.
+
+> Composition over configuration. Python over DSLs. Adapters over lock-in. Explicit capabilities over unrestricted autonomy.
+
+## Why Voodoo?
+
+Modern applications often assemble separate frameworks for HTTP, UI, persistence, queues, scheduling, AI, realtime communication and observability. Voodoo provides these as composable capabilities of one runtime.
+
+The central model is:
+
+```text
+Entity → State → Intent → Capability → Execution → Effect → State
+```
+
+An `Execution` is not every function call. It is meaningful work worth observing, authorizing, recovering, accounting for, waiting on, or reasoning about.
+
+## Quick start
+
+```bash
+pip install voodoo-framework
+voodoo create my_app
+cd my_app
+voodoo dev
+```
+
+Open `http://localhost:8000`. The default path requires no external database, queue or object store.
+
+`voodoo create` is the primary onboarding path and scaffolds the local runtime. If you deliberately want only the smallest UI/routing scaffold, use `voodoo new`.
+
+AI provider SDKs are optional:
+
+```bash
+pip install "voodoo-framework[ai]"
+```
+
+The core package does not install OpenAI, Anthropic, Gemini or Ollama SDKs. Providers are resolved lazily when used.
+
+## Start simple, add runtime capabilities when they matter
+
+| You need | Voodoo primitive |
+|---|---|
+| UI-local mutable value | `state()` |
+| Persistent business data | `Model` |
+| Browser interaction | `@event` |
+| Decoupled application notification | Mesh / event bus |
+| Retryable background work | `@task` |
+| Meaningful durable/observable work | `Execution` |
+| LLM reasoning and tool use | `Agent` + `@tool` |
+| Authorization to produce an effect | `Capability` |
+| Human decision inside work | HITL approval |
+| Future/recurring work | Scheduler |
+
+See `docs/choosing-primitives.md` for the semantic boundaries between State, Model, Memory, events, tools, tasks, capabilities and executions.
+
+## A small AI + data + event example
+
+Install the `ai` extra for real providers, or use `mock:*` locally. This example intentionally claims only the chain it executes: **Agent → Tool → Model → Mesh**.
+
+```python
+from voodoo import Agent, Model, tool
+from voodoo.mesh import mesh
+
+
+class Lead(Model):
+    name: str
+    email: str
+
+
+@tool
+async def create_lead(name: str, email: str) -> str:
+    lead = await Lead.create(name=name, email=email)
+    await mesh.emit("lead.created", {"id": lead.id, "name": name})
+    return f"Created lead #{lead.id}"
+
+
+@mesh.on("lead.created")
+async def notify(payload):
+    print("new lead", payload["name"])
+
+
+agent = Agent(model="mock:test", tools=["create_lead"])
+```
+
+For the broader UI → agent → tool → event → worker → database demonstration, run `examples/ai_saas/main.py`. Tools registered with `@tool` are also available to Voodoo's MCP integration; that exposure is a separate integration boundary rather than a fake step inserted into the local call chain.
+
+## What makes Voodoo different
+
+- **One execution model.** APIs, agents, tools, workers and human workflows can participate in a traceable runtime rather than forming independent orchestration stacks.
+- **AI is one form of Compute.** Agents are powerful participants, not the foundation every application must depend on.
+- **Durable when it matters.** Executions, tasks, schedules and approvals can survive process restarts using local persistence by default.
+- **Human-in-the-loop is native.** Waiting for approval is an execution lifecycle state, not an ad-hoc polling pattern.
+- **Local-first, production-capable.** SQLite/local filesystem provide the default path; PostgreSQL, Redis and S3-compatible storage are adapters.
+- **Adaptive execution is optional.** Planner/supervisor capabilities are available when capability resolution, fallback or budget steering is useful; simple paths remain simple.
+- **Observability is part of the runtime.** Correlation and execution context connect meaningful work across boundaries.
+
+## Computational model
+
+```text
+Intent       desired outcome
+Capability   ability + authorization to produce an effect
+Execution    meaningful unit of runtime work
+Effect       change produced by an execution
+State        operational truth
+```
+
+`Compute`, `Time`, `Resource`, and `Constraint` govern how an Execution happens. See `docs/primitives.md`, `docs/execution-model.md`, `ARCHITECTURE.md`, and `docs/runtime-consolidation.md`.
+
+## Major capabilities
+
+**Application:** server-rendered/reactive Python UI, routing/APIs, design system/themes, SEO, async ORM, auth and security middleware.
+
+**Runtime:** ExecutionEngine, durable execution/checkpoints/recovery, workers/tasks, scheduler, event infrastructure, human approvals, capability security, telemetry and optional adaptive planning/supervision.
+
+**AI:** agents, native provider tool calling, `@tool`, MCP integration, memory, model/provider abstraction and config-driven OpenAI-compatible endpoints.
+
+**Infrastructure adapters:** PostgreSQL, Redis, S3-compatible object storage and OpenTelemetry are optional extras behind runtime contracts.
+
+## Installation
+
+```bash
+# Core runtime — no third-party AI provider SDKs
+pip install voodoo-framework
+
+# Model providers
+pip install "voodoo-framework[ai]"
+
+# Production adapters as needed
+pip install "voodoo-framework[postgres,redis,s3,otel]"
+
+# Development tools
+pip install "voodoo-framework[dev]"
+```
+
+Other supported installation paths include Homebrew (`brew tap helderperez-dev/voodoo && brew install voodoo`), `uv tool install voodoo-framework`, and `pipx install voodoo-framework`.
+
+Verify with:
+
+```bash
+voodoo version
+```
+
+## Configuration
+
+Voodoo is zero-config locally. Add `voodoo.yaml` when you need explicit providers:
+
+```yaml
+database:
+  provider: sqlite
+queue:
+  provider: sqlite
+events:
+  provider: sqlite
+objects:
+  provider: local
+cache:
+  provider: memory
+runtime:
+  run_api_through_runtime: true
+```
+
+AI configuration is opt-in and requires the corresponding optional SDK:
+
+```yaml
+ai:
+  provider: openai
+  model: gpt-4o
+  api_key: "${OPENAI_API_KEY}"
+```
+
+Environment variables use the `VOODOO_*` convention. See `.env.example` for the full reference.
+
+## Documentation
+
+Start here:
+
+- `docs/hello_world.md` — first application
+- `docs/choosing-primitives.md` — which Voodoo abstraction to use
+- `docs/primitives.md` — computational model
+- `docs/execution-model.md` and `docs/runtime.md` — execution semantics
+- `docs/data.md` — Models and persistence
+- `docs/events.md` and `docs/mesh.md` — communication boundaries
+- `docs/workers.md` — background tasks
+- `docs/agents.md`, `docs/tools.md`, `docs/mcp.md` — AI/tool integration
+- `docs/hitl.md` — human approvals
+- `docs/telemetry.md` — observability
+- `docs/deployment.md` — production deployment
+- `ARCHITECTURE.md` — root architecture reference
+- `docs/runtime-consolidation.md` — invariants that keep the runtime coherent
+
+## Examples
+
+| Example | Purpose |
+|---|---|
+| `examples/hello_world/` | smallest page |
+| `examples/dashboard/` | reactive UI/state |
+| `examples/realtime/` | realtime communication |
+| `examples/ai_agent/` | agent/tool application |
+| `examples/ai_saas/` | UI + Agent + Tool + Mesh + Worker + Model |
+
+The examples are intentionally progressive. Applications do not need to adopt the complete runtime surface at once.
+
+## Project status
+
+Voodoo is beta software. The repository's `SPRINT_PLAN.md` is the source of truth for implementation progress; `ROADMAP.md` describes longer-term direction. Public API and behavior should be treated with beta-level compatibility expectations until a stable release policy is declared.
+
+## Contributing and security
+
+See `CONTRIBUTING.md` for the development workflow, `SECURITY.md` for vulnerability reporting, and `CODE_OF_CONDUCT.md` for community expectations.
+
+## License
+
+MIT. See `LICENSE`.

voodoo_framework-2.6.2/README.md

@@ -0,0 +1,216 @@
+# Voodoo
+
+**The programmable runtime for adaptive applications and operational systems.**
+
+Voodoo lets Python applications grow from a page or API into durable workers, agents, human approvals, realtime communication and production infrastructure without replacing the execution model underneath them.
+
+> Composition over configuration. Python over DSLs. Adapters over lock-in. Explicit capabilities over unrestricted autonomy.
+
+## Why Voodoo?
+
+Modern applications often assemble separate frameworks for HTTP, UI, persistence, queues, scheduling, AI, realtime communication and observability. Voodoo provides these as composable capabilities of one runtime.
+
+The central model is:
+
+```text
+Entity → State → Intent → Capability → Execution → Effect → State
+```
+
+An `Execution` is not every function call. It is meaningful work worth observing, authorizing, recovering, accounting for, waiting on, or reasoning about.
+
+## Quick start
+
+```bash
+pip install voodoo-framework
+voodoo create my_app
+cd my_app
+voodoo dev
+```
+
+Open `http://localhost:8000`. The default path requires no external database, queue or object store.
+
+`voodoo create` is the primary onboarding path and scaffolds the local runtime. If you deliberately want only the smallest UI/routing scaffold, use `voodoo new`.
+
+AI provider SDKs are optional:
+
+```bash
+pip install "voodoo-framework[ai]"
+```
+
+The core package does not install OpenAI, Anthropic, Gemini or Ollama SDKs. Providers are resolved lazily when used.
+
+## Start simple, add runtime capabilities when they matter
+
+| You need | Voodoo primitive |
+|---|---|
+| UI-local mutable value | `state()` |
+| Persistent business data | `Model` |
+| Browser interaction | `@event` |
+| Decoupled application notification | Mesh / event bus |
+| Retryable background work | `@task` |
+| Meaningful durable/observable work | `Execution` |
+| LLM reasoning and tool use | `Agent` + `@tool` |
+| Authorization to produce an effect | `Capability` |
+| Human decision inside work | HITL approval |
+| Future/recurring work | Scheduler |
+
+See `docs/choosing-primitives.md` for the semantic boundaries between State, Model, Memory, events, tools, tasks, capabilities and executions.
+
+## A small AI + data + event example
+
+Install the `ai` extra for real providers, or use `mock:*` locally. This example intentionally claims only the chain it executes: **Agent → Tool → Model → Mesh**.
+
+```python
+from voodoo import Agent, Model, tool
+from voodoo.mesh import mesh
+
+
+class Lead(Model):
+    name: str
+    email: str
+
+
+@tool
+async def create_lead(name: str, email: str) -> str:
+    lead = await Lead.create(name=name, email=email)
+    await mesh.emit("lead.created", {"id": lead.id, "name": name})
+    return f"Created lead #{lead.id}"
+
+
+@mesh.on("lead.created")
+async def notify(payload):
+    print("new lead", payload["name"])
+
+
+agent = Agent(model="mock:test", tools=["create_lead"])
+```
+
+For the broader UI → agent → tool → event → worker → database demonstration, run `examples/ai_saas/main.py`. Tools registered with `@tool` are also available to Voodoo's MCP integration; that exposure is a separate integration boundary rather than a fake step inserted into the local call chain.
+
+## What makes Voodoo different
+
+- **One execution model.** APIs, agents, tools, workers and human workflows can participate in a traceable runtime rather than forming independent orchestration stacks.
+- **AI is one form of Compute.** Agents are powerful participants, not the foundation every application must depend on.
+- **Durable when it matters.** Executions, tasks, schedules and approvals can survive process restarts using local persistence by default.
+- **Human-in-the-loop is native.** Waiting for approval is an execution lifecycle state, not an ad-hoc polling pattern.
+- **Local-first, production-capable.** SQLite/local filesystem provide the default path; PostgreSQL, Redis and S3-compatible storage are adapters.
+- **Adaptive execution is optional.** Planner/supervisor capabilities are available when capability resolution, fallback or budget steering is useful; simple paths remain simple.
+- **Observability is part of the runtime.** Correlation and execution context connect meaningful work across boundaries.
+
+## Computational model
+
+```text
+Intent       desired outcome
+Capability   ability + authorization to produce an effect
+Execution    meaningful unit of runtime work
+Effect       change produced by an execution
+State        operational truth
+```
+
+`Compute`, `Time`, `Resource`, and `Constraint` govern how an Execution happens. See `docs/primitives.md`, `docs/execution-model.md`, `ARCHITECTURE.md`, and `docs/runtime-consolidation.md`.
+
+## Major capabilities
+
+**Application:** server-rendered/reactive Python UI, routing/APIs, design system/themes, SEO, async ORM, auth and security middleware.
+
+**Runtime:** ExecutionEngine, durable execution/checkpoints/recovery, workers/tasks, scheduler, event infrastructure, human approvals, capability security, telemetry and optional adaptive planning/supervision.
+
+**AI:** agents, native provider tool calling, `@tool`, MCP integration, memory, model/provider abstraction and config-driven OpenAI-compatible endpoints.
+
+**Infrastructure adapters:** PostgreSQL, Redis, S3-compatible object storage and OpenTelemetry are optional extras behind runtime contracts.
+
+## Installation
+
+```bash
+# Core runtime — no third-party AI provider SDKs
+pip install voodoo-framework
+
+# Model providers
+pip install "voodoo-framework[ai]"
+
+# Production adapters as needed
+pip install "voodoo-framework[postgres,redis,s3,otel]"
+
+# Development tools
+pip install "voodoo-framework[dev]"
+```
+
+Other supported installation paths include Homebrew (`brew tap helderperez-dev/voodoo && brew install voodoo`), `uv tool install voodoo-framework`, and `pipx install voodoo-framework`.
+
+Verify with:
+
+```bash
+voodoo version
+```
+
+## Configuration
+
+Voodoo is zero-config locally. Add `voodoo.yaml` when you need explicit providers:
+
+```yaml
+database:
+  provider: sqlite
+queue:
+  provider: sqlite
+events:
+  provider: sqlite
+objects:
+  provider: local
+cache:
+  provider: memory
+runtime:
+  run_api_through_runtime: true
+```
+
+AI configuration is opt-in and requires the corresponding optional SDK:
+
+```yaml
+ai:
+  provider: openai
+  model: gpt-4o
+  api_key: "${OPENAI_API_KEY}"
+```
+
+Environment variables use the `VOODOO_*` convention. See `.env.example` for the full reference.
+
+## Documentation
+
+Start here:
+
+- `docs/hello_world.md` — first application
+- `docs/choosing-primitives.md` — which Voodoo abstraction to use
+- `docs/primitives.md` — computational model
+- `docs/execution-model.md` and `docs/runtime.md` — execution semantics
+- `docs/data.md` — Models and persistence
+- `docs/events.md` and `docs/mesh.md` — communication boundaries
+- `docs/workers.md` — background tasks
+- `docs/agents.md`, `docs/tools.md`, `docs/mcp.md` — AI/tool integration
+- `docs/hitl.md` — human approvals
+- `docs/telemetry.md` — observability
+- `docs/deployment.md` — production deployment
+- `ARCHITECTURE.md` — root architecture reference
+- `docs/runtime-consolidation.md` — invariants that keep the runtime coherent
+
+## Examples
+
+| Example | Purpose |
+|---|---|
+| `examples/hello_world/` | smallest page |
+| `examples/dashboard/` | reactive UI/state |
+| `examples/realtime/` | realtime communication |
+| `examples/ai_agent/` | agent/tool application |
+| `examples/ai_saas/` | UI + Agent + Tool + Mesh + Worker + Model |
+
+The examples are intentionally progressive. Applications do not need to adopt the complete runtime surface at once.
+
+## Project status
+
+Voodoo is beta software. The repository's `SPRINT_PLAN.md` is the source of truth for implementation progress; `ROADMAP.md` describes longer-term direction. Public API and behavior should be treated with beta-level compatibility expectations until a stable release policy is declared.
+
+## Contributing and security
+
+See `CONTRIBUTING.md` for the development workflow, `SECURITY.md` for vulnerability reporting, and `CODE_OF_CONDUCT.md` for community expectations.
+
+## License
+
+MIT. See `LICENSE`.

{voodoo_framework-2.6.0 → voodoo_framework-2.6.2}/pyproject.toml

@@ -52,7 +52,6 @@ dependencies = [
     "pyyaml",
     "typer",
     "rich",
-    "openai",
     "aiofiles"
 ]
 

{voodoo_framework-2.6.0 → voodoo_framework-2.6.2}/src/voodoo/__init__.py

@@ -102,7 +102,7 @@ from .ui.styles import (
 from .ui.styles.theme import Theme, ThemeColors, create_theme
 from .workers import task
 
-__version__ = "2.6.0"
+__version__ = "2.6.2"
 
 __all__ = [
     # Core runtime

{voodoo_framework-2.6.0 → voodoo_framework-2.6.2}/src/voodoo/config.py

@@ -284,6 +284,11 @@ class EdgeConfig(BaseModel):
     max_state_size: int = 65536  # 64 KiB
     max_pending_effects: int = 1000
     heartbeat_interval: int = 30
+    # Enrollment security (Sprint 23.1).
+    enrollment_auth_required: bool = True
+    enrollment_admin_token: str = ""
+    # Effect delivery (Sprint 23.1).
+    max_effect_retries: int = 3
 
 
 class VoodooConfig(BaseModel):

{voodoo_framework-2.6.0 → voodoo_framework-2.6.2}/src/voodoo/edge/__init__.py

@@ -27,6 +27,8 @@ from voodoo.edge.auth import (
 from voodoo.edge.errors import (
     AuthenticationFailedError,
     AuthorizationFailedError,
+    DeliveryFailedError,
+    DeviceIdMismatchError,
     DeviceNotFoundError,
     DeviceRevokedError,
     DuplicateMessageError,
@@ -37,6 +39,9 @@ from voodoo.edge.errors import (
     InvalidMessageError,
     InvalidProtocolVersionError,
     InvalidStateVersionError,
+    PayloadTooLargeError,
+    SessionInvalidError,
+    SessionRequiredError,
     TransportError,
     error_response,
 )
@@ -109,7 +114,9 @@ __all__ = [
     "error_response",
     "AuthenticationFailedError",
     "AuthorizationFailedError",
+    "DeliveryFailedError",
     "DeviceNotFoundError",
+    "DeviceIdMismatchError",
     "DeviceRevokedError",
     "DuplicateMessageError",
     "EffectExpiredError",
@@ -118,5 +125,8 @@ __all__ = [
     "InvalidMessageError",
     "InvalidProtocolVersionError",
     "InvalidStateVersionError",
+    "PayloadTooLargeError",
+    "SessionInvalidError",
+    "SessionRequiredError",
     "TransportError",
 ]

{voodoo_framework-2.6.0 → voodoo_framework-2.6.2}/src/voodoo/edge/auth.py

@@ -223,6 +223,13 @@ async def authenticate_device(
 
     await store.mark_credential_used(record.credential_id)
 
+    # Reconnect: invalidate any existing sessions for this device before
+    # creating a new one.  The device transitions RECONNECTING → CONNECTED
+    # so downstream observers see a clean lifecycle signal (EDGE §30).
+    old_session_count = await store.delete_device_sessions(device.device_id)
+    if old_session_count > 0:
+        await store.update_device_status(device.device_id, DeviceStatus.RECONNECTING)
+
     session = DeviceSession(
         device_id=device.device_id,
         transport=transport,

{voodoo_framework-2.6.0 → voodoo_framework-2.6.2}/src/voodoo/edge/errors.py

@@ -17,6 +17,7 @@ __all__ = [
     "AuthenticationFailedError",
     "AuthorizationFailedError",
     "DeviceNotFoundError",
+    "DeviceIdMismatchError",
     "DeviceRevokedError",
     "InvalidMessageError",
     "InvalidProtocolVersionError",
@@ -25,6 +26,9 @@ __all__ = [
     "DuplicateMessageError",
     "EffectNotFoundError",
     "EffectExpiredError",
+    "SessionRequiredError",
+    "SessionInvalidError",
+    "DeliveryFailedError",
     "TransportError",
     "HTTP_STATUS",
     "error_response",
@@ -50,6 +54,9 @@ class EdgeErrorCode:
     DUPLICATE_MESSAGE = "DUPLICATE_MESSAGE"
     EFFECT_NOT_FOUND = "EFFECT_NOT_FOUND"
     EFFECT_EXPIRED = "EFFECT_EXPIRED"
+    SESSION_REQUIRED = "SESSION_REQUIRED"
+    SESSION_INVALID = "SESSION_INVALID"
+    DELIVERY_FAILED = "DELIVERY_FAILED"
     TRANSPORT_ERROR = "TRANSPORT_ERROR"
 
 
@@ -66,6 +73,9 @@ HTTP_STATUS: dict[str, int] = {
     EdgeErrorCode.DUPLICATE_MESSAGE: 200,  # idempotent success, not an error for the client
     EdgeErrorCode.EFFECT_NOT_FOUND: 404,
     EdgeErrorCode.EFFECT_EXPIRED: 410,
+    EdgeErrorCode.SESSION_REQUIRED: 401,
+    EdgeErrorCode.SESSION_INVALID: 401,
+    EdgeErrorCode.DELIVERY_FAILED: 502,
     EdgeErrorCode.TRANSPORT_ERROR: 502,
 }
 
@@ -163,6 +173,41 @@ class TransportError(EdgeError):
     status = 502
 
 
+class SessionRequiredError(AuthenticationFailedError):
+    """Request requires an authenticated session."""
+
+    code = EdgeErrorCode.SESSION_REQUIRED
+    status = 401
+
+
+class SessionInvalidError(AuthenticationFailedError):
+    """Session ID is invalid or expired."""
+
+    code = EdgeErrorCode.SESSION_INVALID
+    status = 401
+
+
+class DeliveryFailedError(TransportError):
+    """Effect delivery failed after max retries."""
+
+    code = EdgeErrorCode.DELIVERY_FAILED
+    status = 502
+
+
+class DeviceIdMismatchError(AuthorizationFailedError):
+    """Message device_id does not match the authenticated device."""
+
+    code = EdgeErrorCode.AUTHORIZATION_FAILED
+
+
+class PayloadTooLargeError(InvalidMessageError):
+    """Message or state payload exceeds configured size limit."""
+
+    code = EdgeErrorCode.INVALID_MESSAGE
+    status = 413
+    status = 403
+
+
 # ---------------------------------------------------------------------------
 # Serialization
 # ---------------------------------------------------------------------------