mxm-runtime 0.1.1

Runtime identity discovery and runtime context construction for Money Ex Machina.

mxm-runtime

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:

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:

application code

from:

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:

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.

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:

mxm-config

and:

mxm-secrets

respectively.

Core Concepts

RuntimeIdentity

Represents the operational identity of a running process.

Example:

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:

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:

local-process
docker

Substrate allows runtime construction to adapt to deployment environment differences.

RuntimeContext

Represents the fully constructed operational environment.

Current fields:

RuntimeContext(
    identity=...,
    config=...,
    secrets=...,
)

Future versions may additionally materialise:

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:

RuntimeIdentity
    ↓
load_config(...)
    ↓
Configuration Views
    ↓
Service Construction
    ↓
RuntimeContext

For example:

context = build_runtime_context(
    identity=identity,
)

which currently materialises:

configuration
secret services

and returns a configured RuntimeContext.

Runtime Discovery

mxm-runtime provides discovery utilities for determining runtime characteristics.

Examples:

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:

configuration storage
configuration loading
configuration merging
configuration views

mxm-runtime consumes configuration and constructs runtime services from it.

Example:

RuntimeIdentity
    ↓
mxm-config
    ↓
MXMConfig
    ↓
RuntimeContext

Relationship To mxm-secrets

mxm-secrets owns:

secret references
authorization
resolution
retrieval

mxm-runtime constructs configured secret services and makes them available through RuntimeContext.

Applications are expected to consume:

context.secrets

rather than constructing SecretsApi instances directly.

Installation

pip install mxm-runtime

Usage

Construct a RuntimeContext:

from mxm.runtime import build_runtime_context

context = build_runtime_context(
    identity=identity,
)

Access configured services:

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

poetry install

make check

Run the RuntimeContext smoke test:

poetry run python scripts/smoke_runtime_context.py

Status

Current release status:

Runtime Identity Discovery Complete
RuntimeContext Construction Complete
Service Expansion In Progress

Current RuntimeContext materialises:

configuration
secrets

Additional services will be added incrementally.

License

MIT License. See LICENSE.