feat: out-of-tree handler plugin system (maru.handler_plugins)

[hyunyul-XCENA]

Summary

Adds an out-of-tree (OOT) handler plugin system so vendor-/hardware-specific behaviour can live in separate packages instead of Maru core. Maru stays vendor-neutral: a plugin package registers a maru.handler_plugins entry point and MaruHandler discovers it at construction and calls it at defined seams — core never imports it. Loading is soft-fail (vLLM-style), so a missing or broken plugin never breaks KV-cache operation.

Key Changes

• maru_handler/plugin.py (new): MaruHandlerPlugin protocol (4 optional hooks) + load_handler_plugins() soft-fail loader — filters by MARU_PLUGINS, dedups duplicate names (first wins), and warns on a None factory return / typo'd allowlist name.
• maru_handler/handler.py: dispatch at four seams (on_init / on_batch_retrieve / on_close / contribute_stats) via _dispatch_plugins; the empty-plugin case is guarded so the retrieval hot path stays free. on_batch_retrieve fires after the region-mapping loop (a plugin acts on regions mapped in the current batch); plugin stats are namespaced under stats["plugins"][<PluginClassName>].
• Stable accessor surface (the whole coupling contract): MaruHandler.is_region_mapped() and get_region_dax_path() (backed by new mapper/client get_dax_path). A contract test fails CI if the accessor signatures, hook names, or entry-point group drift.
• Docs: docs/source/api_reference/plugins.md.
• Deferred follow-ups (not regressions): defense-in-depth bounds check on server-supplied kv_offset + kv_length before device ops; access-dumper flush/logging tuning.

How it works

Core discovers plugins purely through the entry point, calls them at four lifecycle seams, and a plugin reaches back into core only through the hook arguments plus two documented accessors — nothing else couples the two packages.

sequenceDiagram
    autonumber
    participant EP as entry points<br/>(maru.handler_plugins)
    participant H as MaruHandler (core)
    participant PL as Plugin<br/>(separate package)
    participant HW as Device / hardware

    Note over H,PL: construction — MaruHandler.__init__
    H->>EP: load_handler_plugins() — soft-fail, MARU_PLUGINS filter
    EP-->>H: plugin instance(s)
    H->>PL: on_init(handler)

    Note over H,PL: retrieval hot path — batch_retrieve(keys)
    H->>H: batch_lookup_kv → map shared regions
    H->>PL: on_batch_retrieve(handler, keys, batch_resp)
    loop found + mapped entries
        PL->>H: is_region_mapped(rid) / get_region_dax_path(rid)
        PL->>HW: device hint (prefetch / pin)
    end
    H-->>H: return MemoryInfo[]

    Note over H,PL: teardown — close()
    H->>PL: on_close(handler)
    PL->>HW: release device resources

Loading

• Core never imports the plugin. Discovery is entirely via the maru.handler_plugins entry point; a missing or broken plugin is logged and skipped (soft-fail).
• Narrow coupling. A plugin uses only the on_batch_retrieve args plus is_region_mapped / get_region_dax_path — the stable contract a CI test pins.
• Hot-path placement. on_batch_retrieve runs after regions are mapped, so a plugin can act on live shared-memory addresses; with no plugin installed the seam is a single guarded no-op.

Test Plan

• Unit tests added/updated — tests/unit/test_plugin_loader.py (loader soft-fail / allowlist / dedup / None-return / dispatch isolation / API contract): 16 passed, ruff clean
• Existing tests pass (pytest -v) — note: the full unit suite hits a pre-existing, environment-specific native crash in the mocked connect() coverage tests on CUDA-enabled hosts (reproduces on main without this branch; unrelated to this change)
• E2E tests — validated on real CXL/DAX hardware with a real plugin (cross-instance producer/consumer): entry-point autoload + real device prefetch / pin / release; and in a full vLLM + LMCache benchmark, a plugin issues the same device hints as the equivalent in-tree path (identical prefetch counts, matching latency)

Related Issues

[github-actions]

Coverage Report

