qx-core 0.1.0__tar.gz

qx_core-0.1.0/.gitignore

@@ -0,0 +1,51 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+eggs/
+.eggs/
+sdist/
+wheels/
+*.egg-link
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# uv
+.uv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Type checking
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Docker
+*.env.local
+
+# Dist artifacts
+dist/

qx_core-0.1.0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: qx-core
+Version: 0.1.0
+Summary: Qx framework core primitives: Result, Error, Entity, RequestContext
+Author: Qx Engineering
+License: MIT
+Requires-Python: >=3.14
+Requires-Dist: pydantic-settings>=2.4.0
+Requires-Dist: pydantic>=2.8.0
+Requires-Dist: typing-extensions>=4.12.0
+Description-Content-Type: text/markdown
+
+# qx-core
+
+Foundational primitives for the Qx framework.
+
+## What lives here
+
+- **`qx.core.result`** — `Result[T]` algebraic type with success/failure variants and combinators.
+- **`qx.core.errors`** — Canonical error hierarchy (`Error`, `ValidationError`, `DomainError`, `NotFoundError`, etc.) used across the framework. HTTP/gRPC layers map these to transport codes.
+- **`qx.core.entities`** — Base `Entity`, `AggregateRoot`, and `ValueObject` with auditing, optimistic concurrency, and soft-delete.
+- **`qx.core.context`** — `RequestContext` propagated via `contextvars` across async boundaries (request_id, correlation_id, trace_id, user_id, tenant_id).
+- **`qx.core.domain`** — `DomainEvent`, `IntegrationEvent`, `Notification` base types.
+- **`qx.core.types`** — Common types: `Identifier`, `Page`, `Cursor`, `Sort`, `Filter`.
+- **`qx.core.config`** — Layered configuration via `pydantic-settings`.
+
+## Design rules
+
+- This package has **zero infrastructure dependencies**. No SQLAlchemy, no Redis, no FastAPI, no NATS.
+- Public API is exported from `qx.core`. Submodules are implementation detail and may move.
+- Backward compatibility from `0.x` is best-effort; `1.0` will lock the API surface.

qx_core-0.1.0/README.md

@@ -0,0 +1,19 @@
+# qx-core
+
+Foundational primitives for the Qx framework.
+
+## What lives here
+
+- **`qx.core.result`** — `Result[T]` algebraic type with success/failure variants and combinators.
+- **`qx.core.errors`** — Canonical error hierarchy (`Error`, `ValidationError`, `DomainError`, `NotFoundError`, etc.) used across the framework. HTTP/gRPC layers map these to transport codes.
+- **`qx.core.entities`** — Base `Entity`, `AggregateRoot`, and `ValueObject` with auditing, optimistic concurrency, and soft-delete.
+- **`qx.core.context`** — `RequestContext` propagated via `contextvars` across async boundaries (request_id, correlation_id, trace_id, user_id, tenant_id).
+- **`qx.core.domain`** — `DomainEvent`, `IntegrationEvent`, `Notification` base types.
+- **`qx.core.types`** — Common types: `Identifier`, `Page`, `Cursor`, `Sort`, `Filter`.
+- **`qx.core.config`** — Layered configuration via `pydantic-settings`.
+
+## Design rules
+
+- This package has **zero infrastructure dependencies**. No SQLAlchemy, no Redis, no FastAPI, no NATS.
+- Public API is exported from `qx.core`. Submodules are implementation detail and may move.
+- Backward compatibility from `0.x` is best-effort; `1.0` will lock the API surface.

