mxm-runtime 0.1.0__tar.gz

mxm_runtime-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Money Ex Machina
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the “Software”), to deal
+in the Software without restriction, including without limitation the rights  
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell  
+copies of the Software, and to permit persons to whom the Software is  
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all  
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR  
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,  
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE  
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER  
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,  
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE  
+SOFTWARE.

mxm_runtime-0.1.0/PKG-INFO

@@ -0,0 +1,378 @@
+Metadata-Version: 2.4
+Name: mxm-runtime
+Version: 0.1.0
+Summary: Runtime identity discovery and runtime context construction for Money Ex Machina.
+License: MIT
+License-File: LICENSE
+Keywords: runtime,context,identity,configuration,deployment,infrastructure,orchestration,prefect,mxm
+Author: mxm
+Author-email: contact@moneyexmachina.com
+Requires-Python: >=3.13,<3.15
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: mxm-config (>=0.6.2,<0.7)
+Requires-Dist: mxm-secrets (>=0.3.2,<0.4)
+Requires-Dist: mxm-types (>=0.3.1,<0.4.0)
+Requires-Dist: rich (>=14.2.0,<15.0.0)
+Requires-Dist: typer (>=0.20.0,<0.21.0)
+Project-URL: Homepage, https://github.com/moneyexmachina/mxm-runtime
+Project-URL: Repository, https://github.com/moneyexmachina/mxm-runtime
+Description-Content-Type: text/markdown
+
+# mxm-runtime
+
+![Version](https://img.shields.io/github/v/release/moneyexmachina/mxm-runtime)
+![License](https://img.shields.io/github/license/moneyexmachina/mxm-runtime)
+![Python](https://img.shields.io/badge/python-3.13+-blue)
+[![Checked with pyright](https://microsoft.github.io/pyright/img/pyright_badge.svg)](https://microsoft.github.io/pyright/)
+
+Runtime discovery, configuration-driven service construction, and RuntimeContext assembly for the Money Ex Machina ecosystem.
+
+`mxm-runtime` is responsible for constructing the operational environment in which MXM applications execute.
+
+It discovers runtime characteristics, loads and resolves configuration, constructs configured services, and assembles them into a single RuntimeContext.
+
+## Purpose
+
+MXM applications require more than configuration files.
+
+They require an operational environment:
+
+```text
+Who am I?
+Where am I running?
+Which configuration applies?
+Which services are available?
+Where should data and artefacts live?
+```
+
+`mxm-runtime` answers these questions.
+
+It exists to separate:
+
+```text
+application code
+```
+
+from:
+
+```text
+runtime discovery
+configuration loading
+service construction
+deployment concerns
+context assembly
+```
+
+Applications should not:
+
+- discover machine characteristics,
+- determine deployment substrate,
+- load configuration directly,
+- construct service APIs,
+- or reason about deployment topology.
+
+Instead, applications receive a configured RuntimeContext:
+
+```python
+context = build_runtime_context(
+    identity=runtime_identity,
+)
+```
+
+and consume the services and resources provided by that context.
+
+## Architecture
+
+`mxm-runtime` acts as the runtime constructor layer of the MXM architecture.
+
+```text
+RuntimeIdentity
+    ↓
+mxm-config
+    ↓
+Configuration Resolution
+    ↓
+Service Construction
+    ↓
+RuntimeContext
+    ↓
+Application
+```
+
+The package owns runtime construction.
+
+It does not own configuration semantics or secret resolution semantics.
+
+Those responsibilities belong to:
+
+```text
+mxm-config
+```
+
+and:
+
+```text
+mxm-secrets
+```
+
+respectively.
+
+## Core Concepts
+
+### RuntimeIdentity
+
+Represents the operational identity of a running process.
+
+Example:
+
+```text
+app          mxm-moneymachine
+environment  dev
+machine      bridge
+substrate    local-process
+role         marketdata
+```
+
+Runtime identity determines which configuration layers are selected and which services are constructed.
+
+### Machine
+
+A machine identifies a machine-specific configuration profile.
+
+Examples:
+
+```text
+bridge
+monolith
+wildling
+scribe
+```
+
+Machine values are derived from operating-system characteristics and are used to select machine-specific configuration.
+
+They are configuration selectors rather than unique hardware identifiers.
+
+### Substrate
+
+Represents the execution substrate.
+
+Examples:
+
+```text
+local-process
+docker
+```
+
+Substrate allows runtime construction to adapt to deployment environment differences.
+
+### RuntimeContext
+
+Represents the fully constructed operational environment.
+
+Current fields:
+
+```python
+RuntimeContext(
+    identity=...,
+    config=...,
+    secrets=...,
+)
+```
+
+Future versions may additionally materialise:
+
+```text
+paths
+databases
+reference data services
+storage services
+execution services
+reporting services
+```
+
+Applications are expected to consume runtime services through RuntimeContext.
+
+## Runtime Construction Flow
+
+Runtime construction follows the sequence:
+
+```text
+RuntimeIdentity
+    ↓
+load_config(...)
+    ↓
+Configuration Views
+    ↓
+Service Construction
+    ↓
+RuntimeContext
+```
+
+For example:
+
+```python
+context = build_runtime_context(
+    identity=identity,
+)
+```
+
+which currently materialises:
+
+```text
+configuration
+secret services
+```
+
+and returns a configured RuntimeContext.
+
+## Runtime Discovery
+
+`mxm-runtime` provides discovery utilities for determining runtime characteristics.
+
+Examples:
+
+```python
+machine = discover_machine()
+substrate = discover_substrate()
+```
+
+These functions derive MXM runtime selectors from operating-system facts.
+
+The resulting values are suitable for configuration resolution and runtime construction.
+
+## Relationship To mxm-config
+
+`mxm-config` owns:
+
+```text
+configuration storage
+configuration loading
+configuration merging
+configuration views
+```
+
+`mxm-runtime` consumes configuration and constructs runtime services from it.
+
+Example:
+
+```text
+RuntimeIdentity
+    ↓
+mxm-config
+    ↓
+MXMConfig
+    ↓
+RuntimeContext
+```
+
+## Relationship To mxm-secrets
+
+`mxm-secrets` owns:
+
+```text
+secret references
+authorization
+resolution
+retrieval
+```
+
+`mxm-runtime` constructs configured secret services and makes them available through RuntimeContext.
+
+Applications are expected to consume:
+
+```python
+context.secrets
+```
+
+rather than constructing SecretsApi instances directly.
+
+## Installation
+
+```bash
+pip install mxm-runtime
+```
+
+## Usage
+
+Construct a RuntimeContext:
+
+```python
+from mxm.runtime import build_runtime_context
+
+context = build_runtime_context(
+    identity=identity,
+)
+```
+
+Access configured services:
+
+```python
+api_key = context.secrets.get_secret(
+    "databento_api_key",
+    identity=context.identity,
+)
+```
+
+## Design Principles
+
+- **Explicit runtime identity**
+  Runtime identity is always represented explicitly.
+
+- **Configuration-driven construction**
+  Runtime behaviour is determined through configuration rather than hardcoded wiring.
+
+- **Separation of concerns**
+  Discovery, configuration, resolution, construction, and application logic remain separate.
+
+- **Strict typing**
+  Fully Pyright-clean and PEP 561 compliant.
+
+- **Minimal implicit behaviour**
+  Runtime construction is deterministic and inspectable.
+
+- **Composable services**
+  Runtime services are assembled from independent packages.
+
+## Development
+
+```bash
+poetry install
+
+make check
+```
+
+Run the RuntimeContext smoke test:
+
+```bash
+poetry run python scripts/smoke_runtime_context.py
+```
+
+## Status
+
+Current release status:
+
+```text
+Runtime Identity Discovery Complete
+RuntimeContext Construction Complete
+Service Expansion In Progress
+```
+
+Current RuntimeContext materialises:
+
+```text
+configuration
+secrets
+```
+
+Additional services will be added incrementally.
+
+## License
+
+MIT License. See [LICENSE](LICENSE).
+

mxm_runtime-0.1.0/README.md

@@ -0,0 +1,351 @@
+# mxm-runtime
+
+![Version](https://img.shields.io/github/v/release/moneyexmachina/mxm-runtime)
+![License](https://img.shields.io/github/license/moneyexmachina/mxm-runtime)
+![Python](https://img.shields.io/badge/python-3.13+-blue)
+[![Checked with pyright](https://microsoft.github.io/pyright/img/pyright_badge.svg)](https://microsoft.github.io/pyright/)
+
+Runtime discovery, configuration-driven service construction, and RuntimeContext assembly for the Money Ex Machina ecosystem.
+
+`mxm-runtime` is responsible for constructing the operational environment in which MXM applications execute.
+
+It discovers runtime characteristics, loads and resolves configuration, constructs configured services, and assembles them into a single RuntimeContext.
+
+## Purpose
+
+MXM applications require more than configuration files.
+
+They require an operational environment:
+
+```text
+Who am I?
+Where am I running?
+Which configuration applies?
+Which services are available?
+Where should data and artefacts live?
+```
+
+`mxm-runtime` answers these questions.
+
+It exists to separate:
+
+```text
+application code
+```
+
+from:
+
+```text
+runtime discovery
+configuration loading
+service construction
+deployment concerns
+context assembly
+```
+
+Applications should not:
+
+- discover machine characteristics,
+- determine deployment substrate,
+- load configuration directly,
+- construct service APIs,
+- or reason about deployment topology.
+
+Instead, applications receive a configured RuntimeContext:
+
+```python
+context = build_runtime_context(
+    identity=runtime_identity,
+)
+```
+
+and consume the services and resources provided by that context.
+
+## Architecture
+
+`mxm-runtime` acts as the runtime constructor layer of the MXM architecture.
+
+```text
+RuntimeIdentity
+    ↓
+mxm-config
+    ↓
+Configuration Resolution
+    ↓
+Service Construction
+    ↓
+RuntimeContext
+    ↓
+Application
+```
+
+The package owns runtime construction.
+
+It does not own configuration semantics or secret resolution semantics.
+
+Those responsibilities belong to:
+
+```text
+mxm-config
+```
+
+and:
+
+```text
+mxm-secrets
+```
+
+respectively.
+
+## Core Concepts
+
+### RuntimeIdentity
+
+Represents the operational identity of a running process.
+
+Example:
+
+```text
+app          mxm-moneymachine
+environment  dev
+machine      bridge
+substrate    local-process
+role         marketdata
+```
+
+Runtime identity determines which configuration layers are selected and which services are constructed.
+
+### Machine
+
+A machine identifies a machine-specific configuration profile.
+
+Examples:
+
+```text
+bridge
+monolith
+wildling
+scribe
+```
+
+Machine values are derived from operating-system characteristics and are used to select machine-specific configuration.
+
+They are configuration selectors rather than unique hardware identifiers.
+
+### Substrate
+
+Represents the execution substrate.
+
+Examples:
+
+```text
+local-process
+docker
+```
+
+Substrate allows runtime construction to adapt to deployment environment differences.
+
+### RuntimeContext
+
+Represents the fully constructed operational environment.
+
+Current fields:
+
+```python
+RuntimeContext(
+    identity=...,
+    config=...,
+    secrets=...,
+)
+```
+
+Future versions may additionally materialise:
+
+```text
+paths
+databases
+reference data services
+storage services
+execution services
+reporting services
+```
+
+Applications are expected to consume runtime services through RuntimeContext.
+
+## Runtime Construction Flow
+
+Runtime construction follows the sequence:
+
+```text
+RuntimeIdentity
+    ↓
+load_config(...)
+    ↓
+Configuration Views
+    ↓
+Service Construction
+    ↓
+RuntimeContext
+```
+
+For example:
+
+```python
+context = build_runtime_context(
+    identity=identity,
+)
+```
+
+which currently materialises:
+
+```text
+configuration
+secret services
+```
+
+and returns a configured RuntimeContext.
+
+## Runtime Discovery
+
+`mxm-runtime` provides discovery utilities for determining runtime characteristics.
+
+Examples:
+
+```python
+machine = discover_machine()
+substrate = discover_substrate()
+```
+
+These functions derive MXM runtime selectors from operating-system facts.
+
+The resulting values are suitable for configuration resolution and runtime construction.
+
+## Relationship To mxm-config
+
+`mxm-config` owns:
+
+```text
+configuration storage
+configuration loading
+configuration merging
+configuration views
+```
+
+`mxm-runtime` consumes configuration and constructs runtime services from it.
+
+Example:
+
+```text
+RuntimeIdentity
+    ↓
+mxm-config
+    ↓
+MXMConfig
+    ↓
+RuntimeContext
+```
+
+## Relationship To mxm-secrets
+
+`mxm-secrets` owns:
+
+```text
+secret references
+authorization
+resolution
+retrieval
+```
+
+`mxm-runtime` constructs configured secret services and makes them available through RuntimeContext.
+
+Applications are expected to consume:
+
+```python
+context.secrets
+```
+
+rather than constructing SecretsApi instances directly.
+
+## Installation
+
+```bash
+pip install mxm-runtime
+```
+
+## Usage
+
+Construct a RuntimeContext:
+
+```python
+from mxm.runtime import build_runtime_context
+
+context = build_runtime_context(
+    identity=identity,
+)
+```
+
+Access configured services:
+
+```python
+api_key = context.secrets.get_secret(
+    "databento_api_key",
+    identity=context.identity,
+)
+```
+
+## Design Principles
+
+- **Explicit runtime identity**
+  Runtime identity is always represented explicitly.
+
+- **Configuration-driven construction**
+  Runtime behaviour is determined through configuration rather than hardcoded wiring.
+
+- **Separation of concerns**
+  Discovery, configuration, resolution, construction, and application logic remain separate.
+
+- **Strict typing**
+  Fully Pyright-clean and PEP 561 compliant.
+
+- **Minimal implicit behaviour**
+  Runtime construction is deterministic and inspectable.
+
+- **Composable services**
+  Runtime services are assembled from independent packages.
+
+## Development
+
+```bash
+poetry install
+
+make check
+```
+
+Run the RuntimeContext smoke test:
+
+```bash
+poetry run python scripts/smoke_runtime_context.py
+```
+
+## Status
+
+Current release status:
+
+```text
+Runtime Identity Discovery Complete
+RuntimeContext Construction Complete
+Service Expansion In Progress
+```
+
+Current RuntimeContext materialises:
+
+```text
+configuration
+secrets
+```
+
+Additional services will be added incrementally.
+
+## License
+
+MIT License. See [LICENSE](LICENSE).

mxm_runtime-0.1.0/pyproject.toml

@@ -0,0 +1,76 @@
+[tool.poetry]
+name = "mxm-runtime"
+version = "0.1.0"
+description = "Runtime identity discovery and runtime context construction for Money Ex Machina."
+keywords = [
+    "runtime",
+    "context",
+    "identity",
+    "configuration",
+    "deployment",
+    "infrastructure",
+    "orchestration",
+    "prefect",
+    "mxm",
+]
+authors = ["mxm <contact@moneyexmachina.com>"]
+license = "MIT"
+readme = "README.md"
+packages = [{ include = "mxm", from = "src" }]
+homepage = "https://github.com/moneyexmachina/mxm-runtime"
+repository = "https://github.com/moneyexmachina/mxm-runtime"
+include = ["src/mxm/runtime/py.typed"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+[tool.poetry.dependencies]
+python = ">=3.13,<3.15"
+mxm-types = "^0.3.1"
+mxm-config = ">=0.6.2, <0.7"
+mxm-secrets = ">=0.3.2, <0.4"
+typer = "^0.20.0"
+rich = "^14.2.0"
+
+[tool.poetry.scripts]
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.4.2"
+ruff = "^0.14.3"
+black = "^25.9.0"
+isort = "^7.0.0"
+pyright = "^1.1.407"
+
+[build-system]
+requires = ["poetry-core>=2.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+# ---- Tooling (package-local, MXM defaults) ----
+[tool.black]
+line-length = 88
+target-version = ["py313"]
+
+[tool.isort]
+profile = "black"
+line_length = 88
+known_first_party = ["mxm"]
+combine_as_imports = true
+
+[tool.ruff]
+line-length = 88
+target-version = "py313"
+
+[tool.ruff.lint]
+select = ["E","F","I","B","UP","C90","RUF"]
+ignore = ["E203","E501"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["mxm"]
+
+[tool.pytest.ini_options]
+addopts = "-q"
+pythonpath = ["src"]
+

mxm_runtime-0.1.0/src/mxm/runtime/__init__.py

@@ -0,0 +1,12 @@
+"""Runtime identity discovery and runtime context construction for MXM."""
+
+from mxm.runtime.identity import build_runtime_identity
+from mxm.runtime.validation import RuntimeIdentityError, validate_runtime_identity_shape
+from mxm.types import RuntimeIdentity
+
+__all__ = [
+    "RuntimeIdentity",
+    "RuntimeIdentityError",
+    "build_runtime_identity",
+    "validate_runtime_identity_shape",
+]

mxm_runtime-0.1.0/src/mxm/runtime/attestation.py

@@ -0,0 +1,57 @@
+"""Runtime identity attestation.
+
+Attestation checks whether the empirical claims in a RuntimeIdentity match the
+current running process.
+
+This is distinct from shape validation. Shape validation checks whether an
+identity object is well formed. Attestation checks whether selected claims are
+true here.
+"""
+
+from __future__ import annotations
+
+from mxm.runtime.discovery import discover_machine, discover_substrate
+from mxm.types import RuntimeIdentity
+
+
+class RuntimeIdentityAttestationError(RuntimeError):
+    """Raised when a runtime identity is not true for this process."""
+
+
+def attest_runtime_identity(identity: RuntimeIdentity) -> None:
+    """Attest that empirical RuntimeIdentity claims match local discovery.
+
+    Only locally discoverable empirical fields are attested:
+
+    - ``machine``
+    - ``substrate``
+
+    The following fields are not attested here because they are invocation or
+    deployment claims rather than directly discoverable local facts:
+
+    - ``app``
+    - ``environment``
+    - ``role``
+    """
+    discovered_machine = discover_machine()
+    discovered_substrate = discover_substrate()
+
+    errors: list[str] = []
+
+    if identity.machine != discovered_machine:
+        errors.append(
+            "machine claim does not match local discovery: "
+            f"identity.machine={identity.machine!r}, "
+            f"discovered_machine={discovered_machine!r}"
+        )
+
+    if identity.substrate != discovered_substrate:
+        errors.append(
+            "substrate claim does not match local discovery: "
+            f"identity.substrate={identity.substrate!r}, "
+            f"discovered_substrate={discovered_substrate!r}"
+        )
+
+    if errors:
+        message = "; ".join(errors)
+        raise RuntimeIdentityAttestationError(message)

mxm_runtime-0.1.0/src/mxm/runtime/build.py

@@ -0,0 +1,79 @@
+"""RuntimeContext construction for mxm-runtime.
+
+This module owns materialisation of a RuntimeContext from an explicit
+RuntimeIdentity and resolved MXM configuration.
+
+It deliberately keeps package responsibilities separated:
+
+- mxm-config loads, slices, and converts configuration.
+- mxm-secrets constructs the configured SecretsApi from plain config data.
+- mxm-runtime assembles the materialised RuntimeContext.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from mxm.config import load_config, make_view, to_config_data
+from mxm.runtime.context import RuntimeContext
+from mxm.secrets import SecretsApi
+from mxm.types import RuntimeIdentity
+
+
+def build_runtime_context(
+    *,
+    identity: RuntimeIdentity,
+    store_root: Path | None = None,
+) -> RuntimeContext:
+    """Build a RuntimeContext for an explicit runtime identity.
+
+    Parameters
+    ----------
+    identity
+        Runtime identity used to resolve configuration and materialise runtime
+        services.
+    store_root
+        Optional configuration store root. If omitted, mxm-config uses its
+        default configuration store location.
+
+    Returns
+    -------
+    RuntimeContext
+        Materialised runtime context containing the supplied identity, resolved
+        configuration, and configured SecretsApi.
+
+    Raises
+    ------
+    FileNotFoundError
+        If required configuration files are missing.
+    KeyError
+        If selected configuration layers or required config sections are absent.
+    TypeError
+        If configuration sections have invalid structure.
+    ValueError
+        If secrets configuration fails mxm-secrets validation.
+    """
+    if store_root is None:
+        config = load_config(identity=identity)
+    else:
+        config = load_config(
+            identity=identity,
+            store_root=store_root,
+        )
+
+    secrets_config = make_view(
+        config,
+        "mxm_secrets",
+        readonly=True,
+        resolve=True,
+    )
+
+    secrets = SecretsApi.from_config_data(
+        to_config_data(secrets_config),
+    )
+
+    return RuntimeContext(
+        identity=identity,
+        config=config,
+        secrets=secrets,
+    )

mxm_runtime-0.1.0/src/mxm/runtime/context.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from mxm.config import MXMConfig
+from mxm.secrets import SecretsApi
+from mxm.types import RuntimeIdentity
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimePaths:
+    """Resolved filesystem locations available to this runtime."""
+
+    data_root: Path | None = None
+    artifact_root: Path | None = None
+    state_root: Path | None = None
+    log_root: Path | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeMetadata:
+    """Materialised metadata about the current execution substrate."""
+
+    substrate: str
+    is_container: bool
+
+
+@dataclass(frozen=True, slots=True)
+class RuntimeContext:
+    """Materialised operational context for an MXM runtime."""
+
+    identity: RuntimeIdentity
+    config: MXMConfig
+    secrets: SecretsApi | None = None
+    paths: RuntimePaths | None = None
+    runtime: RuntimeMetadata | None = None

mxm_runtime-0.1.0/src/mxm/runtime/discovery.py

@@ -0,0 +1,68 @@
+"""Runtime discovery helpers."""
+
+from __future__ import annotations
+
+import socket
+from pathlib import Path
+
+DEFAULT_DOCKERENV_PATH = Path("/.dockerenv")
+
+
+def discover_machine() -> str:
+    """Discover the current MXM machine selector.
+
+    The machine selector identifies the machine-specific configuration profile
+    that should be applied by MXM.
+
+    It is derived from operating-system host information but is not required to
+    equal the raw hostname reported by the operating system. The purpose of the
+    selector is configuration selection rather than unique host identification.
+
+    For v0.1, the selector is derived from the local hostname by taking the
+    unqualified hostname component.
+
+    Examples
+    --------
+    Raw hostname:
+
+        bridge.local
+
+    Produces:
+
+        bridge
+
+    Raw hostname:
+
+        monolith
+
+    Produces:
+
+        monolith
+
+    Returns
+    -------
+    str
+        MXM machine selector used for machine-specific configuration loading.
+    """
+    hostname = socket.gethostname()
+    return hostname.split(".", maxsplit=1)[0]
+
+
+def discover_substrate(
+    *,
+    dockerenv_path: Path = DEFAULT_DOCKERENV_PATH,
+) -> str:
+    """Discover the current execution substrate.
+
+    Discovery order:
+
+    1. Docker marker file.
+    2. ``local-process`` fallback.
+
+    The Docker marker path is injectable because ``/.dockerenv`` is a
+    conventional probe rather than an MXM-owned runtime concept.
+    """
+    if dockerenv_path.exists():
+        return "docker-container"
+
+    return "local-process"

mxm_runtime-0.1.0/src/mxm/runtime/identity.py

@@ -0,0 +1,59 @@
+"""Runtime identity construction.
+
+This module provides the small public construction helper for MXM runtime
+identity. It deliberately keeps discovery and validation at the boundary:
+callers may pass explicit values, while missing machine/substrate values are
+delegated to discovery helpers.
+"""
+
+from __future__ import annotations
+
+from mxm.runtime.discovery import discover_machine, discover_substrate
+from mxm.runtime.validation import validate_runtime_identity_shape
+from mxm.types import (
+    RuntimeIdentity,
+)
+
+
+def build_runtime_identity(
+    *,
+    app: str,
+    environment: str,
+    role: str,
+    machine: str | None = None,
+    substrate: str | None = None,
+) -> RuntimeIdentity:
+    """Build and validate a RuntimeIdentity.
+
+    Parameters
+    ----------
+    app:
+        MXM application or package identifier.
+    environment:
+        Operational environment, for example ``dev``, ``test``, or ``prod``.
+    role:
+        Runtime responsibility, for example ``research`` or ``marketdata``.
+    machine:
+        Physical or logical host identifier. If omitted, this is discovered.
+    substrate:
+        Execution substrate. If omitted, this is discovered.
+
+    Returns
+    -------
+    RuntimeIdentity
+        A validated runtime identity using the shared mxm-types vocabulary.
+    """
+    resolved_machine = machine if machine is not None else discover_machine()
+    resolved_substrate = substrate if substrate is not None else discover_substrate()
+
+    identity = RuntimeIdentity(
+        app=app,
+        environment=environment,
+        machine=resolved_machine,
+        substrate=resolved_substrate,
+        role=role,
+    )
+
+    validate_runtime_identity_shape(identity)
+
+    return identity

mxm_runtime-0.1.0/src/mxm/runtime/validation.py

@@ -0,0 +1,32 @@
+"""Runtime identity validation."""
+
+from __future__ import annotations
+
+from mxm.types import RuntimeIdentity
+
+
+class RuntimeIdentityError(ValueError):
+    """Raised when a runtime identity is invalid."""
+
+
+def validate_runtime_identity_shape(identity: RuntimeIdentity) -> None:
+    """Validate a RuntimeIdentity.
+
+    Validation is intentionally minimal for v0.1.0. Policy-specific allowed
+    values should be introduced only once the deployment model has stabilized.
+    """
+    fields = {
+        "app": identity.app,
+        "environment": identity.environment,
+        "machine": identity.machine,
+        "substrate": identity.substrate,
+        "role": identity.role,
+    }
+
+    missing = [name for name, value in fields.items() if not str(value).strip()]
+
+    if missing:
+        joined = ", ".join(missing)
+        raise RuntimeIdentityError(
+            f"RuntimeIdentity contains empty required field(s): {joined}"
+        )