feat(runtime): add native semantic, replay, and adaptive systems

[PhilipJohnBasile]

Maintainer action required

The reviewer-facing README pass is complete on exact head:

9e067af5f65e26f4ff3d056f55c5dd8b80428e8a

Because this external-fork PR modifies workflow files, GitHub created new exact-head runs with no jobs and marked them action_required. Please approve:

• build
• ci
• hygiene
• native-adaptive matrix

The preceding code-and-matrix head, 53ba0cc1bc96b135da32fba25615dfff96b81bf6, passed all four authoritative upstream workflows. The only change after that green head is README.md. Maintainer edits remain enabled, and @youssofal is the requested reviewer.

Reviewer-facing README update

The top-level README before-and-after section now documents the complete contribution in product terms rather than requiring the reviewer to reconstruct it from source files. It includes:

• a seven-row before / after comparison covering SessionBank reuse, MoE working sets, memory governance, production diagnosis, candidate evaluation, observability/policy, and operations
• every new subsystem: semantic anchors, expert locality, safe-point memory governance, expert warm-set control, unified-memory coordination, privacy-default capture, deterministic replay, trace parity, OTLP/HTTP export, lifecycle policy hooks, and capture-to-replay orchestration
• the actual environment-variable names and a representative opt-in configuration
• /v1/mtplx/systems, the Systems dashboard, the read-only Native command surface, and the relevant CLI commands
• the privacy, safe-point, router, KV-resize, fail-open, and non-automatic-promotion boundaries
• a collapsible maintainer review order and links to the operator docs and validation receipt

What this adds

This is a vendor-neutral MTPLX implementation. It does not import, embed, launch, or require FreeToken, Future AGI, or another external runtime.

Semantic runtime intelligence

• exact SessionBank anchors from verified complete-message chat-template prefixes
• safe-point SessionBank memory governance under the model lock
• opt-in MoE expert-locality telemetry without router mutation

Deterministic replay and evaluation

• privacy-safe request capture with prompt/response content disabled by default
• deterministic counterfactual replay with candidate and evaluator isolation
• bounded timeouts, trace-parity diagnosis, and explicit regression gates
• advisory promotion decisions that MTPLX never applies automatically

Native adaptive systems

• locality-guided, byte-budgeted expert warm-set planning
• atomic unified-memory coordination across SessionBank, expert state, and protected KV headroom
• dependency-free, bounded, privacy-first OTLP/HTTP export
• trusted request, stream, response, and error policy hooks with a fixed-size worker pool
• deterministic capture-to-replay orchestration with stale-plan protection and atomic receipts

Operations

• GET /v1/mtplx/systems
• Systems dashboard states for available, enabled, observed, active, blocked, and inactive
• read-only Native dashboard commands
• dashboard compilation before wheel/release packaging
• permanent native-systems and expanded native-adaptive CI coverage

Safety boundaries

• all adaptive serving paths are default-off or inert
• no router mutation from locality telemetry or residency planning
• no cache or memory mutation outside proven safe points
• generic MLX reports materialize_only; it does not claim hard page residency on unified memory
• live KV resizing requires an explicit backend capability
• no prompt/response persistence or telemetry content export without separate opt-in
• nested credentials are recursively redacted
• observability failures are fail-open; policy failures are request-fatal only for an explicitly trusted fail-closed hook
• MTPLX never promotes a replay candidate automatically

Configuration matrix

The permanent nine-cell matrix covers:

Cell	Result on 53ba0cc
Python 3.11 pure systems	143 passed
Python 3.12 pure systems	143 passed
Python 3.13 pure systems	143 passed
Python 3.14 pure systems	143 passed
Default-off process profile	passed; model lock untouched
Expert-only process profile	passed
Unified-memory-only process profile	passed
Combined-memory process profile	passed
macOS 14 ARM64 runtime integration	185 passed

The cross-system tests cover default-off fast paths, individual and combined activation, every safe-point blocker, lock release and zero-mutation behavior, invalid environment-value clamping, privacy-default OTLP behavior, simultaneous memory/telemetry/policy/replay operation, non-automatic promotion, and concurrent first-use idempotency.

Existing publication receipt

docs/validation/native-adaptive-phase2.json records the preceding publication gate:

• 166 focused tests: 0 failures, 0 errors, 0 skips
• 819 compatibility tests: 0 failures, 0 errors, 0 skips
• Python compilation: PASS
• Git whitespace/diff validation: PASS
• Ruff/Pyflakes/import correctness: PASS
• production TypeScript/Vite dashboard build: PASS
• wheel and sdist build: PASS
• Twine validation: PASS
• fresh-environment install smoke: PASS
• external-runtime dependency and executable-source scans: PASS

Suggested review order

1. README.md and the linked operator documentation
2. mtplx/semantic_anchors.py, memory_governor.py, expert_locality.py
3. mtplx/deterministic_replay.py, request_capture.py, replay_orchestrator.py
4. mtplx/expert_residency.py, unified_memory.py, native_adaptive.py
5. mtplx/otlp_export.py, policy_hooks.py
6. mtplx/runtime_systems.py, mtplx/server/openai.py
7. dashboard source, matrix tests, and validation receipts

The contribution is four clean commits directly on MTPLX 2.9.1. It contains no source exporters, patch payloads, temporary publication workflows, or fork-only benchmark archives.

Benchmark evidence

No throughput or quality improvement is claimed. These systems are default-off, observational, capability-gated, or offline. Model-specific M5 performance promotion remains separate work.

