matrx-runtime
The durable-execution substrate for the Matrx platform.
Every unit of work — a utility call, a workflow run, an agent session — is one
row on a single global_execution spine that can nest inside any other. The
substrate owns the concerns all three flavors share, so they compose freely and
share one lifecycle, one nesting tree, one cost ledger, and one enforced state
machine:
- run identity + lineage (
parent_execution_id, denormalizedroot_execution_id) - the lifecycle state machine (
transition()— the only legal way to change status) - the cost ledger + tree-wide budget and quantity limits
- cancellation, deadlines, and down-tree propagation
- generalized checkpoints, leases, recovery, and lifecycle events
- pluggable durable stores (
InMemoryExecutionStoreandOrmExecutionStore) - immutable per-execution context snapshots with explicit inheritance modes
ContextMode.INHERIT deep-copies the parent's snapshot, SCOPE overlays
explicit narrower values, and destructive REPLACE requires a complete
replacement context. Omitting that replacement raises
MissingReplacementContext both at the engine spawn boundary and in
ExecutionContext.derive; silent context erasure is not a valid operation.
Executors plug in as strategies and are NOT owned here: the agent loop
(matrx-ai), the superstep DAG (matrx-graph), utility implementations
(matrx-scraper).
Status: active. The decision core, durable ORM store, context propagation, metering, budget/cancel/deadline gates, leases, recovery, checkpoints, and request/execution lifecycle are implemented. aidream adopts them through its host integration; domain payloads and entity lookup remain host-owned so this package stays independent and payload-blind.
Durable frontier consumers use runtime.work_item. A provider poll that is
still in progress calls defer_work_item(...): it returns the claim to
pending, schedules not_before, and does not consume the retry budget.
Actual call failures continue through fail_work_item(...) and its bounded
retry/dead-letter policy. pending_work_execution_ids(type, limit) is the
payload-blind discovery seam for host drainers; providers and domain payloads
remain outside this package.
Expired leases obey the same attempt budget: a final expired attempt becomes
dead_letter with a typed error instead of returning to pending. Consumers
that intentionally encode a resumable terminal wait can use the CAS-fenced
resume_failed_work_item(...); it matches the full expected error and restores
the claim attempt consumed while discovering that wait.
Large mixed backlogs use generic priority (lower claims first, seq breaks
ties). Long workers call renew_work_item_lease(...); coordinators use the
bounded list_work_items(...), exact get_work_item(...), and dependency-state
lookup without importing ORM rows.
Design + phased plan: docs/runtime/EXECUTION_SPINE.md.
1 maintainer
Release files for matrx-runtime 0.0.120
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| matrx_runtime-0.0.120.tar.gz | 105.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| matrx_runtime-0.0.120-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 174.7 kB
Release files / matrx_runtime-0.0.120.tar.gz
| Download URL | matrx_runtime-0.0.120.tar.gz |
|---|---|
| Size | 105.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3412e74f309112c8d63e04ec5811e75d65f5467a2e93e4d751ed617a5147693f
|
|
BLAKE2b-256 checksum How to use checksums |
4a1459754a3151bd18d00d27ab0edbd38895e78ffcb7cd560e00694c414a70ef
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency logRelease files / matrx_runtime-0.0.120-py3-none-any.whl
| Download URL | matrx_runtime-0.0.120-py3-none-any.whl |
|---|---|
| Size | 69.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
66bb845791f4972a9634f8a05d27ff8be7d48e2c9c583cf975da9a8471d59d40
|
|
BLAKE2b-256 checksum How to use checksums |
8a803dd98d2fac596a119664ac22c8f9b6e193646514a069dbf80a746a0f0621
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency log
