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, denormalized root_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 (InMemoryExecutionStore and OrmExecutionStore)
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.

Release files for matrx-runtime 0.0.116

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for matrx-runtime 0.0.116
File	Size	Uploaded
matrx_runtime-0.0.116.tar.gz	98.2 kB	Sep 19, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for matrx-runtime 0.0.116
File	Interpreter	ABI	Platform	Reset
matrx_runtime-0.0.116-py3-none-any.whl 66.5 kB Sep 19, 2026	Python 3	none	any	Details

Total release size: 164.7 kB

Release files / matrx_runtime-0.0.116.tar.gz

Download URL	matrx_runtime-0.0.116.tar.gz
Size	98.2 kB
Tags	Source
SHA-256 checksum How to use checksums	`6964c2f60d3b5830b09826588eeb76bce9b1fb3be738c9856c45f7d0bbfd3af2`
BLAKE2b-256 checksum How to use checksums	`1c3d47c6310d059f756846b13b65d91b2c75dc62925570e75eeedd1b548f6fbc`
Upload date	Sep 19, 2026
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.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/AI-Matrix-Engine/aidream
Publishing commit: github.com/AI-Matrix-Engine/aidream/tree/ca9f2a05cd1b5b877d10157d758eb5a9a8bfe9e1

Workflow

Publishing configuration: github.com/AI-Matrix-Engine/aidream/blob/ca9f2a05cd1b5b877d10157d758eb5a9a8bfe9e1/.github/workflows/publish-package.yml
Publishing logs: github.com/AI-Matrix-Engine/aidream/actions/runs/35466969351/attempts/1

Artifact

Subject: matrx_runtime-0.0.116.tar.gz
SHA-256 checksum: 6964c2f60d3b5830b09826588eeb76bce9b1fb3be738c9856c45f7d0bbfd3af2 Verifying attestations

Release files / matrx_runtime-0.0.116-py3-none-any.whl

Download URL	matrx_runtime-0.0.116-py3-none-any.whl
Size	66.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`31891ff8aecd6841dd0ed3b05f0d8f3b2fbaa735ab5d4fac53e55e6af648f4df`
BLAKE2b-256 checksum How to use checksums	`bac73f76e9c611086e883a6b86e5736c611a18dbf613fe2a7e61f65a93788a4a`
Upload date	Sep 19, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/AI-Matrix-Engine/aidream
Publishing commit: github.com/AI-Matrix-Engine/aidream/tree/ca9f2a05cd1b5b877d10157d758eb5a9a8bfe9e1

Workflow

Publishing configuration: github.com/AI-Matrix-Engine/aidream/blob/ca9f2a05cd1b5b877d10157d758eb5a9a8bfe9e1/.github/workflows/publish-package.yml
Publishing logs: github.com/AI-Matrix-Engine/aidream/actions/runs/35466969351/attempts/1

Artifact

Subject: matrx_runtime-0.0.116-py3-none-any.whl
SHA-256 checksum: 31891ff8aecd6841dd0ed3b05f0d8f3b2fbaa735ab5d4fac53e55e6af648f4df Verifying attestations