matrx-runtime 0.0.1__py3-none-any.whl

matrx_runtime/__init__.py

@@ -0,0 +1,146 @@
+"""matrx-runtime — the Request Management Layer.
+
+You hand us a request; we own its entire life and its whole nested tree —
+identity, nesting, status, every failure and success, accumulated cost and any
+metered limit, context propagation, cancellation, and resume — WITHOUT knowing or
+caring what the work is. Payload-blind: never chat, agents, providers, tokens, or
+messages. Feature data stays in the consumer's tables, reached via an opaque
+`link_kind`/`link_id`.
+
+Design: docs/runtime/REQUEST_MANAGEMENT_LAYER.md. Public API = exactly __all__.
+"""
+
+from __future__ import annotations
+
+from matrx_runtime.lifecycle import (
+    ALLOWED_TRANSITIONS,
+    InvalidExecutionTransition,
+    TransitionResult,
+    can_transition,
+    event_for_transition,
+    is_terminal,
+    transition,
+)
+from matrx_runtime.engine import (
+    DEFAULT_LEASE_SECONDS,
+    BudgetExceeded,
+    ConcurrentTransition,
+    DeadlineExceeded,
+    ExecutionCancelled,
+    ExecutionEngine,
+    ExecutionNotFound,
+    ExecutionScope,
+    InvalidLeaseState,
+    LimitExceeded,
+)
+from matrx_runtime.models import (
+    TERMINAL_STATUSES,
+    ContextMode,
+    ExecutionCheckpoint,
+    ExecutionContext,
+    ExecutionControl,
+    ExecutionError,
+    ExecutionEvent,
+    ExecutionEventKind,
+    ExecutionOutcome,
+    ExecutionStatus,
+    ExecutionTree,
+    ExecutionTreeNode,
+    GlobalExecution,
+    MeterEntry,
+    MeterEvent,
+    Origin,
+    Request,
+)
+from matrx_runtime.store import ExecutionStore, InMemoryExecutionStore
+from matrx_runtime.orm_store import OrmExecutionStore
+from matrx_runtime.origins import (
+    OriginSpec,
+    OriginSyncResult,
+    is_caller_allowed,
+    sync_origins,
+)
+from matrx_runtime.db import PACKAGE_DB_NAME, apply_schema, bind_to_host, bootstrap_db
+
+__version__ = "0.0.1"
+
+
+def configure(*, db_config_name: str | None = None) -> None:
+    """Host-injection entry point (called once at startup; mirrors matrx-rag).
+    `db_config_name` is the matrx-orm pool the host already registered — we alias
+    the package's `"matrx_runtime"` name onto it and register the `runtime.*`
+    Models the `OrmExecutionStore` needs. Standalone installs call `bootstrap_db()`."""
+    from matrx_runtime import _config
+
+    if db_config_name is not None:
+        _config.set_db_config_name(db_config_name)
+        from matrx_orm import is_database_registered
+
+        from matrx_runtime.db import bind_to_host as _bind
+
+        if is_database_registered(db_config_name):
+            _bind(db_config_name)
+    _config.mark_configured()
+
+
+def is_configured() -> bool:
+    from matrx_runtime import _config
+
+    return _config.is_configured()
+
+
+__all__ = [
+    # lifecycle
+    "transition",
+    "can_transition",
+    "is_terminal",
+    "event_for_transition",
+    "TransitionResult",
+    "InvalidExecutionTransition",
+    "ALLOWED_TRANSITIONS",
+    # engine
+    "ExecutionEngine",
+    "ExecutionScope",
+    "ExecutionNotFound",
+    "ConcurrentTransition",
+    "BudgetExceeded",
+    "LimitExceeded",
+    "DeadlineExceeded",
+    "ExecutionCancelled",
+    "InvalidLeaseState",
+    "DEFAULT_LEASE_SECONDS",
+    # store
+    "ExecutionStore",
+    "InMemoryExecutionStore",
+    "OrmExecutionStore",
+    # origin registry
+    "OriginSpec",
+    "OriginSyncResult",
+    "sync_origins",
+    "is_caller_allowed",
+    # host wiring / db binding
+    "configure",
+    "is_configured",
+    "bind_to_host",
+    "bootstrap_db",
+    "apply_schema",
+    "PACKAGE_DB_NAME",
+    # models / enums
+    "GlobalExecution",
+    "ExecutionStatus",
+    "ExecutionEventKind",
+    "ContextMode",
+    "ExecutionContext",
+    "ExecutionError",
+    "ExecutionOutcome",
+    "ExecutionControl",
+    "ExecutionEvent",
+    "ExecutionCheckpoint",
+    "ExecutionTree",
+    "ExecutionTreeNode",
+    "MeterEvent",
+    "MeterEntry",
+    "Origin",
+    "Request",
+    "TERMINAL_STATUSES",
+]