qx_core-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "qx-core"
+version = "0.1.0"
+description = "Qx framework core primitives: Result, Error, Entity, RequestContext"
+requires-python = ">=3.14"
+license = { text = "MIT" }
+authors = [{ name = "Qx Engineering" }]
+readme = "README.md"
+dependencies = [
+    "pydantic>=2.8.0",
+    "pydantic-settings>=2.4.0",
+    "typing-extensions>=4.12.0",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/qx"]

qx_core-0.1.0/src/qx/core/__init__.py

@@ -0,0 +1,130 @@
+"""Public surface of ``qx-core``.
+
+Import from this module rather than from internal submodules; the submodule
+layout is subject to change while this surface is stable.
+"""
+
+from __future__ import annotations
+
+from qx.core.config import (
+    AppSection,
+    Environment,
+    LoggingSection,
+    QxSettings,
+)
+from qx.core.context import (
+    RequestContext,
+    current_context,
+    request_scope,
+    reset_context,
+    set_context,
+)
+from qx.core.domain.audit import AuditAction, AuditEntry
+from qx.core.domain.events import (
+    DomainEvent,
+    Event,
+    IntegrationEvent,
+    Notification,
+)
+from qx.core.entities import (
+    AggregateRoot,
+    Entity,
+    Identifier,
+    ValueObject,
+    aggregate,
+    entity,
+    uuid4,
+    uuid7,
+)
+from qx.core.errors import (
+    ConfigurationError,
+    ConflictError,
+    DomainError,
+    Error,
+    ErrorException,
+    ForbiddenError,
+    InfrastructureError,
+    NotFoundError,
+    PreconditionFailedError,
+    RateLimitedError,
+    TimeoutError,
+    UnauthorizedError,
+    ValidationError,
+)
+from qx.core.result import Failure, Result, Success
+from qx.core.types.pagination import (
+    CursorPage,
+    CursorPagination,
+    Filter,
+    FilterOp,
+    OffsetPage,
+    OffsetPagination,
+    Page,
+    Sort,
+    SortDirection,
+)
+from qx.core.utils.time import utcnow
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AggregateRoot",
+    "AppSection",
+    # Audit
+    "AuditAction",
+    "AuditEntry",
+    "ConfigurationError",
+    "ConflictError",
+    "CursorPage",
+    "CursorPagination",
+    "DomainError",
+    "DomainEvent",
+    "Entity",
+    "Environment",
+    # Errors
+    "Error",
+    "ErrorException",
+    # Domain events
+    "Event",
+    "Failure",
+    "Filter",
+    "FilterOp",
+    "ForbiddenError",
+    # Entities
+    "Identifier",
+    "InfrastructureError",
+    "IntegrationEvent",
+    "LoggingSection",
+    "NotFoundError",
+    "Notification",
+    "OffsetPage",
+    # Pagination/filter
+    "OffsetPagination",
+    "Page",
+    "PreconditionFailedError",
+    # Config
+    "QxSettings",
+    "RateLimitedError",
+    # Context
+    "RequestContext",
+    # Result
+    "Result",
+    "Sort",
+    "SortDirection",
+    "Success",
+    "TimeoutError",
+    "UnauthorizedError",
+    "ValidationError",
+    "ValueObject",
+    "__version__",
+    "aggregate",
+    "current_context",
+    "entity",
+    "request_scope",
+    "reset_context",
+    "set_context",
+    # Utils
+    "utcnow",
+    "uuid4",
+    "uuid7",
+]

qx_core-0.1.0/src/qx/core/config/__init__.py

