mxm-runtime

Runtime discovery, configuration-driven runtime resource materialization, 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
    ↓
Resource Materialisation
    ↓
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=...,
    db_configs=...,
    paths=...,
    runtime=...,
)

Current RuntimeContext materialises:

identity configuration secrets database configuration views runtime paths runtime metadata

Applications are expected to consume runtime resources (and SecretsApi) through RuntimeContext.

Runtime Construction Flow

Runtime construction follows the sequence:

Configuration Views
    ↓
SecretsApi Construction
    ↓
Path Materialisation
    ↓
Database View Extraction
    ↓
RuntimeContext

For example:

context = build_runtime_context(
    identity=identity,
)

which currently materialises:

configuration
secret services
database configuration views
runtime paths
runtime metadata

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.

mxm-runtime also extracts and materialises selected configuration views required for runtime operation.

Examples:

mxm_secrets
mxm_databases
mxm_paths

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,
)

db_config = context.db_configs.operational_state

print(db_config.host)
print(db_config.name)

data_root = context.paths.data_root

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
Configuration Integration Complete
Secrets Integration Complete
Runtime Path Materialisation Complete
Database View Materialisation Complete
Store Integration In Progress

Current RuntimeContext materialises:

configuration
secrets
database configuration views
runtime paths
runtime metadata

Additional services will be added incrementally.

License

MIT License. See LICENSE.