matrx_runtime/_config.py

@@ -0,0 +1,52 @@
+"""Host-injection registry — the seam between matrx-runtime and its host.
+
+The host calls :func:`matrx_runtime.configure` once at startup; the package reads
+back what it needs here. Kept tiny and dependency-free (the boundary gate stays
+green). Today the only seam is the matrx-orm pool name the spine persists to; the
+Coordinator/context drops will add their seams here the same way.
+"""
+
+from __future__ import annotations
+
+import os
+
+_registry: dict[str, object] = {
+    # matrx-orm pool identifier the host registered via
+    # register_database_from_env. matrx_runtime.configure(db_config_name=...)
+    # aliases PACKAGE_DB_NAME onto it.
+    "db_config_name": None,
+}
+
+_configured = False
+
+
+def set_db_config_name(name: str) -> None:
+    _registry["db_config_name"] = name
+
+
+def is_configured() -> bool:
+    return _configured
+
+
+def mark_configured() -> None:
+    global _configured
+    _configured = True
+
+
+def get_db_config_name() -> str:
+    """Resolve the host's matrx-orm pool name.
+
+    Order: the name injected via ``configure(db_config_name=...)`` → the
+    ``MATRX_RUNTIME_DB_NAME`` env var (name of an already-registered config).
+    Raises if neither is set — running the ORM-bound store with no configured
+    pool is a wiring bug, surfaced loudly rather than silently no-op'd.
+    """
+    name = _registry.get("db_config_name") or os.environ.get("MATRX_RUNTIME_DB_NAME")
+    if not name:
+        raise RuntimeError(
+            "matrx-runtime: no database configured. Call "
+            "matrx_runtime.configure(db_config_name=<registered matrx-orm pool>) "
+            "at host startup, set MATRX_RUNTIME_DB_NAME, or use "
+            "matrx_runtime.bootstrap_db() for a standalone pool."
+        )
+    return str(name)

matrx_runtime/db/__init__.py