@@ -0,0 +1,87 @@
+"""Layered configuration via :mod:`pydantic_settings`.
+
+Resolution order (highest priority first):
+
+1. Explicit constructor arguments
+2. Environment variables (prefix: ``QX_``)
+3. ``.env.{environment}`` file
+4. ``.env.local`` file
+5. ``.env`` file
+6. Defaults declared on the settings class
+
+The ``environment`` selector itself comes from the env var ``QX_ENV``
+(``local`` | ``dev`` | ``staging`` | ``prod``). Default is ``local``.
+
+Services subclass ``QxSettings`` and add their own sections. Avoid putting
+service-specific knobs on the framework base — those belong to the service.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import ClassVar, Literal
+
+from pydantic import Field
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+__all__ = ["AppSection", "Environment", "LoggingSection", "QxSettings"]
+
+Environment = Literal["local", "dev", "staging", "prod", "test"]
+
+
+def _detect_env() -> Environment:
+    raw = os.environ.get("QX_ENV", "local").lower()
+    if raw in {"local", "dev", "staging", "prod", "test"}:
+        return raw  # type: ignore[return-value]
+    return "local"
+
+
+def _env_file_chain() -> tuple[str, ...]:
+    """Return the chain of .env files, lowest priority first.
+
+    pydantic-settings merges multiple env files with later ones overriding
+    earlier ones. We want the most-specific file to override less-specific.
+    """
+    env = _detect_env()
+    cwd = Path.cwd()
+    candidates: list[Path] = [
+        cwd / ".env",
+        cwd / ".env.local",
+        cwd / f".env.{env}",
+    ]
+    return tuple(str(p) for p in candidates if p.exists())
+
+
+class AppSection(BaseSettings):
+    name: str = Field(default="qx-service")
+    version: str = Field(default="0.0.0")
+    instance_id: str | None = Field(default=None)
+
+
+class LoggingSection(BaseSettings):
+    level: Literal["DEBUG", "INFO", "WARNING", "ERROR"] = "INFO"
+    json_output: bool = True
+    include_caller: bool = False
+
+
+class QxSettings(BaseSettings):
+    """Base settings.
+
+    Services should subclass and add their own sub-models (database, redis,
+    nats, third-party integrations). Keep secrets out of defaults — pydantic
+    will load them from env at runtime.
+    """
+
+    model_config: ClassVar[SettingsConfigDict] = SettingsConfigDict(
+        env_prefix="QX_",
+        env_nested_delimiter="__",
+        env_file=_env_file_chain(),
+        env_file_encoding="utf-8",
+        extra="ignore",
+        case_sensitive=False,
+    )
+
+    environment: Environment = Field(default_factory=_detect_env)
+    app: AppSection = Field(default_factory=AppSection)
+    logging: LoggingSection = Field(default_factory=LoggingSection)

qx_core-0.1.0/src/qx/core/context/__init__.py

@@ -0,0 +1,133 @@
+"""Request-scoped context propagated via :mod:`contextvars`.
+
+Every request, message consumption, or scheduled job runs inside a
+``RequestContext`` that carries the standard correlation, tracing, and tenancy
+fields. The context is set at the edge (HTTP middleware, NATS subscriber
+wrapper, CLI command entrypoint) and read everywhere downstream — logs,
+spans, repositories, domain events — without threading it through every
+function signature.
+
+Implementation choice: ``contextvars.ContextVar`` rather than a global. This
+makes the context **task-local** under asyncio, so concurrent requests in the
+same process don't see each other's data. This is non-negotiable for
+correctness.
+
+Read pattern::
+
+    from qx.core.context import current_context
+    ctx = current_context()
+    log.info("processing", correlation_id=ctx.correlation_id)
+
+Write pattern (edge code only)::
+
+    with request_scope(correlation_id=cid, user_id=uid):
+        await handler.run()
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+from contextvars import ContextVar, Token
+from dataclasses import dataclass, field, replace
+from typing import TYPE_CHECKING, Any
+from uuid import UUID, uuid4
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+__all__ = [
+    "RequestContext",
+    "current_context",
+    "request_scope",
+    "reset_context",
+    "set_context",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class RequestContext:
+    """Immutable per-request context.
+
+    All fields are optional except ``correlation_id`` and ``request_id``, which
+    we always synthesize at edges if the caller didn't provide one. Making this
+    frozen forces deliberate mutation via ``with_changes`` — accidental updates
+    inside a handler can't silently leak to siblings.
+    """
+
+    request_id: UUID = field(default_factory=uuid4)
+    correlation_id: UUID = field(default_factory=uuid4)
+    trace_id: str | None = None
+    span_id: str | None = None
+
+    user_id: UUID | None = None
+    tenant_id: UUID | None = None
+    actor_kind: str | None = None  # "user" | "service" | "system"
+
+    # Free-form bag for adapter-specific data (ip address, user-agent, request path).
+    # Don't put large objects here; this gets copied on every context inheritance.
+    attributes: dict[str, Any] = field(default_factory=dict)
+
+    def with_changes(self, **changes: Any) -> RequestContext:
+        return replace(self, **changes)
+
+    def child(self, **overrides: Any) -> RequestContext:
+        """Derive a child context (e.g., when fanning out to background work).
+
+        ``correlation_id`` and ``trace_id`` carry over; ``request_id`` is fresh.
+        """
+        defaults: dict[str, Any] = {
+            "request_id": uuid4(),
+            "correlation_id": self.correlation_id,
+            "trace_id": self.trace_id,
+            "span_id": self.span_id,
+            "user_id": self.user_id,
+            "tenant_id": self.tenant_id,
+            "actor_kind": self.actor_kind,
+            "attributes": dict(self.attributes),
+        }
+        defaults.update(overrides)
+        return RequestContext(**defaults)
+
+
+_EMPTY = RequestContext()
+_var: ContextVar[RequestContext] = ContextVar("qx_request_context", default=_EMPTY)
+
+
+def current_context() -> RequestContext:
+    """Read the current context. Returns an empty default outside a scope.
+
+    Returning a default rather than raising is intentional: utility code (logging,
+    health checks) should not crash because no scope was established. Edge code
+    that *requires* a context should check ``ctx is not EMPTY`` explicitly.
+    """
+    return _var.get()
+
+
+def set_context(ctx: RequestContext) -> Token[RequestContext]:
+    """Imperative setter. Prefer ``request_scope`` for structured use."""
+    return _var.set(ctx)
+
+
+def reset_context(token: Token[RequestContext]) -> None:
+    _var.reset(token)
+
+
+@contextmanager
+def request_scope(
+    ctx: RequestContext | None = None,
+    /,
+    **overrides: Any,
+) -> Iterator[RequestContext]:
+    """Establish a request-scoped context.
+
+    Either pass a fully-built ``ctx``, or pass kwargs to derive a fresh context
+    from the current one (which may be the empty default).
+    """
+    if ctx is None:
+        base = current_context()
+        ctx = base.with_changes(**overrides) if overrides else base.child()
+    token = _var.set(ctx)
+    try:
+        yield ctx
+    finally:
+        _var.reset(token)

qx_core-0.1.0/src/qx/core/domain/audit.py

@@ -0,0 +1,58 @@
+"""Audit log primitive.
+
+Distinct from the per-entity audit *fields* (created_by, updated_by, ...) on
+``Entity``. Those describe the *current* state; this is the *history* of state
+changes, written as an append-only stream. The two are complementary:
+
+- Entity audit fields are cheap to query ("who last touched this user?")
+- Audit log entries are expensive to query but exhaustive ("show me every
+  permission change for this user in 2024")
+
+Audit entries should be written by infrastructure (repository decorators,
+mediator behaviors), never by domain code. The domain doesn't know it's being
+audited — that's the point.
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+from qx.core.utils.time import utcnow
+
+__all__ = ["AuditAction", "AuditEntry"]
+
+AuditAction = str  # Keep as free-form string; conventions: "user.created", "policy.updated"
+
+
+class AuditEntry(BaseModel):
+    """A single audit log row.
+
+    ``before`` and ``after`` are arbitrary JSON-serializable snapshots. For large
+    aggregates, prefer storing a diff rather than full snapshots — the storage
+    layer can compute that. ``correlation_id`` ties multiple entries together
+    when one user action triggers cascading changes.
+    """
+
+    model_config: ClassVar[ConfigDict] = ConfigDict(frozen=True)
+
+    id: UUID = Field(default_factory=uuid4)
+    action: AuditAction
+    entity_type: str
+    entity_id: UUID
+
+    before: dict[str, Any] | None = None
+    after: dict[str, Any] | None = None
+
+    actor_id: UUID | None = None
+    actor_kind: str | None = None
+    tenant_id: UUID | None = None
+
+    correlation_id: UUID | None = None
+    trace_id: str | None = None
+    ip_address: str | None = None
+    user_agent: str | None = None
+
+    occurred_at: Any = Field(default_factory=utcnow)
+    metadata: dict[str, Any] = Field(default_factory=dict)

qx_core-0.1.0/src/qx/core/domain/events.py

@@ -0,0 +1,114 @@
+"""Event base types.
+
+We distinguish three flavors of "something happened" messaging:
+
+1. **DomainEvent** — in-process, fired inside a transaction, processed by other
+   parts of the same service. Handlers run synchronously with the writing
+   transaction so failures roll back. Example: "user registered" updating a
+   read model.
+
+2. **IntegrationEvent** — cross-process, published to other services via the
+   outbox. Never dispatched in-process; always durable. Example: "user
+   registered" notifying the billing service.
+
+3. **Notification** — in-process, fire-and-forget, side-channel. Used for
+   logging, audit, metrics. Failures in notification handlers should not affect
+   the originating command. Example: "audit log this admin action".
+
+The three types share base fields but the dispatcher treats them differently.
+Mixing them up is the most common CQRS mistake — when in doubt, choose the more
+restrictive option.
+"""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+from qx.core.utils.time import utcnow
+
+__all__ = [
+    "DomainEvent",
+    "Event",
+    "IntegrationEvent",
+    "Notification",
+]
+
+
+class Event(BaseModel):
+    """Base event. Carries identity, timing, causation, correlation.
+
+    Subclasses set ``event_name`` as a stable string used by routers and the
+    outbox schema. The ``version`` field lets the same logical event evolve
+    without breaking subscribers — bump it when the payload shape changes in a
+    non-additive way.
+    """
+
+    model_config: ClassVar[ConfigDict] = ConfigDict(
+        frozen=True,
+        extra="forbid",
+    )
+
+    event_id: UUID = Field(default_factory=uuid4)
+    event_name: ClassVar[str] = ""  # subclasses must override
+    event_version: ClassVar[int] = 1
+
+    occurred_at: Any = Field(default_factory=utcnow)
+    correlation_id: UUID | None = None
+    causation_id: UUID | None = None
+    tenant_id: UUID | None = None
+    actor_id: UUID | None = None
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+        # Enforce that concrete events define event_name. Abstract intermediates
+        # (DomainEvent, IntegrationEvent, Notification) are skipped.
+        if cls.__name__ in {"DomainEvent", "IntegrationEvent", "Notification"}:
+            return
+        if not cls.event_name:
+            raise TypeError(
+                f"{cls.__qualname__} must define a non-empty class-level "
+                "`event_name` for routing and outbox storage."
+            )
+
+    def envelope(self) -> dict[str, Any]:
+        """Serialization envelope used by outbox and message bus."""
+        return {
+            "event_id": str(self.event_id),
+            "event_name": self.event_name,
+            "event_version": self.event_version,
+            "occurred_at": self.occurred_at.isoformat(),
+            "correlation_id": str(self.correlation_id) if self.correlation_id else None,
+            "causation_id": str(self.causation_id) if self.causation_id else None,
+            "tenant_id": str(self.tenant_id) if self.tenant_id else None,
+            "actor_id": str(self.actor_id) if self.actor_id else None,
+            "payload": self.model_dump(
+                mode="json",
+                exclude={
+                    "event_id",
+                    "occurred_at",
+                    "correlation_id",
+                    "causation_id",
+                    "tenant_id",
+                    "actor_id",
+                },
+            ),
+        }
+
+
+class DomainEvent(Event):
+    """In-process event. Handlers run in the writing transaction."""
+
+
+class IntegrationEvent(Event):
+    """Cross-process event. Published via the transactional outbox.
+
+    Subclasses should consider their payload a public schema contract: subscribers
+    in other services rely on field stability. Bump ``event_version`` for breaking
+    changes and keep both versions live during the migration window.
+    """
+
+
+class Notification(Event):
+    """In-process fire-and-forget event. Failures do not affect the originator."""