Metadata-Version: 2.5
Name: matrx-runtime
Version: 0.0.38
Summary: The durable-execution substrate: one global_execution spine, one lifecycle state machine, one cost ledger, that every matrx-* executor (agent loop, workflow superstep, utilities) plugs into.
Author-email: Matrx <admin@aimatrx.com>
License: MIT
Keywords: durable,execution,matrx,orchestration,runtime
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.13
Requires-Dist: matrx-orm>=3.1.81
Requires-Dist: pydantic>=2.12
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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 `available_at`, 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.

Design + phased plan: [`docs/runtime/EXECUTION_SPINE.md`](../../docs/runtime/EXECUTION_SPINE.md).