[PhilipJohnBasile]

Phase-one CI receipt — superseded by phase-two head

The original semantic/replay head 88954d81dad0c40e02df4b865b838faf1b14f750 passed its exact-head checks:

• build — PASS
• hygiene — PASS
• ci / no-mlx-smoke — PASS
• ci / native-systems — PASS

The PR has since advanced to d8e90dbc80f3cf60ac3dd3320ae8fcc684a2e2eb, adding the native adaptive systems and a larger receipt-backed validation gate. See the later phase-two completion comment for the current review state.

[PhilipJohnBasile]

Final exact-head matrix receipt

@youssofal — PR #336 is now fully green on exact head 53ba0cc1bc96b135da32fba25615dfff96b81bf6.

Upstream checks:

• build — PASS
• ci — PASS
• hygiene — PASS
• native-adaptive — PASS

The permanent native-systems matrix passed all nine cells:

• Python 3.11, 3.12, 3.13, and 3.14: 143 pure-system tests each
• isolated default-off, expert-only, unified-memory-only, and combined-memory profiles
• macOS 14 ARM64 integration: 185 tests

The matrix specifically covers all safe-point blockers, zero-mutation blocked paths, default-off lock avoidance, simultaneous memory/OTLP/policy/replay operation, telemetry privacy defaults, non-automatic promotion, environment clamping, and concurrent first-use idempotency.

The PR is non-draft, mergeable, maintainer-editable, and contains no temporary publication branches or files. The fork-side temporary branches were archived by exact commit tag and deleted. This is ready for maintainer review and merge.

[PhilipJohnBasile]

@youssofal — final handoff: #336 is now the only open PR associated with this integration. The fork-side staging PRs and the unrelated external replay PR have been closed, the PR description now has a file-by-file review map, maintainer edits are enabled, and the exact head remains d8e90dbc80f3cf60ac3dd3320ae8fcc684a2e2eb. The only remaining action is approving the four action_required workflow runs linked at the top of the description; GitHub created no jobs for them because this fork PR changes workflow files.

[PhilipJohnBasile]

@youssofal The reviewer-facing README pass is now complete on 9e067af5f65e26f4ff3d056f55c5dd8b80428e8a.

The README now includes a full before / after table, all new native runtime and adaptive features, exact opt-in environment variables, the /v1/mtplx/systems and dashboard/CLI surfaces, privacy and safety boundaries, and a collapsible maintainer review map.

The preceding code-and-matrix head 53ba0cc1bc96b135da32fba25615dfff96b81bf6 was fully green. The only delta is README.md. GitHub requires approval of the new exact-head workflow runs because the PR contains workflow changes:

• build: https://github.com/youssofal/MTPLX/actions/runs/32744840351
• ci: https://github.com/youssofal/MTPLX/actions/runs/32744840252
• hygiene: https://github.com/youssofal/MTPLX/actions/runs/32744840224
• native-adaptive: https://github.com/youssofal/MTPLX/actions/runs/32744840146

Maintainer edits remain enabled.

[youssofal]

This bundles several unrelated systems in one PR and I cannot review it as one unit. Split it into one PR per system with a measurement each and I will look.

[PhilipJohnBasile]

@youssofal I split #336 into 13 focused PRs. Each PR is based on current main, contains a reproducible measurement, is open and mergeable, and has wheel, repository-hygiene, and no-mlx-smoke green. I requested your review on each one.

PR	System	Measured result
#350	Exact semantic session anchors	Planner p50 0.751 ms and p95 0.931 ms for 32 messages and 512 tokens
#351	Deterministic counterfactual replay	4,755.6 cases/s over 128 cases, with one stable digest across 10 runs
#352	Expert warm-set residency controller	Planner p50 5.535 ms for 10,240 experts; bounded apply 0.019 ms
#353	Unified-memory budget coordinator	Plan p50 4.167 us; 1,000 injected rollbacks and zero rollback failures
#354	Bounded OTLP/HTTP exporter	Healthy emit p50 9.833 us; 10,000 spans exported with zero drops
#355	Expert-locality telemetry	1.130 us added per call at 1-in-16 sampling; output parity true
#356	Privacy-safe request capture	595.733 us per persisted record; all five privacy assertions passed
#357	SessionBank memory governor	Safe apply mean 1,032 ns over 50,000 applies; zero unsafe applications
#361	Bounded lifecycle policy hooks	One-hook p50 19.208 us; observed concurrency stayed within the configured two-worker bound
#362	Generic runtime systems registry and endpoint	HTTP GET p50 339.541 us and p95 552.459 us; 2,669 req/s
#363	Capture plan replay orchestration	Plan selection p50 50.151 ms over 1,000 captures; stale mutation rejected
#364	Native operations dashboard	2,696 bytes gzip bundle delta; median build delta 69.367 ms
#365	Generic Systems dashboard	2.52 second production build; 1,714 bytes gzip bundle delta

I did not carry the old native_adaptive.py umbrella, cross-system workflow and matrix, or aggregate README and changelog claims into another PR. Those files couple the systems back together and recreate the review problem. #362 is the provider-neutral status contract, and #365 is its separate read-only view with the dependency called out explicitly.

I left #336 open as the replacement index rather than closing it.

[PhilipJohnBasile]

Only the superseded 51-file branch is conflicting. All 13 measured replacement PRs in the map above are clean and mergeable. I am closing #336 rather than merging current main back into the rejected bundle and recreating the review problem.