feat: initial Rust Core (cpex-core and cpex-sdk)

[terylt]

Summary

Phase 1a of the CPEX Rust plugin runtime. Introduces cpex-core and cpex-sdk crates with a typed, 5-phase plugin execution framework.

This is the foundation for multi-language plugin support (Go, Python, WASM) with a shared Rust core. The existing Python implementation in cpex/framework/ is unchanged and continues to work as-is.

Closes: #15

What's included

Rust crates (crates/)

• cpex-core — Core runtime (4,482 lines)

  • Plugin trait (lifecycle: initialize, shutdown)
  • HookTypeDef trait (typed hook definitions with payload + result types)
  • HookHandler<H> trait (borrow-based handlers — framework never clones)
  • PluginResult<P> with separate payload and extension modifications
  • PluginPayload trait (object-safe base for all payloads)
  • PluginRef (trusted config from loader — plugin can't tamper with priority/mode/capabilities)
  • PluginRegistry with typed registration and name-based multi-hook registration (CMF pattern)
  • TypedHandlerAdapter (auto-bridges typed handlers to type-erased dispatch)
  • 5-phase Executor (Sequential → Transform → Audit → Concurrent → FireAndForget)
  • PluginManager with register_handler(), invoke::<H>(), and invoke_by_name()
  • PluginConfig, PluginMode, OnError, PluginCondition (backward compat)
  • 27 unit tests + 6 doc tests

• cpex-sdk — Lean re-exports for plugin authors

Key design decisions

• Borrow-based handlers — fn handle(&self, payload: &P, ...). The framework holds payload ownership. Plugins clone only when modifying. Enforced by Rust's borrow checker at compile time.
• PluginRef trust model — Plugin configs come from the config loader, never from plugin.config(). The executor reads mode, priority, and capabilities from PluginRef.trusted_config.
• Single invoke() path — AnyHookHandler has one method, not separate owned/ref paths. Simpler API.
• Box<dyn PluginPayload> instead of Box<dyn Any> — type errors caught at compile time.
• Extensions separate from payload — capability-filtered per plugin, modified independently. Extension-only changes don't clone the payload.
• CMF one-handler pattern — one HookHandler<CmfHook> impl registered for multiple hook names (cmf.tool_pre_invoke, cmf.llm_input, etc.).

What's NOT included (future phases)

• Language bindings (Go/FFI — Phase 1b, Python/PyO3 — Phase 5)
• Conformance test corpus (Phase 1c)
• Unified YAML config parsing (Phase 2)
• Full CMF extension types: MonotonicSet, Guarded, MetaExtension (Phase 3)
• WASM/native plugin hosts (Phase 6-8)

How to test

# Requires Rust 1.75+ (we develop on 1.94)                                                                                                                                                                                                       
cargo test -p cpex-core -p cpex-sdk                                                                                                                                                                                                              
                                        
See crates/README.md for setup instructions.

[araujof]

Nice work! Here are a few findings to address.

TL;DR

Scope and shape are right. The trait decomposition (Plugin lifecycle + HookHandler<H> dispatch + PluginRef trusted config) looks good. But some pieces look like stubs, and a few items are behavioral bugs rather than future-phase gaps. The biggest issues: the "concurrent" phase is serial, timeouts don't actually time anything out, OnError::Disable is silently equivalent to Ignore, and register_legacy never wires plugins into the hook index.

Design

Good

• Trust model is right. PluginRef.trusted_config as the sole source of scheduling; plugin cannot tamper. Covered by a dedicated test.
• Split of payload vs extensions matches the CMF invariant story and avoids COW on label-only changes.
• HookHandler<H> borrow-based signature lets the framework retain ownership; plugins pay clone cost only when modifying. Enforced by the borrow checker.
• Open HookType newtype keeps hosts extensible while giving compile-time constants for built-ins.

Concerns

• AnyHookHandler::invoke is sync while Plugin::initialize/shutdown are async_trait. A real plugin doing HTTP / DB lookups has no async entry point in the hot path. This will force either block_on (deadlock risk inside a tokio runtime) or a re-plumb when Phase 5 (PyO3) and Phase 7 (wasmtime) land, both inherently async. Decide now whether invoke returns Pin<Box<dyn Future>> or stays sync; retrofitting later breaks every binding.
• define_hook! generates an orphan trait. The macro emits MyHookHandler with an owned payload parameter, but the executor dispatches only through the generic HookHandler<H> (borrowed). The generated trait is never implemented or invoked anywhere.
• config.rs is a TODO comment. Either ship a minimal serde_yaml round-trip now or drop serde_yaml from cpex-core's deps.
• ManagerConfig wraps a single field. Today it's just ExecutorConfig. If no second field is coming in future phases, flatten it.
• Stale docs. registry.rs documents a removed invoke_owned/invoke_ref split. define_hook! docs claim "owned; executor decides borrow vs clone" but the executor never passes owned payloads anywhere.

Bugs

#	Severity	Location	Issue
1	High	executor.rs:350–421	run_concurrent_phase runs plugins serially — the loop for entry in entries { … .await } awaits each in turn. No join_all / FuturesUnordered / tokio::spawn.
2	High	executor.rs:246–249, 327–330, 372–375	timeout(dur, async { entry.handler.invoke(...) }) wraps a synchronous call. The inner future returns immediately, so the timeout is never observed. A misbehaving plugin can hang the pipeline indefinitely. Either make invoke async or run the sync call via tokio::task::spawn_blocking under the timeout.
3	High	executor.rs:283, 297	OnError::Disable is matched together with OnError::Ignore and has no effect; the plugin is never marked disabled. A plugin configured to auto-disable after failure will keep running and keep failing.
4	High	registry.rs:262–276	register_legacy inserts into plugins but never into hook_index. Every plugin registered this way is silently unreachable. No test covers it. Either remove the method or wire it up.
5	Medium	executor.rs:204–211	FireAndForget runs inline in run_ref_phase, blocking the pipeline. The design promises "background tokio tasks." Use tokio::spawn and don't await.
6	Medium	executor.rs:455–457	extract_erased returns Option<_> and silently drops on downcast failure. A handler returning the wrong result type causes the pipeline to continue as if the plugin did nothing; no log, no error. At minimum warn! on None.
7	Medium	executor.rs:266–269	modify_extensions replaces the whole Extensions struct (*extensions = me). A Transform plugin can clear labels, directly violating the monotonic-label invariant the design doc treats as type-system-guaranteed. Mark as a hard TODO in code, or enforce a superset check.
8	Medium	executor.rs:242	FilteredExtensions::default() is hard-coded for every dispatch. Plugins see no extensions regardless of declared capabilities. If a plugin relies on reading labels today it will always see empty, and a future fix that starts populating them will be a silent behavior change.
9	Low	manager.rs:245–252	initialize() returns on first plugin failure, leaving partially-initialized state. No shutdown() of already-initialized plugins before returning the error.
10	Low	error.rs:95 + executor	PluginViolation.plugin_name is documented as "set by the framework", but the executor never stamps it. Callers can't attribute a violation to its source.

Code quality

• unsafe impl Send + Sync on TypedHandlerAdapter (adapter.rs) is unnecessary. Arc<P> where P: Send+Sync is auto-Send+Sync; PhantomData<H> with H: Send+Sync is as well. Dropping the unsafe lets the compiler catch a future bound regression automatically.
• Dead field PluginManager.config (compiler warning). Clone out what's needed at construction or drop the field.
• fn default_priority() -> i32 { 100 } → const.
• has_hooks_for in registry re-checks !v.is_empty() even though unregister already retains empty entries out.
• initialize/shutdown iterate plugin_names() then get(name): two lookups per plugin. Collect PluginRef clones once and iterate.
• register_handler + register_handler_for_names duplicate the adapter construction. Extract a helper.
• impl Default for ManagerConfig can be #[derive(Default)].

Security

• CMF invariants not enforced. That's fine for Phase 1a scope, but the modify_extensions replace path in the executor means plugins can erase labels today, inheriting weaker guarantees than the design advertises. Maybe document this in the issue/README, or gate modify_extensions behind a #[cfg(phase_3)] until the tiered types land.
• No capability filtering (bug #8). Label-sensitive plugins written now will be wrong when Phase 3 turns filtering on.
• Timeout is decorative (bug #2). A blocking sync handler, or a plugin that deliberately spins, stalls the whole pipeline. This is exploitable with a malicious or buggy plugin.
• OnError::Disable unenforced (bug #3). A failing plugin configured as disable continues to run on every invocation, both wasting work and potentially amplifying a failure mode.
• Violation attribution missing (bug #10). Audit logs can't reliably identify which plugin denied a request.
• No payload-size or hook-depth limits. Acceptable for Phase 1a but problematic for Phase 1b/2 when FFI adds an untrusted ingress.

Tests

Tests cover registration, priority ordering, trusted-config tamper protection, allow/deny/modify, lifecycle, and typed vs dynamic invoke. Gaps worth closing before 1b:

• No test for PluginMode::Transform actually transforming.
• No test for Concurrent with >1 plugin (would expose bug #1 if asserting concurrency via timing).
• No test for timeout firing (would expose bug #2).
• No test for OnError::Disable semantics (would expose bug #3).
• No test for register_legacy dispatch (would expose bug #4).
• No test for FireAndForget returning before the background task finishes (would expose bug #5).
• No test for modify_extensions superset/monotonic behavior.
• No test asserting extensions are capability-filtered.

Recommendation

Request changes. High-severity items (concurrent serial, fake timeout, silent Disable, orphan register_legacy, blocking FireAndForget). Either fix them in this PR or document them out explicitly in the issue/epic with a "not functional in 1a" banner. Once the Highs are addressed, the rest can land as follow-up commits in Phase 1b.

[terylt]

All review items addressed or described where they will be deferred.

Async invoke (was sync)
AnyHookHandler::invoke is now async via #[async_trait]. tokio::time::timeout can observe and cancel
long-running handlers. TypedHandlerAdapter updated to match.

Concurrent phase was serial
Replaced the for loop + .await with tokio::spawn + futures::future::join_all. Handlers now run truly in
parallel. Results are zipped back with entries to access PluginRef without cloning into the spawn.

OnError::Disable did nothing
Added Arc<AtomicBool> circuit breaker on PluginRef. When a plugin errors with on_error: Disable, the executor
calls plugin_ref.disable(). mode() checks the flag and returns Disabled, so group_by_mode() skips it on all
subsequent invocations — instant, lock-free, shared across all clones.

register_legacy dead end
Removed. register_raw already covers the Python/WASM use case with explicit AnyHookHandler + hook index wiring.

FireAndForget ran inline
New spawn_fire_and_forget() method. Each handler gets its own tokio::spawn — pipeline returns immediately.

extract_erased silently dropped
Added warn! log on downcast failure.

modify_extensions replaces whole struct
Deferred to Phase 3. The executor currently replaces the entire Extensions struct. Phase 3 adds tier-aware merging
(MonotonicSet for labels, Guarded for controlled fields). TODO comment marks the spot.

FilteredExtensions::default() hardcoded
Deferred to Phase 3. Every plugin currently receives the same default FilteredExtensions with all fields visible.
Phase 3 adds per-plugin capability gating matching the Python filter_extensions() implementation. TODO comment marks
the spot.

initialize() partial failure
On failure, now shuts down already-initialized plugins in reverse order before returning the error.

PluginViolation.plugin_name never stamped
Framework now sets plugin_name on all violations (deny results, errors, timeouts) in both serial and concurrent
phases.

Cleanup:

• Removed unsafe impl Send + Sync on TypedHandlerAdapter — auto-derived from bounds.
• Removed dead config field on PluginManager.
• Removed orphan trait from define_hook! macro — now only generates the HookTypeDef marker struct. Removed paste
  dependency.

Context refactor (spec alignment):

• Removed GlobalContext. PluginContext now has local_state + global_state per spec §8.1. Identity, request
  metadata, tenant scope live in extensions, not context.
• Added PluginContextTable (HashMap<String, PluginContext> keyed by plugin ID). Optionally passed into
  invoke_by_name()/invoke() and returned in PipelineResult. Caller owns the scope — request-scoped,
  session-scoped, etc. — by choosing which table to pass and how long to keep it.

New tests (34 total, up from 27):

Test	What it covers
test_on_error_disable_skips_plugin_on_subsequent_invocations	Errors disable the plugin; second invocation skips
it
test_on_error_ignore_continues_without_disabling	Errors are swallowed; plugin stays active
test_on_error_fail_halts_pipeline	Errors halt pipeline; plugin_name stamped on violation
test_transform_modifies_payload	Transform mode payload modification flows through; downcast verifies content
test_concurrent_multiple_plugins_all_run	2 plugins sleep 50ms each; asserts both ran AND total <90ms (parallel
not serial)
test_timeout_fires_on_slow_handler	Handler sleeps 5s, timeout is 1s; pipeline denied with plugin_timeout in
~1s
test_fire_and_forget_returns_before_task_completes	Handler sleeps 200ms; pipeline returns instantly with task
not yet done; task completes in background

Context state semantics by phase:

Handlers receive &mut PluginContext and can write directly to local_state and global_state. How those writes are
handled depends on the phase:

• Sequential / Transform — global_state changes are merged back after each plugin, so the next plugin in the
  chain sees them. local_state is private per-plugin and persists across hook invocations via the
  PluginContextTable.
• Concurrent — each spawned task gets its own clone of the context. Writes to global_state or local_state are
  local to that task and discarded. This matches the concurrent authority model (read-only, can block but cannot
  modify).
• Audit / FireAndForget — same as concurrent. Context is a read-only snapshot; writes are discarded.

The PluginContextTable (keyed by plugin ID) is returned in PipelineResult and can be passed into subsequent hook
invocations to preserve per-plugin local_state across hooks in the same scope. The caller owns the table's lifecycle
— request-scoped, session-scoped, etc.

Two new tests verify this: test_global_state_flows_between_serial_plugins (writer plugin sets a key, reader plugin
in the same serial chain sees it) and test_local_state_persists_across_hook_invocations (counter increments across
two separate invoke calls via the threaded context table).

[araujof]

LGTM

Nice work addressing the reviews.