tigrbl-runtime 0.1.0.dev1__tar.gz

tigrbl_runtime-0.1.0.dev1/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: tigrbl-runtime
+Version: 0.1.0.dev1
+Summary: Runtime pipeline and executor components for Tigrbl.
+License-Expression: Apache-2.0
+Keywords: tigrbl,sdk,standards,framework
+Author: Jacob Stewart
+Author-email: jacob@swarmauri.com
+Requires-Python: >=3.10,<3.13
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Development Status :: 1 - Planning
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Dist: tigrbl-kernel
+Description-Content-Type: text/markdown
+
+![Tigrbl branding](https://github.com/swarmauri/swarmauri-sdk/blob/a170683ecda8ca1c4f912c966d4499649ffb8224/assets/tigrbl.brand.theme.svg)
+
+# tigrbl-runtime
+
+![PyPI - Downloads](https://img.shields.io/pypi/dm/tigrbl-runtime.svg) ![Hits](https://hits.sh/github.com/swarmauri/swarmauri-sdk.svg) ![Python Versions](https://img.shields.io/pypi/pyversions/tigrbl-runtime.svg) ![License](https://img.shields.io/pypi/l/tigrbl-runtime.svg) ![Version](https://img.shields.io/pypi/v/tigrbl-runtime.svg)
+
+## Features
+
+- Modular package in the Tigrbl namespace.
+- Supports Python 3.10 through 3.12.
+- Distributed as part of the swarmauri-sdk workspace.
+
+## Installation
+
+### uv
+
+```bash
+uv add tigrbl-runtime
+```
+
+### pip
+
+```bash
+pip install tigrbl-runtime
+```
+
+## Usage
+
+Import from the shared package-specific module namespaces after installation in your environment.
+

tigrbl_runtime-0.1.0.dev1/README.md

@@ -0,0 +1,29 @@
+![Tigrbl branding](https://github.com/swarmauri/swarmauri-sdk/blob/a170683ecda8ca1c4f912c966d4499649ffb8224/assets/tigrbl.brand.theme.svg)
+
+# tigrbl-runtime
+
+![PyPI - Downloads](https://img.shields.io/pypi/dm/tigrbl-runtime.svg) ![Hits](https://hits.sh/github.com/swarmauri/swarmauri-sdk.svg) ![Python Versions](https://img.shields.io/pypi/pyversions/tigrbl-runtime.svg) ![License](https://img.shields.io/pypi/l/tigrbl-runtime.svg) ![Version](https://img.shields.io/pypi/v/tigrbl-runtime.svg)
+
+## Features
+
+- Modular package in the Tigrbl namespace.
+- Supports Python 3.10 through 3.12.
+- Distributed as part of the swarmauri-sdk workspace.
+
+## Installation
+
+### uv
+
+```bash
+uv add tigrbl-runtime
+```
+
+### pip
+
+```bash
+pip install tigrbl-runtime
+```
+
+## Usage
+
+Import from the shared package-specific module namespaces after installation in your environment.

tigrbl_runtime-0.1.0.dev1/pyproject.toml

@@ -0,0 +1,42 @@
+[project]
+name = "tigrbl-runtime"
+version = "0.1.0.dev1"
+description = "Runtime pipeline and executor components for Tigrbl."
+license = "Apache-2.0"
+readme = "README.md"
+repository = "http://github.com/swarmauri/swarmauri-sdk"
+requires-python = ">=3.10,<3.13"
+classifiers = [
+    "License :: OSI Approved :: Apache Software License",
+    "Development Status :: 1 - Planning",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+]
+authors = [{ name = "Jacob Stewart", email = "jacob@swarmauri.com" }]
+dependencies = [
+    "tigrbl-kernel",
+]
+keywords = ["tigrbl", "sdk", "standards", "framework"]
+
+[tool.uv.sources]
+"tigrbl-kernel" = { workspace = true }
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+
+[tool.poetry]
+packages = [
+    { include = "tigrbl_runtime" },
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.9",
+]

tigrbl_runtime-0.1.0.dev1/tigrbl_runtime/runtime/README.md

@@ -0,0 +1,180 @@
+# Runtime Execution Module (v3)
+
+> **Maintainer-only:** This module is internal to the SDK. Downstream users **must not** modify or rely on it directly.
+
+The runtime executor coordinates Tigrbl operations through a fixed set of **phase chains**. Each phase has a list of steps built by the kernel and is executed under strict database guards.
+
+## Kernel Architecture Form
+
+Tigrbl's runtime kernel follows a **compiled spec form with predicate-gated
+phase-chain execution**. It is not imperative request handling and not purely
+declarative configuration.
+
+The kernel form is:
+
+`Spec → Normalization → Compilation → KernelPlan → PhaseChain execution over GwRawEnvelope`
+
+1. `AppSpec` is normalized into `NormalizedSpec`.
+2. `NormalizedSpec` is compiled once into a deterministic `KernelPlan`.
+3. `Executor(plan).invoke(env)` executes ordered phase chains over a raw
+   transport envelope.
+
+At runtime, the executor behaves like a compiled plan engine:
+
+- compile once and cache the plan,
+- run ingress chain,
+- resolve an operation key by indexed protocol lookup,
+- run operation chain,
+- run egress chain.
+
+Dispatch is index-based (`proto_indices[proto][route_key] -> opkey`), not
+router traversal. Operation metadata (`opmeta[opkey]`) drives deterministic
+execution.
+
+### Canonical KernelPlan Shape
+
+Conceptually, the compiled plan contains:
+
+- `proto_indices` – protocol-to-route hash maps for O(1) dispatch,
+- `opmeta` – operation metadata keyed by operation key,
+- `ingress_chain` – ordered atoms before operation execution,
+- `op_chains` – per-operation ordered atoms,
+- `egress_chain` – ordered atoms after operation execution.
+
+Atoms are small execution units with optional predicates. Predicate checks gate
+execution without introducing heuristic branching in the executor.
+
+### Classification
+
+In systems terms, the runtime kernel is a deterministic, compiled,
+phase-oriented dispatch engine derived from normalized application
+specification. This gives:
+
+- compile-once / execute-many behavior,
+- deterministic and inspectable plans,
+- protocol abstraction over a raw envelope,
+- phase-level security and diagnostics injection,
+- consistent phase ordering.
+
+## Phase Chains
+
+Phase chains map phase names to ordered handler lists. The executor runs the phases in the sequence below:
+
+1. `PRE_TX_BEGIN` – pre-transaction checks.
+2. `START_TX` – open a new transaction (system-only).
+3. `PRE_HANDLER` – request validation and setup.
+4. `HANDLER` – core operation logic.
+5. `POST_HANDLER` – post-processing while still in the transaction.
+6. `PRE_COMMIT` – final checks before committing.
+7. `END_TX` – commit and close the transaction.
+8. `POST_COMMIT` – steps after commit.
+9. `POST_RESPONSE` – fire-and-forget side effects.
+
+## Step Kinds
+
+The kernel labels every piece of work so it can be ordered predictably:
+
+- **secdeps** – security dependencies that run before any other steps. Downstream
+  applications configure these to enforce authentication or authorization.
+- **deps** – general dependencies resolved ahead of handlers. These are also
+  provided downstream.
+- **sys** – system steps shipped with Tigrbl to coordinate core behavior. They
+  are maintained by project maintainers.
+- **atoms** – built-in runtime units such as schema collectors or wire
+  serializers. Maintainers own these components.
+- **hooks** – user-supplied handlers that attach to anchors within phases.
+
+Downstream consumers configure `secdeps`, `deps`, and `hooks`, while `sys` and
+`atom` steps are maintained by the Tigrbl maintainers.
+
+
+## Step Precedence
+
+When the kernel assembles an operation it flattens several step kinds into a
+single execution plan. They run in the following precedence:
+
+1. Security dependencies (`secdeps`)
+2. General dependencies (`deps`)
+3. System steps (`sys`) such as transaction begin, handler dispatch, and commit
+4. Runtime atoms (`atoms`)
+5. Hooks (`hooks`)
+
+System steps appear only on the `START_TX`, `HANDLER`, and `END_TX` anchors. Within
+each anchor, atoms execute before hooks and any remaining ties are resolved by
+anchor-specific preferences.
+
+## Atom Domains
+
+Atoms are grouped into domain-specific registries so the kernel can inject them
+at the correct stage of the lifecycle. Each domain focuses on a different slice
+of request or response processing:
+
+- **wire** – builds inbound data, validates it, and prepares outbound payloads at
+  the field level.
+- **schema** – collects request and response schema definitions for models.
+- **resolve** – assembles derived values or generates paired inputs before they
+  are flushed.
+- **storage** – converts field specifications into storage-layer instructions.
+- **emit** – surfaces runtime metadata such as aliases or extras for downstream
+  consumers.
+- **out** – mutates data after handlers run, for example masking fields before
+  serialization.
+- **response** – negotiates content types and renders the final HTTP response or
+  template.
+- **refresh** – triggers post-commit refreshes like demand-driven reloads.
+
+Domains differ by the moment they run and the guarantees they provide. A `wire`
+atom transforms raw request values before validation, whereas a `response` atom
+operates after the transaction is committed to shape the returned payload. The
+kernel uses the pair `(domain, subject)` to register and inject atoms into phase
+chains.
+
+## DB Guards
+
+For every phase the executor installs database guards that monkey‑patch
+`commit` and `flush` on the session. Guards enforce which operations are
+allowed and ensure only the owning transaction may commit.
+
+The guard installer swaps these methods with stubs that raise
+`RuntimeError` when a disallowed operation is attempted. Each phase passes
+flags describing its policy:
+
+- `allow_flush` – permit calls to `session.flush`.
+- `allow_commit` – permit calls to `session.commit`.
+- `require_owned_tx_for_commit` – when `True`, block commits if the
+  executor did not open the transaction.
+
+The installer returns a handle that restores the original methods once the
+phase finishes so restrictions do not leak across phases. A companion
+helper triggers a rollback if the runtime owns the transaction and a phase
+raises an error.
+
+| Phase | Flush | Commit | Notes |
+|-------|-------|--------|-------|
+| PRE_TX_BEGIN | ❌ | ❌ | no database writes |
+| START_TX | ❌ | ❌ | transaction opening |
+| PRE_HANDLER | ✅ | ❌ | writes allowed, commit blocked |
+| HANDLER | ✅ | ❌ | writes allowed, commit blocked |
+| POST_HANDLER | ✅ | ❌ | writes allowed, commit blocked |
+| PRE_COMMIT | ❌ | ❌ | freeze writes before commit |
+| END_TX | ✅ | ✅ | commit allowed only if runtime owns the transaction |
+| POST_COMMIT | ✅ | ❌ | post-commit writes without commit |
+| POST_RESPONSE | ❌ | ❌ | background work, no writes |
+
+### Transaction Boundaries
+
+`start_tx` is a system step that opens a new database transaction when
+no transaction is active and marks the runtime as its owner. While this
+phase runs, both `session.flush` and `session.commit` are blocked. After a
+transaction is started, phases such as `PRE_HANDLER`, `HANDLER`, and
+`POST_HANDLER` allow flushes so SQL statements can be issued while the
+commit remains deferred. The `end_tx` step executes during the `END_TX`
+phase, performing a final flush and committing the transaction if the
+runtime owns it. Once this phase completes, guards restore the original
+session methods.
+
+If a phase fails, the guard restores the original methods and the executor rolls back when it owns the transaction. Optional `ON_<PHASE>_ERROR` chains can handle cleanup.
+
+---
+
+This runtime layer is maintained by the core team. Downstream packages should treat it as read‑only and interact only through the public Tigrbl interfaces.

tigrbl_runtime-0.1.0.dev1/tigrbl_runtime/runtime/__init__.py

@@ -0,0 +1,20 @@
+# tigrbl/runtime/__init__.py
+from .executor import _invoke, _Ctx
+from .kernel import Kernel, build_phase_chains, run, get_cached_specs, _default_kernel
+from . import events, status, context
+from .labels import STEP_KINDS, DOMAINS
+
+__all__ = [
+    "_invoke",
+    "_Ctx",
+    "Kernel",
+    "build_phase_chains",
+    "run",
+    "get_cached_specs",
+    "_default_kernel",
+    "events",
+    "status",
+    "context",
+    "STEP_KINDS",
+    "DOMAINS",
+]

tigrbl_runtime-0.1.0.dev1/tigrbl_runtime/runtime/context.py

@@ -0,0 +1,206 @@
+# tigrbl/runtime/context.py
+from __future__ import annotations
+
+import datetime as _dt
+from dataclasses import dataclass, field
+from typing import Any, Dict, Mapping, Optional, Sequence
+
+
+def _canon_op(op: Optional[str]) -> str:
+    return (op or "").strip().lower() or "unknown"
+
+
+@dataclass
+class Context:
+    """
+    Canonical runtime context shared by the kernel and atoms.
+
+    Minimal contract (consumed by atoms we’ve written so far):
+      - op:        operation name (e.g., 'create' | 'update' | 'read' | 'list' | custom)
+      - persist:   write vs. read (affects pruning of persist-tied anchors)
+      - specs:     mapping of field -> ColumnSpec (frozen at bind time)
+      - cfg:       read-only config view (see config.resolver.CfgView)
+      - temp:      dict scratchpad used by atoms to exchange data
+
+    Optional adapter slots:
+      - model:     owning model type / class
+      - obj:       hydrated ORM instance (if any)
+      - session:   DB session / unit-of-work handle
+      - user, tenant, now: identity/time hints
+      - row/values/current_values: mapping fallbacks (for read paths)
+      - in_data / payload / data / body: inbound payload staging (for build_in)
+    """
+
+    # core
+    op: str
+    persist: bool
+    specs: Mapping[str, Any]
+    cfg: Any
+
+    # shared scratchpad
+    temp: Dict[str, Any] = field(default_factory=dict)
+
+    # optional context
+    model: Any | None = None
+    obj: Any | None = None
+    session: Any | None = None
+
+    # identity/time
+    user: Any | None = None
+    tenant: Any | None = None
+    now: _dt.datetime | None = None
+
+    # read-path fallbacks
+    row: Mapping[str, Any] | None = None
+    values: Mapping[str, Any] | None = None
+    current_values: Mapping[str, Any] | None = None
+
+    # inbound staging (router/adapters may set any one of these)
+    in_data: Any | None = None
+    payload: Any | None = None
+    data: Any | None = None
+    body: Any | None = None
+
+    def __post_init__(self) -> None:
+        self.op = _canon_op(self.op)
+        # Normalize now to a timezone-aware UTC timestamp when not provided
+        if self.now is None:
+            try:
+                self.now = _dt.datetime.now(_dt.timezone.utc)
+            except Exception:  # pragma: no cover
+                self.now = _dt.datetime.utcnow().replace(tzinfo=None)
+
+        # Ensure temp is a dict (atoms rely on it)
+        if not isinstance(self.temp, dict):
+            self.temp = dict(self.temp)
+
+    # ── convenience flags ─────────────────────────────────────────────────────
+
+    @property
+    def is_write(self) -> bool:
+        """Alias for persist; reads better in some call sites."""
+        return bool(self.persist)
+
+    # ── safe read-only view for user callables (generators, default_factory) ──
+
+    def safe_view(
+        self,
+        *,
+        include_temp: bool = False,
+        temp_keys: Optional[Sequence[str]] = None,
+    ) -> Mapping[str, Any]:
+        """
+        Return a small, read-only mapping exposing only safe, frequently useful keys.
+
+        By default, temp is NOT included (to avoid leaking internals like paired raw values).
+        If include_temp=True, only exposes the keys listed in 'temp_keys' (if provided),
+        otherwise exposes a conservative subset.
+
+        This method is intended to be passed into author callables such as
+        default_factory(ctx_view) or paired token generators.
+        """
+        base = {
+            "op": self.op,
+            "persist": self.persist,
+            "model": self.model,
+            "specs": self.specs,
+            "user": self.user,
+            "tenant": self.tenant,
+            "now": self.now,
+        }
+        if include_temp:
+            allowed = set(temp_keys or ("assembled_values", "virtual_in"))
+            exposed: Dict[str, Any] = {}
+            for k in allowed:
+                if k in self.temp:
+                    exposed[k] = self.temp[k]
+            base = {**base, "temp": MappingProxy(exposed)}
+        return MappingProxy(base)
+
+    # ── tiny helpers used by atoms / kernel ───────────────────────────────────
+
+    def mark_used_returning(self, value: bool = True) -> None:
+        """Flag that DB RETURNING already hydrated values."""
+        self.temp["used_returning"] = bool(value)
+
+    def merge_hydrated_values(
+        self, mapping: Mapping[str, Any], *, replace: bool = False
+    ) -> None:
+        """
+        Save values hydrated from DB (RETURNING/refresh). If replace=False (default),
+        performs a shallow merge into any existing 'hydrated_values'.
+        """
+        if not isinstance(mapping, Mapping):
+            return
+        hv = self.temp.get("hydrated_values")
+        if replace or not isinstance(hv, dict):
+            self.temp["hydrated_values"] = dict(mapping)
+        else:
+            hv.update(mapping)
+
+    def add_response_extras(
+        self, extras: Mapping[str, Any], *, overwrite: Optional[bool] = None
+    ) -> Sequence[str]:
+        """
+        Merge alias extras into temp['response_extras'].
+        Returns a tuple of conflicting keys that were skipped when overwrite=False.
+        """
+        if not isinstance(extras, Mapping) or not extras:
+            return ()
+        buf = self.temp.get("response_extras")
+        if not isinstance(buf, dict):
+            buf = {}
+            self.temp["response_extras"] = buf
+        if overwrite is None:
+            # fall back to cfg; atoms call wire:dump to honor final overwrite policy
+            overwrite = bool(getattr(self.cfg, "response_extras_overwrite", False))
+        conflicts: list[str] = []
+        for k, v in extras.items():
+            if (k in buf) and not overwrite:
+                conflicts.append(k)
+                continue
+            buf[k] = v
+        return tuple(conflicts)
+
+    def get_response_payload(self) -> Any:
+        """Return the payload assembled by wire:dump (or None if not yet available)."""
+        return self.temp.get("response_payload")
+
+    # ── representation (avoid leaking large/sensitive temp contents) ──────────
+
+    def __repr__(self) -> str:  # pragma: no cover
+        model_name = getattr(self.model, "__name__", None) or str(self.model)
+        return (
+            f"Context(op={self.op!r}, persist={self.persist}, model={model_name!r}, "
+            f"user={(getattr(self.user, 'id', None) or None)!r}, temp_keys={sorted(self.temp.keys())})"
+        )
+
+
+# ── tiny immutable mapping proxy (local; no external deps) ────────────────────
+
+
+class MappingProxy(Mapping[str, Any]):
+    """A lightweight, read-only mapping wrapper."""
+
+    __slots__ = ("_d",)
+
+    def __init__(self, data: Mapping[str, Any]):
+        self._d = dict(data)
+
+    def __getitem__(self, k: str) -> Any:
+        return self._d[k]
+
+    def __iter__(self):
+        return iter(self._d)
+
+    def __len__(self) -> int:
+        return len(self._d)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self._d.get(key, default)
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"MappingProxy({self._d!r})"
+
+
+__all__ = ["Context", "MappingProxy"]