File	Stmts	Miss	Cover	Missing
__init__.py	6	0	100%
__main__.py	3	3	0%	5, 7–8
allocation_manager.py	113	9	92%	30–31, 44–45, 52, 237–240
client.py	186	9	95%	88, 130, 147–148, 311–313, 319, 363
config.py	46	1	98%	72
constants.py	9	0	100%
device_scanner.py	94	31	67%	25, 100, 102–104, 106, 114–123, 125, 127, 129, 134–143, 145, 147
handler.py	557	86	85%	153, 168, 179–186, 194–196, 211, 217–219, 227, 238–243, 248, 273, 300–301, 305, 345, 349–350, 355, 377, 384–385, 389–395, 398, 402–404, 420, 422–423, 432, 486, 507, 517–518, 624–626, 633, 755–758, 761, 772–775, 781, 867, 971, 1134–1138, 1144, 1155–1159, 1165, 1244, 1249, 1291
ipc.py	275	2	99%	365, 441
kv_manager.py	108	0	100%
logging_setup.py	19	0	100%
plugin.py	59	3	95%	65–67
protocol.py	232	0	100%
resource_manager_installer.py	103	13	87%	80–86, 167, 169–172, 187
rpc_async_client.py	190	0	100%
rpc_async_server.py	111	0	100%
rpc_client.py	66	0	100%
rpc_client_base.py	106	10	91%	185, 221–222, 233–234, 306–307, 311–312, 374
rpc_handler_mixin.py	106	19	82%	154–156, 159–161, 219–222, 227, 231–235, 256–257, 263
rpc_server.py	64	0	100%
serializer.py	81	0	100%
server.py	166	20	88%	44, 54–59, 64–65, 73, 168, 172, 243, 247, 265–266, 339–341, 426
stats_manager.py	95	0	100%
types.py	60	1	98%	145
uds_helpers.py	13	0	100%
memory
__init__.py	5	0	100%
allocator.py	55	0	100%
mapper.py	130	3	98%	229, 251, 300
owned_region_manager.py	101	1	99%	212
types.py	62	0	100%
TOTAL	3242	211	93%

Tests	Skipped	Failures	Errors	Time
702	4 💤	0 ❌	0 🔥	7.270s ⏱️

[youngrok-XCENA]

OOT plugin 시스템 설계·구현 품질이 매우 높습니다 (soft-fail 로더, 좁은 커플링 표면, 계약 테스트, vendor-neutral 문서). 블로킹 이슈는 없습니다.

요청하신 대로 MEDIUM 2건 · LOW 2건을 인라인으로 남깁니다:

• MEDIUM-1 (plugins.md): "owned region은 hint 안 쏨" 서술이 실제 코드와 배치 (owned도 mapper에 등록됨)
• MEDIUM-2 (test_plugin_loader.py): 계약 테스트가 on_batch_retrieve 필드 표면을 pin하지 않음
• LOW-1 (handler.py): 매 __init__마다 entry-point 스캔
• LOW-2 (handler.py): 서버 제공 offset/length가 plugin으로 무검증 전달 (deferred 확인)

MEDIUM 2건은 머지 전 처리를 권합니다.

[hyunyul-XCENA]

Follow-up in 6775e2a: folded the remaining review findings into the stable hook contract as docstring-only hardening (no behavior change).

• on_batch_retrieve: documented that KV bytes are at entry.kv_offset/kv_length (handle.offset is only the region mmap base) and that this hook is not serialized against close() — plugins issuing HW hints must be thread-safe and treat pin/unpin as idempotent.
• on_close: fires only when connected (not paired with on_init) and runs under the write lock, so must not block.
• on_init: don't acquire there a resource whose release depends on on_close.
• contribute_stats: keyed by class name → same-named plugins collide.
• Class docstring: soft-fail isolates raised exceptions, not hangs.

ruff clean, 17 plugin loader tests pass. LOW-2 (server offset/length bounds-check) remains tracked in #59.

[jooho-XCENA]

LGTM