@@ -0,0 +1,217 @@
+"""Database binding for the execution spine.
+
+matrx-runtime ships ONE canonical copy of its `runtime.*` model classes
+(``matrx_runtime.db.models_runtime``) — generated from the live database by the
+host's ``db/generate.py`` run (the ``output:`` entry in aidream's
+``db/matrx_orm.yaml``). Every model bakes ``_database = "matrx_runtime"``
+(:data:`PACKAGE_DB_NAME`). What that name points at is decided exactly once:
+
+* **Hosted** — the host registered its own pool and calls
+  ``matrx_runtime.configure(db_config_name=...)``, which calls
+  :func:`bind_to_host`: a matrx-orm *name alias* maps ``"matrx_runtime"`` onto
+  the host's config. One registration, one physical pool — the package NEVER
+  opens a second connection.
+* **Standalone** — :func:`bootstrap_db` registers the pool from
+  ``MATRX_RUNTIME_POSTGRES_*`` env vars under :data:`PACKAGE_DB_NAME`.
+
+This mirrors matrx-rag's binding exactly (the proven pattern). There is
+deliberately NO ``SET search_path``: every model fully-qualifies its schema
+(``runtime.global_execution``), so the transaction pooler resetting backend
+state between transactions is a non-issue.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING, Any
+from urllib.parse import quote
+
+if TYPE_CHECKING:
+    from asyncpg import Pool
+
+# The config name every matrx-runtime model class is bound to. Hosts alias it to
+# their registered pool (bind_to_host); standalone registers it as a real config
+# (bootstrap_db).
+PACKAGE_DB_NAME = "matrx_runtime"
+
+# Env prefix for TRUE standalone credentials. Deliberately NOT "MATRX_RUNTIME_DB":
+# a MATRX_RUNTIME_DB_NAME env var would mean "name of an already-registered
+# matrx-orm config", which register_database_from_env would misread as the
+# database name (the same trap matrx-rag documents).
+STANDALONE_ENV_PREFIX = "MATRX_RUNTIME_POSTGRES"
+
+_models_registered = False
+
+
+def connection_url() -> str:
+    """Resolve the postgres connection URL for ad-hoc / migration use.
+
+    Priority:
+      1. ``RUNTIME_DATABASE_URL``   — explicit override.
+      2. ``DATABASE_URL``           — generic shared URL.
+      3. ``MATRX_RUNTIME_POSTGRES_*`` — the package's standalone credential set.
+      4. ``SUPABASE_MATRIX_*``      — legacy aidream-flavored fields.
+
+    Raises ``RuntimeError`` if none resolve to a usable URL.
+    """
+    explicit = os.environ.get("RUNTIME_DATABASE_URL") or os.environ.get("DATABASE_URL")
+    if explicit:
+        return explicit
+
+    for prefix in (STANDALONE_ENV_PREFIX, "SUPABASE_MATRIX"):
+        host = os.environ.get(f"{prefix}_HOST")
+        user = os.environ.get(f"{prefix}_USER")
+        password = os.environ.get(f"{prefix}_PASSWORD")
+        if prefix == "SUPABASE_MATRIX":
+            database = os.environ.get("SUPABASE_MATRIX_DATABASE_NAME") or "postgres"
+        else:
+            database = os.environ.get(f"{prefix}_NAME") or "postgres"
+        port = os.environ.get(f"{prefix}_PORT") or "5432"
+        if host and user and password:
+            return (
+                f"postgresql://{quote(user, safe='')}:{quote(password, safe='')}"
+                f"@{host}:{port}/{database}"
+            )
+
+    raise RuntimeError(
+        "matrx-runtime: cannot build database URL — set RUNTIME_DATABASE_URL, "
+        f"DATABASE_URL, the {STANDALONE_ENV_PREFIX}_HOST/USER/PASSWORD trio, or "
+        "the SUPABASE_MATRIX_HOST/USER/PASSWORD trio."
+    )
+
+
+def _register_models() -> None:
+    """Import the generated model module so its classes register.
+
+    The module ends with ``model_registry.register_all(..., skip_existing=True)``
+    so a host's earlier same-name registration always wins.
+    """
+    global _models_registered
+    if _models_registered:
+        return
+    from matrx_runtime.db import models_runtime  # noqa: F401  (registers on import)
+
+    _models_registered = True
+
+
+def bind_to_host(db_config_name: str) -> None:
+    """Hosted entry — point :data:`PACKAGE_DB_NAME` at the host's pool.
+
+    Registers a matrx-orm name alias (idempotent for the same target) and
+    registers the package's ``runtime.*`` model classes. Called automatically by
+    ``matrx_runtime.configure(db_config_name=...)``.
+    """
+    from matrx_orm import is_database_registered, register_database_alias
+
+    if not is_database_registered(PACKAGE_DB_NAME):
+        register_database_alias(PACKAGE_DB_NAME, db_config_name)
+    _register_models()
+
+
+def bootstrap_db(
+    *,
+    env_prefix: str = STANDALONE_ENV_PREFIX,
+    additional_schemas: tuple[str, ...] = ("runtime",),
+    env_var_overrides: dict[str, str] | None = None,
+) -> str:
+    """Standalone entry — register the package's own pool from env vars.
+
+    Reads ``{env_prefix}_HOST/_PORT/_NAME/_USER/_PASSWORD`` and registers the
+    database under :data:`PACKAGE_DB_NAME`, then registers the model set.
+    Idempotent: a host that already registered/aliased the name turns this into
+    a no-op model-registration call. Returns :data:`PACKAGE_DB_NAME`.
+    """
+    from matrx_orm import is_database_registered, register_database_from_env
+
+    if not is_database_registered(PACKAGE_DB_NAME):
+        ok = register_database_from_env(
+            name=PACKAGE_DB_NAME,
+            env_prefix=env_prefix,
+            additional_schemas=list(additional_schemas),
+            env_var_overrides=env_var_overrides,
+        )
+        if not ok:
+            raise RuntimeError(
+                f"matrx-runtime standalone bootstrap failed: missing {env_prefix}_* "
+                "env vars. Either set them, or run hosted via "
+                "matrx_runtime.configure(db_config_name=<registered pool name>)."
+            )
+    _register_models()
+    return PACKAGE_DB_NAME
+
+
+def ensure_bound() -> str:
+    """Resolve the pool name matrx-runtime should use, binding lazily if needed.
+
+    Order: an already-registered/aliased :data:`PACKAGE_DB_NAME` → the
+    host-injected ``db_config_name`` (bound on first use) → raise. The
+    ExecutionStore adapter calls this so the models resolve to a live pool even
+    if ``configure`` was passed a name but ``bind_to_host`` hasn't run yet.
+    """
+    from matrx_orm import is_database_registered
+
+    if is_database_registered(PACKAGE_DB_NAME):
+        _register_models()
+        return PACKAGE_DB_NAME
+
+    from matrx_runtime._config import get_db_config_name
+
+    name = get_db_config_name()  # raises if neither injected name nor env is set
+    if is_database_registered(name):
+        bind_to_host(name)
+        return PACKAGE_DB_NAME
+    # Unregistered name: hand it to matrx-orm unchanged so its own
+    # "Configuration not found" error surfaces.
+    return name
+
+
+def bootstrap_sql_files() -> list[Any]:
+    """The bundled `bootstrap/*.sql` files in apply order (`NNN_*.sql`)."""
+    from pathlib import Path
+
+    return sorted((Path(__file__).parent / "bootstrap").glob("*.sql"))
+
+
+async def apply_schema(*, pool: Pool | None = None) -> list[str]:
+    """Create the standalone substrate on a fresh database — schemas, enums, the
+    actor/timestamp functions, the minimal identity shim, and the `runtime.*` tables +
+    indexes + triggers + RLS. Applies the bundled `bootstrap/*.sql` in order; every
+    statement is idempotent + NON-DESTRUCTIVE, so this is a pure no-op against a host
+    (aidream) that already owns the schema. Standalone flow: `bootstrap_db()` then
+    `await apply_schema()`. Returns the file names applied.
+
+    Design + the non-destructive invariant: docs/runtime/STANDALONE_SUBSTRATE.md.
+    """
+    from matrx_orm.operations.dynamic_admin import execute_sql_script
+
+    applied: list[str] = []
+    for path in bootstrap_sql_files():
+        # execute_sql_script rides asyncpg's simple-query protocol (no bound
+        # params), which is what makes a multi-statement idempotent DDL
+        # script runnable in one call — matrx_orm.operations.dynamic_admin
+        # is the ORM's sanctioned surface for this shape.
+        if pool is not None:
+            await execute_sql_script(path.read_text(), pool=pool)
+        else:
+            await execute_sql_script(path.read_text(), config_name=ensure_bound())
+        applied.append(path.name)
+    return applied
+
+
+def get_models() -> dict[str, Any]:
+    """Return name → Model class for everything the package ships."""
+    _register_models()
+    from matrx_runtime.db import models_runtime
+
+    out: dict[str, Any] = {}
+    for attr in vars(models_runtime).values():
+        if isinstance(attr, type) and getattr(attr, "_table_name", None):
+            out[attr.__name__] = attr
+    return out
+
+
+async def get_pool() -> Pool:
+    """Return the shared matrx-orm asyncpg pool (the host's pool when hosted)."""
+    from matrx_orm.core.async_db_manager import AsyncDatabaseManager
+
+    return await AsyncDatabaseManager.get_pool(ensure_bound())

matrx_runtime/db/bootstrap/000_substrate.sql

@@ -0,0 +1,82 @@
+-- matrx-runtime standalone substrate — 000: schemas + enums + actor/timestamp triggers.
+-- Idempotent + NON-DESTRUCTIVE: every statement is a no-op where the object already
+-- exists (e.g. inside aidream). Portable: no auth.uid(), no Supabase-only objects.
+-- See docs/runtime/STANDALONE_SUBSTRATE.md.
+
+create schema if not exists platform;
+create schema if not exists iam;
+create schema if not exists runtime;
+
+-- Visibility tiers (platform.visibility). Create only if absent — never alter a host's.
+do $do$
+begin
+  if not exists (
+    select 1 from pg_type t join pg_namespace n on n.oid = t.typnamespace
+    where t.typname = 'visibility' and n.nspname = 'platform'
+  ) then
+    create type platform.visibility as enum ('private', 'internal', 'link', 'public');
+  end if;
+end
+$do$;
+
+-- Permission levels (public.permission_level). Create only if absent.
+do $do$
+begin
+  if not exists (
+    select 1 from pg_type t join pg_namespace n on n.oid = t.typnamespace
+    where t.typname = 'permission_level' and n.nspname = 'public'
+  ) then
+    create type public.permission_level as enum ('viewer', 'editor', 'admin');
+  end if;
+end
+$do$;
+
+-- updated_at / version stamping. CREATE-IF-ABSENT (never CREATE OR REPLACE): a host's
+-- own version is NEVER overwritten — the only truly non-destructive rule, now that the
+-- host's functions evolve independently (e.g. aidream's _stamp_actor gained an auth.uid
+-- fallback). The standalone body below is the portable baseline.
+do $do$
+begin
+  if not exists (
+    select 1 from pg_proc p join pg_namespace n on n.oid = p.pronamespace
+    where p.proname = '_touch_row' and n.nspname = 'platform'
+  ) then
+    execute $exec$
+      create function platform._touch_row()
+      returns trigger language plpgsql as $fn$
+      begin
+        new.updated_at := now();
+        if tg_op = 'UPDATE' then new.version := old.version + 1; end if;
+        return new;
+      end
+      $fn$;
+    $exec$;
+  end if;
+end
+$do$;
+
+-- created_by / updated_by stamping. PORTABLE baseline: resolves the actor from the
+-- app.user_id GUC ONLY (no auth.uid() — so it CREATEs on vanilla Postgres). A host on
+-- Supabase keeps its own richer version (e.g. COALESCE(app.user_id, auth.uid())) — this
+-- is create-if-absent, so that version is never touched. The runtime engine sets
+-- created_by explicitly regardless, so attribution is correct on either.
+do $do$
+begin
+  if not exists (
+    select 1 from pg_proc p join pg_namespace n on n.oid = p.pronamespace
+    where p.proname = '_stamp_actor' and n.nspname = 'platform'
+  ) then
+    execute $exec$
+      create function platform._stamp_actor()
+      returns trigger language plpgsql as $fn$
+      declare uid uuid := nullif(current_setting('app.user_id', true), '')::uuid;
+      begin
+        if tg_op = 'INSERT' then new.created_by := coalesce(new.created_by, uid); end if;
+        new.updated_by := coalesce(uid, new.updated_by);
+        return new;
+      end
+      $fn$;
+    $exec$;
+  end if;
+end
+$do$;

matrx_runtime/db/bootstrap/010_identity.sql

@@ -0,0 +1,84 @@
+-- matrx-runtime standalone substrate — 010: MINIMAL portable identity.
+-- The smallest thing that satisfies runtime's organization FK + registry-driven RLS.
+-- Every object is create-if-absent: in aidream the real (richer) organizations +
+-- iam.has_access + registries already exist and are kept UNTOUCHED. This file only
+-- materializes a minimal shim on a bare DB. See docs/runtime/STANDALONE_SUBSTRATE.md.
+
+-- The organization the governed private root is scoped to (global_request.organization_id
+-- FK target). aidream's is 13 cols → auth.users; standalone gets an id-only shim.
+create table if not exists public.organizations (
+  id uuid primary key default gen_random_uuid(),
+  name text,
+  created_at timestamptz not null default now()
+);
+
+-- The registries has_access reads (token → table, and the composition/containment edges).
+create table if not exists platform.entity_types (
+  token text primary key,
+  schema_name text not null,
+  table_name text not null,
+  is_component boolean not null default false
+);
+
+create table if not exists platform.entity_relationships (
+  child_type text not null,
+  parent_type text not null,
+  fk_column text not null,
+  kind text not null,
+  primary key (child_type, parent_type, kind)
+);
+
+-- Portable, fail-closed access resolver. Mirrors aidream's iam.has_access but uses the
+-- app.user_id GUC (not auth.uid()) and resolves only owner + composition + public — the
+-- minimal safe set (grants / org-admin / containment are the host's richer layer). Create
+-- only if absent: aidream's full version is NEVER overwritten.
+do $do$
+begin
+  if not exists (
+    select 1 from pg_proc p join pg_namespace n on n.oid = p.pronamespace
+    where p.proname = 'has_access' and n.nspname = 'iam'
+  ) then
+    execute $exec$
+      create function iam.has_access(p_type text, p_id uuid, p_required permission_level default 'viewer')
+        returns boolean language plpgsql stable security definer
+        set search_path to 'public', 'platform', 'iam'
+      as $fn$
+      declare
+        v_schema text; v_table text; v_is_component boolean;
+        v_uid uuid := nullif(current_setting('app.user_id', true), '')::uuid;
+        v_vis platform.visibility; v_owner uuid; v_org uuid;
+        v_parent_type text; v_parent_col text; v_parent_id uuid;
+      begin
+        if v_uid is null then return false; end if;
+
+        select schema_name, table_name, coalesce(is_component, false)
+          into v_schema, v_table, v_is_component
+        from platform.entity_types where token = p_type;
+        if v_schema is null then return false; end if;
+
+        -- component: access is exactly the parent's, full depth
+        if v_is_component then
+          select parent_type, fk_column into v_parent_type, v_parent_col
+          from platform.entity_relationships where child_type = p_type and kind = 'composition' limit 1;
+          if v_parent_type is null then return false; end if;
+          execute format('select %I from %I.%I where id=$1', v_parent_col, v_schema, v_table)
+            into v_parent_id using p_id;
+          if v_parent_id is null then return false; end if;
+          return iam.has_access(v_parent_type, v_parent_id, p_required);
+        end if;
+
+        -- standard entity: owner or public-read
+        begin
+          execute format('select visibility, created_by, organization_id from %I.%I where id=$1', v_schema, v_table)
+            into v_vis, v_owner, v_org using p_id;
+        exception when others then return false; end;
+        if v_owner is null and v_vis is null then return false; end if;
+        if v_owner = v_uid then return true; end if;
+        if v_vis = 'public' and p_required = 'viewer' then return true; end if;
+        return false;
+      end
+      $fn$;
+    $exec$;
+  end if;
+end
+$do$;