[EPIC]: CPEX Rust Core and multi-language plugin runtime

[terylt]

Summary

Rewrite the CPEX PluginManager as a Rust core library with C FFI, Python (PyO3), and Go (cgo) bindings. Rust enforces CMF invariants (monotonic labels, immutable SubjectExtension, scope narrowing) internally through the type system; inputs crossing language/runtime boundaries are validated at ingress before entering the core. This gives us a single plugin execution engine shared across all language consumers, with support for native Rust, WASM, and Python plugin hosts.

The Rust core replaces the current Python PluginManager while maintaining backward compatibility with existing Python plugins via a PyO3 bridge host.

Motivation

The current Python PluginManager works, but:

1. Invariants are enforced by convention, not the type system. Monotonic label sets, immutable security extensions, and delegation scope narrowing are documented rules that plugins can violate at runtime. Rust enforces these internally through the type system; inputs from other languages are validated at ingress.
2. Every consumer reimplements the runtime. If Kagenti (Go), ContextForge (Python), or an Envoy filter (Rust) wants CPEX plugins, they each need a full PluginManager implementation. A shared Rust core with language bindings solves this.
3. WASM plugin sandboxing requires a native runtime. Python cannot efficiently host WASM plugins. A Rust core with wasmtime gives us sandboxed third-party plugins where the host grants no filesystem, network, or memory capabilities by default — only those explicitly configured by the runtime.
4. Performance-sensitive paths (identity resolution, policy evaluation, session lookup) benefit from native execution, especially in high-throughput gateway deployments.

User Stories

User Story 1: Gateway Integrator (Python — ContextForge)

• As a: ContextForge gateway developer
• I want: to replace from cpex import PluginManager with a Rust-backed PluginManager that exposes the same Python API
• So that: I get compile-time CMF invariants, WASM plugin support, and faster policy evaluation without changing my integration code

Acceptance Criteria

Scenario: Drop-in replacement for Python PluginManager
  Given a ContextForge gateway using cpex.PluginManager
  When I upgrade the cpex package to the Rust-backed version
  Then existing Python plugin configurations load without changes
  And existing Python plugins execute through the PyO3 bridge host
  And the 5-phase execution order is preserved (sequential → transform → audit → concurrent → fire_and_forget)

Scenario: Monotonic security labels enforced at compile time
  Given a plugin attempts to remove a label from SecurityExtension
  When the Rust type system evaluates the operation
  Then compilation fails — MonotonicSet has no remove() method

Scenario: WASM plugin loading
  Given a plugin declared as kind: "wasm://path/to/plugin.wasm"
  When the PluginManager initializes
  Then the plugin loads in a wasmtime sandbox
  And the WASM host grants no filesystem, network, or host memory access by default (only explicitly configured capabilities)
  And the plugin implements the same Plugin trait as native plugins

User Story 2: Gateway Integrator (Go — Kagenti)

• As a: Kagenti developer working in Go
• I want: to use cpex.NewManager() from a Go package backed by the same Rust core
• So that: Kagenti gets identical policy enforcement behavior as ContextForge without reimplementing the PluginManager in Go

Acceptance Criteria

Scenario: Go bindings via cgo + C FFI
  Given the cpex-ffi crate is compiled to libcpex_ffi.so
  And include/cpex.h is generated by cbindgen
  When a Go application imports "github.com/contextforge/cpex/go"
  Then cpex.NewManager() initializes the Rust PluginManager via cgo
  And cpex.InvokeHook() dispatches through the same 5-phase executor

Scenario: Monorepo developer workflow
  Given a developer has cloned the cpex monorepo
  When they run "cargo build --release -p cpex-ffi && cd go && go test ./..."
  Then the Go tests pass using relative paths to the compiled library
  And no system-wide installation is required

User Story 3: Plugin Author (Rust)

• As a: a security team member writing a content-filter plugin
• I want: to write my plugin in Rust using the cpex-sdk crate
• So that: my plugin compiles to a native shared library with zero runtime overhead

Acceptance Criteria

Scenario: Plugin author uses lean SDK crate
  Given a Rust developer adds cpex-sdk as a dependency
  When they implement the Plugin trait and compile
  Then the resulting .so/.dylib can be loaded by cpex-hosts as a native plugin
  And cpex-sdk does not pull in wasmtime, PyO3, or the full PluginManager

Scenario: Plugin author targets WASM
  Given a Rust developer compiles with --target wasm32-wasip1
  When they use only cpex-sdk types
  Then the plugin compiles to .wasm and loads via the WASM host

Design

Crate Architecture

cpex/
├── Cargo.toml                    # Workspace root
├── pyproject.toml                # maturin build for Python package
├── Makefile                      # Top-level: rust-ffi, go-test, python-build
│
├── crates/
│   ├── cpex-core/                # Pure Rust — no FFI deps
│   │   └── src/
│   │       ├── manager.rs        # PluginManager + lifecycle
│   │       ├── executor.rs       # 5-phase execution engine
│   │       ├── registry.rs       # PluginInstanceRegistry + HookRegistry
│   │       ├── plugin.rs         # Plugin trait, PluginRef, HookRef
│   │       ├── config.rs         # Unified YAML config (serde)
│   │       ├── context.rs        # GlobalContext, PluginContext
│   │       ├── policy.rs         # PluginMode, OnError, HookPayloadPolicy
│   │       ├── error.rs          # PluginError, Violation, Timeout
│   │       ├── hooks/
│   │       │   ├── types.rs      # HookType enum, payload/result traits
│   │       │   └── builtin.rs    # tool_pre_invoke, prompt_pre_fetch, etc.
│   │       ├── cmf/
│   │       │   ├── message.rs    # Message, ContentPart, Role, Channel
│   │       │   ├── view.rs       # MessageView (zero-copy projection)
│   │       │   └── extensions/
│   │       │       ├── security.rs    # MonotonicSet, SubjectExt (immutable)
│   │       │       ├── delegation.rs  # DelegationChain (append-only, scope-narrowing)
│   │       │       ├── request.rs
│   │       │       ├── agent.rs
│   │       │       ├── http.rs        # Guarded (capability-gated)
│   │       │       ├── mcp.rs
│   │       │       └── filter.rs      # Capability-gated extension filtering
│   │       └── session/
│   │           ├── state.rs      # SessionState (monotonic merge)
│   │           ├── store.rs      # SessionStore trait + in-memory impl
│   │           └── resolver.rs   # Multi-tier session resolution
│   │
│   ├── cpex-hosts/               # Plugin host runtimes (feature-gated)
│   │   └── src/
│   │       ├── native.rs         # dlopen .so/.dylib — libloading
│   │       ├── wasm.rs           # wasmtime sandbox
│   │       └── python.rs         # PyO3 bridge (calls INTO Python plugins)
│   │
│   ├── cpex-ffi/                 # C ABI for Go/Swift/other consumers
│   │   ├── src/
│   │   │   ├── lib.rs            # #[no_mangle] extern "C" functions
│   │   │   ├── handles.rs        # Opaque handle types + Arc safety
│   │   │   ├── manager.rs        # cpex_manager_new(), cpex_invoke_hook()
│   │   │   ├── payload.rs        # Byte buffer exchange across boundary
│   │   │   └── error.rs          # cpex_last_error(), error codes
│   │   └── cbindgen.toml         # Generates include/cpex.h
│   │
│   ├── cpex-python/              # PyO3 bindings (Python calls INTO Rust)
│   │   └── src/
│   │       ├── lib.rs            # #[pymodule]
│   │       ├── manager.rs        # PyPluginManager
│   │       ├── config.rs         # from_yaml()
│   │       ├── types.rs          # PyPluginResult, PyExtensions
│   │       └── plugin.rs         # PyPlugin trait adapter
│   │
│   └── cpex-sdk/                 # Lean crate for plugin authors
│       └── src/
│           ├── plugin.rs         # Plugin trait + derive macro stubs
│           ├── payload.rs        # PluginPayload, PluginResult
│           ├── context.rs        # PluginContext (read-only view)
│           └── extensions.rs     # Extension types (re-exported from core)
│
├── include/
│   └── cpex.h                    # Generated by cbindgen
│
├── python/
│   └── cpex/                     # Thin Python wrapper
│       ├── __init__.py           # Imports from cpex._native
│       ├── _native.pyi           # Type stubs
│       ├── compat.py             # Backward-compat shims
│       └── testing.py            # Test harness for plugin authors
│
├── go/                           # module: github.com/contextforge/cpex/go
│   ├── go.mod                    # package name: cpex
│   ├── cpex.go                   # NewManager, InvokeHook, etc.
│   ├── config.go
│   ├── types.go
│   ├── errors.go
│   └── internal/
│       ├── ffi.go                # cgo → cpex.h (pkg-config + relative fallback)
│       └── memory.go             # Handle lifecycle, free() safety
│
└── tests/
    ├── rust/
    ├── python/
    └── go/

Key Design Decisions

1. cpex-core is pure Rust — no FFI, no wasmtime, no PyO3

This is the most important structural decision. Core contains the PluginManager, executor, CMF types, session store, and config parser — with zero external runtime dependencies. This means:

• Core compiles to any Rust target including wasm32-wasip1
• Core is testable without standing up Python or WASM runtimes
• Plugin hosts (cpex-hosts) depend on core, not the other way around

2. cpex-hosts is separate and feature-gated

[features]
default = ["native", "wasm", "python"]
native = ["libloading"]
wasm = ["wasmtime"]
python = ["pyo3"]

Each host implements the Plugin trait by bridging to foreign plugin code. A Go-only deployment can compile with default-features = false, features = ["native", "wasm"] and skip PyO3 entirely.

3. cpex-python vs cpex-hosts::python — opposite directions

These both use PyO3 but serve different roles:

Crate	Direction	Purpose
cpex-python	Python → Rust	Python code calls the Rust PluginManager
cpex-hosts::python	Rust → Python	Rust PluginManager calls existing Python plugins

ContextForge needs both. Kagenti needs neither.

4. cpex-sdk is lean for plugin authors

Plugin authors depend only on cpex-sdk, which re-exports the Plugin trait and payload/result types from core. It does not pull in the PluginManager, hosts, or FFI. This is also the crate WASM plugins compile against.

5. Go bindings use coarse-grained C FFI with zero-copy where possible

The FFI boundary is coarse-grained: one round trip per hook invocation, no chatty per-field accessors. Data crosses the boundary with minimal copying:

Direction	What crosses	Copy?
Go → Rust (payload in)	Pointer + length to Go's existing bytes	Zero-copy read; Rust deserializes into owned types
Rust → Go (result envelope)	#[repr(C)] struct with scalar fields	Zero-copy (shared C layout)
Rust → Go (modified payload)	Pointer + length to Rust-owned bytes	Zero-copy read; Go copies only if it needs to keep it
Cleanup	cpex_result_free()	Go tells Rust when to drop

Serialization only happens when necessary: always on input (Go bytes → Rust types), and on output only if a plugin modified the payload. A deny with no modification requires zero serialization on the result path — Go reads the C struct directly.

// cpex.h
typedef struct cpex_manager cpex_manager_t;

// Result envelope — #[repr(C)], Go reads fields directly
typedef struct {
    int             continue_processing;   // 0 = denied, 1 = allowed
    const char*     violation_code;        // NULL if allowed
    const char*     violation_reason;      // NULL if allowed
    const uint8_t*  modified_payload;      // NULL if unmodified
    size_t          modified_payload_len;  // 0 if unmodified
} cpex_result_t;

// ABI version for compatibility checking
uint32_t            cpex_abi_version(void);

// Lifecycle
cpex_manager_t*     cpex_manager_new(const char* config_path);
void                cpex_manager_free(cpex_manager_t* mgr);

// Hook dispatch — zero-copy pointer+length in, C struct out
cpex_result_t*      cpex_invoke_hook(cpex_manager_t* mgr,
                                      const char* hook_type,
                                      const uint8_t* payload_buf,
                                      size_t payload_len);
void                cpex_result_free(cpex_result_t* result);

// Error reporting
const char*         cpex_last_error(void);

Go consumers interact via cpex.NewManager() / cpex.InvokeHook() — the cgo layer is internal.

Monorepo devs: cargo build -p cpex-ffi && cd go && go test — cgo finds the library via relative paths with pkg-config fallback for system installs.

5a. Wire format: MessagePack (default), JSON (debug)

Payloads are serialized at the FFI boundary using MessagePack by default (~10x faster than JSON, same data model, schema-less). JSON is available as a debug option for human-readable inspection.

Format	Serialize	Deserialize	Schema required?	Use case
MessagePack (default)	~20µs	~20µs	No	Production — fast, compact binary
JSON (debug)	~200µs	~200µs	No	Development — human-readable

MessagePack is a drop-in replacement for JSON at the serde layer — same data model (maps, arrays, strings, numbers), just binary-encoded. No schema files, no code generation, no type model changes.

Alternatives considered:

Format	Why not (for now)
Protocol Buffers	Requires .proto schema files + codegen for internal FFI — overkill
FlatBuffers / Cap'n Proto	Zero-copy reads but requires generated accessor types instead of plain structs — premature optimization
CBOR	Same family as MessagePack, slightly less Rust/Go library support
Bincode	Rust-specific, no stable Go library

FlatBuffers remains an option if profiling shows serialization is a bottleneck on a hot path. The FFI surface is format-agnostic — swapping the wire format doesn't change the C API.

6. CMF invariants enforced in the Rust core

Rust's type system enforces invariants internally; inputs from other languages are validated at ingress before entering the core:

// Security labels: add-only (no remove, no clear)
pub struct MonotonicSet<T: Eq + Hash> { inner: HashSet<T> }
impl<T: Eq + Hash> MonotonicSet<T> {
    pub fn insert(&mut self, value: T) { self.inner.insert(value); }
    pub fn contains(&self, value: &T) -> bool { self.inner.contains(value) }
    // No remove(). No clear(). No drain().
}

// Delegation chain: append-only, scopes must narrow
pub struct DelegationChain { hops: Vec<DelegationHop> }
impl DelegationChain {
    pub fn push(&mut self, hop: DelegationHop) -> Result<(), ScopeEscalation> {
        if let Some(prev) = self.hops.last() {
            if !hop.scopes.is_subset(&prev.scopes) {
                return Err(ScopeEscalation { .. });
            }
        }
        self.hops.push(hop);
        Ok(())
    }
}

Execution Model (preserved from Python)

The 5-phase execution order is identical to the current Python implementation:

SEQUENTIAL → TRANSFORM → AUDIT → CONCURRENT → FIRE_AND_FORGET

Phase	Block?	Modify?	Execution	Use Case
Sequential	Yes	Yes	Serial, chained	Policy enforcement + transformation
Transform	No	Yes	Serial, chained	Data shaping (PII redaction)
Audit	No	No	Serial	Observation, logging
Concurrent	Yes	No	Parallel (fail-fast)	Independent policy gates
Fire-and-forget	No	No	Background (tokio tasks)	Telemetry, async side effects

Plugin Trait

#[async_trait]
pub trait Plugin: Send + Sync {
    fn config(&self) -> &PluginConfig;
    async fn initialize(&self) -> Result<(), PluginError>;
    async fn execute(
        &self,
        hook_type: &str,
        payload: &serde_json::Value,
        context: &PluginContext,
    ) -> Result<PluginResult, PluginError>;
    async fn shutdown(&self) -> Result<(), PluginError>;
}

Note: The manager wraps each plugin in a PluginRef that holds the authoritative config from the config loader — not from the plugin. The plugin's config() is available for the plugin's own reading during execute(), but the manager/executor never reads it. Trust flows one direction: config loader → manager → PluginRef → executor.

This single trait is implemented by:

• Native Rust plugins (directly)
• cpex-hosts::wasm (bridges to WASM guest)
• cpex-hosts::python (bridges to Python plugin classes)
• cpex-hosts::native (bridges to dlopen'd shared libraries)

Additional Framework Features

The following features are supported by the Rust core:

Dynamic Hook Types

Hook types use a HookType(String) newtype for runtime extensibility. Built-in hook names are provided as &str constants in hook_names:: and cmf_hook_names:: modules for compile-time checking of known hooks, while hosts can register custom hooks at runtime:

// Built-in string constants (compile-time checked)
pub mod hook_names {
    pub const TOOL_PRE_INVOKE: &str = "tool_pre_invoke";
    pub const TOOL_POST_INVOKE: &str = "tool_post_invoke";
    // ...
}

// Create a HookType from a built-in constant or custom string
let builtin = HookType::new(hook_names::TOOL_PRE_INVOKE);
let custom = HookType::new("generation_pre_call");

Payload-Agnostic Design

The framework operates on any type implementing PluginPayload, not just CMF messages. MessagePayload is a built-in payload type; domain-specific hooks use domain-specific payloads through the same pipeline, modes, and capability gating.

Function Hooks

In addition to the class-based Plugin trait, standalone functions can be registered directly as hook handlers. This is the simplest way to add a single hook without a full plugin struct.

PluginSet (Composable Groupings)

PluginSet groups related plugins into reusable, composable units. Sets are inert containers — they organize plugins for registration but do not execute anything themselves. Sets can nest other sets.

Scoped Registration

Plugins can be activated for a specific scope and automatically deregistered when the scope exits. In Rust this uses RAII (Drop); Python and Go bindings expose context managers / defer respectively.

PipelineResult

PipelineResult wraps the aggregate outcome of a full hook invocation with factory methods (allowed(), denied()). Callers treat it identically to PluginResult.

COW Validation & Hook Payload Policies

Modify plugins operate on copy-on-write payloads. After modification, the framework validates against extension mutability tiers (immutable, monotonic, guarded, mutable). Per-hook HookPayloadPolicy can further restrict which payload fields are writable.

Global Settings

plugin_settings:
  plugin_timeout: 30
  cow_validation: strict        # strict | warn | disabled
  short_circuit_on_deny: true

Unified Configuration

The Rust core parses the unified YAML config:

global:
  identity:
    provider: cedarling
  session:
    store: memory
    ttl: 3600
  policies:
    pii:
      policy: require(perm.pii_access)
    hr:
      policy: require(role.hr | role.auditor)

plugins:
  - name: apl-policy
    kind: builtin
    hooks: [tool_pre_invoke, tool_post_invoke]
    mode: sequential
    capabilities: [read_security, append_labels]
  - name: content-filter
    kind: "wasm://plugins/content_filter.wasm"
    hooks: [tool_pre_invoke]
    mode: sequential
  - name: legacy-audit
    kind: "python://plugins.audit.AuditPlugin"
    hooks: [tool_post_invoke]
    mode: audit

routes:
  - tool: get_compensation
    meta:
      tags: [pii, hr]
      scope: hr-services
    policy:
      - "args.include_ssn & !perm.view_ssn": deny
    result:
      salary: "redact(!role.hr)"
      ssn: "redact(!perm.view_ssn)"

Typed Hook System

• HookType trait defines typed payload + result per hook. No serde_json::Value in the Rust core — native Rust plugins work with typed structs at zero cost.
• Mode drives scheduling — the hook type doesn't declare read-only vs mutating. The executor decides borrow vs clone based on the plugin's mode from PluginRef.trusted_config.
• Extensions are a separate parameter — capability-filtered per plugin, modified independently from the payload (no COW needed for extension-only changes).
• CMF: one handler, multiple hook names — a plugin implements CmfHookHandler once, registers for cmf.tool_pre_invoke, cmf.llm_input, etc. The MessageHookType field tells the handler which hook fired.
• Python compatibility preserved — @hook decorators, Plugin base class, and block()/allow() helpers are unchanged. Rust-defined payloads surface in Python as PyO3-wrapped objects with typed attributes. Python can also define custom hooks at runtime via register_hook_type().
• Serialization only at language boundaries — native Rust: zero-cost. Python: PyO3 attribute conversion. Go/WASM: MessagePack (default), JSON (debug).

Implementation Phases

Phase 1 is deliberately narrow: minimal Rust execution kernel, one payload path (JSON values), and Go as the first binding target (there is active interest from Red Hat, and Python already has a complete implementation). We prove the execution semantics before expanding.

Phase	Deliverable	Depends On	Can Parallelize?
1a	cpex-core: Plugin trait, PluginManager, 5-phase executor, hook registry	—	—
1b	cpex-ffi + go/: C ABI + Go bindings — first consumer, proves FFI semantics	Phase 1a	—
1c	Conformance test corpus (YAML scenarios, runs against Python impl and Rust/Go)	Phase 1a	Yes (with 1b)
2	cpex-core config: unified YAML config parsing	Phase 1a	—
3	cpex-core extensions: CMF types, monotonic sets, capability-gated filtering, session store	Phase 1a	Yes (with 2)
4	cpex-sdk: Lean plugin author crate	Phase 1a	Yes (with 2, 3)
5	cpex-python: PyO3 bindings (Python calls Rust PluginManager)	Phase 1a	Yes (with 2, 3, 4)
6	cpex-hosts::python: Run existing Python plugins from Rust	Phase 5	—
7	cpex-hosts::wasm: wasmtime sandbox host	Phase 1a + 4	Yes (with 5, 6)
8	cpex-hosts::native: dlopen for .so plugins	Phase 1a	Yes (with all)
9	Integrate apl-core + cedarling as built-in plugins	Phase 3	—

Phases 2-8 are largely independent and can be worked in parallel once Phase 1 lands.

Backward Compatibility

Python backward compatibility has two layers:

Layer	Guarantee	Scope
API compatibility	from cpex import PluginManager, public interfaces, config YAML format	Hard requirement (Phase 5+6)
Behavioral compatibility	Documented lifecycle semantics: 5-phase ordering, capability gating, COW validation, error isolation	Hard requirement

Some undocumented behaviors may differ once execution moves into Rust — mutation timing, threading model, internal exception types. These are explicitly not guaranteed.

ABI Stability (cpex-ffi)

Documented as part of Phase 1b (FFI/Go bindings):

• ABI version function — cpex_abi_version() returns a version integer; consumers check at init.
• Ownership rules — Every handle-returning function documents who owns the handle and which _free function releases it.
• Semver for cpex.h — Breaking changes to the C header require a major version bump.
• Stable vs unstable surfaces — Functions prefixed cpex_experimental_ are not covered by stability guarantees.

Conformance Tests

Since the goal is shared semantics across languages, a common test corpus will be introduced in Phase 1c:

• YAML scenario files specifying: hook type, plugins (mode, priority, config), payload, expected outcome (allow/deny/modify).
• Each scenario runs against both the existing Python PluginManager and the Rust core (via Go bindings initially, Python bindings later).
• Covers: hook ordering, allow/deny behavior, mutation rules, timeout semantics, error handling modes (fail/ignore/disable).
• Scenarios are the source of truth for behavioral compatibility — if a scenario passes in both runtimes, the behavior is guaranteed.

Alternatives Considered

1. Keep Python PluginManager, add Rust only for hot paths (APL, session)

• Pro: Less work. Already partially done with apl-core PyO3.
• Con: Every new consumer (Go, Envoy) must reimplement the PluginManager. CMF invariants remain unenforced.
• Rejected because: The PluginManager is the value — policy enforcement, phase ordering, capability gating. Optimizing leaves only gives you speed; a shared core gives you correctness across languages.

2. Use gRPC/HTTP between language runtimes instead of FFI

• Pro: No cgo, no PyO3. Language-independent via network.
• Con: ~1-10ms per call (network + serialization). Unacceptable for pre/post-invoke hooks on every tool call in a gateway hot path.
• Rejected because: The plugin pipeline runs on every request. FFI overhead is ~50-200ns; gRPC is 1000-10000x more.

3. Single cpex-ffi crate that bundles everything

• Pro: One library to link.
• Con: Go consumers pull in PyO3 + wasmtime even if they don't need them. Compilation time explodes.
• Rejected because: Feature-gated cpex-hosts + separate cpex-ffi keeps the dependency graph lean per consumer.

Additional Context

• Existing Rust work: apl-core (APL evaluator + token service) already compiles via maturin with PyO3 bindings — same pattern cpex-python will use.
• ContextForge gateway: Primary Python consumer. Backward compatibility with existing Python plugins is a hard requirement (Phase 5).
• Kagenti: Primary Go consumer. Go bindings (Phase 7) enable shared policy enforcement across both gateways.

[araujof]

@terylt The architecture is coherent and the crate split (cpex-core, cpex-hosts, cpex-python, cpex-ffi, cpex-sdk) makes sense. The main suggestions below are about tightening semantics, migration expectations, and long-term maintainability.

1. Reword “compile-time invariants”
Current wording may overstate what is possible across Python / Go / WASM boundaries.

Suggested wording:

Rust enforces CMF invariants internally through the type system. Inputs crossing language/runtime boundaries are validated at ingress before entering the core.

2. Resolve hook type model
The issue mentions both:

• HookType enum
• hook types are open / extensible

Suggested model:

• BuiltinHook enum for built-in hooks
• HookId(String) (or interned string/newtype) for runtime-defined hooks

This should resolve the conflict while preserving extensibility and typed built-ins.

3. Keep the FFI boundary coarse-grained
Recommend avoiding overly chatty APIs like field/path getters.

Prefer:

• request bytes in
• result bytes out
• opaque handles
• explicit free functions
• ABI versioning

This will simplify Go bindings and future compatibility.

4. Clarify Python backward compatibility
Recommend separating:

• API compatibility (imports / public interfaces preserved)
• behavioral compatibility (documented lifecycle semantics preserved)

Some undocumented behaviors may differ once execution moves into Rust (identity, mutation timing, threading, etc.).

5. Tighten WASM security wording
Instead of saying WASM cannot access filesystem/network, suggest:

By default, the WASM host grants no filesystem/network capabilities except those explicitly configured by the runtime.

More accurate and auditable.

6. Add ABI stability policy now
Since Go / external consumers depend on FFI, recommend documenting:

• ABI version function
• ownership / free rules
• semver expectations for cpex.h
• stable vs unstable surfaces

7. Add conformance tests early
Since the goal is shared semantics across languages, introduce a common test corpus early for:

• hook ordering
• allow/deny behavior
• mutation rules
• timeout semantics
• error handling

8. Narrow Phase 1 scope
Phase 1 may be ambitious.

Consider making Phase 1:

• minimal Rust execution kernel
• one payload path
• one binding path (Python first)

Then expand once semantics are proven.

[terylt]

Hi @araujof , thanks for the feedback. I updated the original proposal above with:

Thanks for the thorough review — all good points. Here's how we're addressing each:

1. Reword "compile-time invariants" — Agreed. Updated the proposal. New wording: "Rust enforces CMF invariants internally through the type system; inputs crossing language/runtime boundaries are validated at ingress before entering the core."

2. Resolve hook type model — We landed on HookType(String) newtype with &str constants in hook_names:: / cmf_hook_names:: modules. This gives compile-time checking for known hooks while keeping extensibility for custom hooks. We opted against a BuiltinHook enum since the string constants already give us the typed reference points without requiring conversion between enum and string at dispatch boundaries. Updated the proposal to clarify.

3. Coarse-grained FFI — Agreed. Removed the per-field getter (cpex_result_get_field) from the proposal. The FFI surface is now: request bytes in, result bytes out, opaque handles, explicit free, ABI version. Updated the cpex.h example.

4. Python backward compatibility — Good distinction. Added a section to the proposal separating API compatibility (imports, public interfaces) from behavioral compatibility (documented lifecycle semantics). Undocumented behaviors (mutation timing, threading, internal exception types) are explicitly not guaranteed.

5. WASM security wording — Updated. Now reads: "the WASM host grants no filesystem, network, or host memory capabilities by default — only those explicitly configured by the runtime."

6. ABI stability policy — Added as a deliverable in Phase 1b (since Go bindings are now the first binding target). Covers: ABI version function, ownership/free rules, semver for cpex.h, stable vs unstable (cpex_experimental_ prefix) surfaces.

7. Conformance tests — Strongly agree. Added Phase 1c: a shared YAML test corpus that runs against both the Python PluginManager and the Rust core. Covers hook ordering, allow/deny, mutation rules, timeouts, and error handling modes. This becomes the source of truth for behavioral compatibility.

8. Narrow Phase 1 — Agreed and narrowed. Phase 1 is now:

• 1a: Minimal Rust execution kernel (Plugin trait, PluginManager, 5-phase executor, hook registry) — in progress, core types and registry done
• 1b: cpex-ffi + Go bindings — first binding target (Red Hat has expressed interest in Go, and we already have a complete Python implementation)
• 1c: Conformance test corpus

We also re-prioritized Go bindings ahead of Python bindings since Python already has a full working implementation. PyO3 bindings move to Phase 5.

Additional update: Typed Hook System

[terylt]

I also drilled down a bit into how the hooking system would work:

Typed Hook System Design

Status: Draft

Goals

• Hooks have typed payloads and results — no runtime JSON parsing for native Rust plugins.
• Extensions are a separate parameter, capability-filtered per plugin. Extension modifications don't require copying the payload.
• The plugin's mode drives scheduling and authority — not the hook type. The executor determines borrow vs owned at runtime based on mode.
• CMF plugins implement one handler for multiple hook names (tool_pre_invoke, llm_input, etc.) — the payload carries which hook fired.
• Custom hooks are first-class — hosts define their own hook types with their own payloads using a macro.
• Serialization only at language boundaries — native Rust plugins never touch JSON or MessagePack.

Hook Type Trait

A hook type defines its payload and result types. It does not declare an access pattern — the plugin's mode (from PluginConfig) determines whether it reads or mutates, and the executor handles scheduling accordingly.

pub trait HookType: Send + Sync + 'static {
    /// The typed payload handlers receive.
    /// Must be Clone so the executor can COW when a modifier needs ownership.
    type Payload: Send + Sync + Clone;

    /// The typed result handlers return.
    type Result: Send + Sync;

    /// Hook name — used as the registry key and in config YAML.
    const NAME: &'static str;
}

Mode Drives Everything

The hook type defines what data flows through. The plugin's mode (from PluginRef.trusted_config) defines what authority the plugin has and how it runs:

Mode	Receives	Can Block?	Can Modify?	Execution
Sequential	owned Payload (clone)	Yes	Yes	Serial, chained
Transform	owned Payload (clone)	No	Yes	Serial, chained
Audit	&Payload (borrow)	No	No	Serial
Concurrent	&Payload (borrow)	Yes	No	Parallel
FireAndForget	&Payload (borrow)	No	No	Background

The executor clones the payload only when dispatching to Sequential or Transform plugins. Audit, Concurrent, and FireAndForget plugins receive a borrow — zero copy.

Security invariants (immutable extensions, monotonic labels, guarded writes) are enforced by the types inside the payload and extensions (Arc<T>, MonotonicSet, Guarded<T>), not by borrow vs owned. A plugin that receives an owned payload still cannot strip a security label — MonotonicSet has no remove().

Extensions as a Separate Parameter

Extensions are not part of the payload. They are passed as a separate parameter so the framework can:

1. Capability-filter per plugin — each plugin gets a different FilteredExtensions view without touching the payload.
2. Accept extension modifications back (labels, headers) without copying the payload.
3. Pass the same payload to multiple plugins while giving each different filtered extensions.

Results carry payload and extension modifications separately:

pub struct HookResult<P> {
    pub continue_processing: bool,
    pub modified_payload: Option<P>,            // only if message content changed
    pub modified_extensions: Option<Extensions>, // only if extensions changed
    pub violation: Option<PluginViolation>,
}

Extension-only changes (add a label, set a header) don't require copying the payload.

The define_hook! Macro

Generates a HookType impl and a handler trait from a declaration:

define_hook! {
    /// Fires before a tool is invoked.
    ToolPreInvoke {
        payload: ToolPreInvokePayload,
        result: HookResult<ToolPreInvokePayload>,
    }
}

// Generates:
//
// pub struct ToolPreInvoke;
//
// impl HookType for ToolPreInvoke {
//     type Payload = ToolPreInvokePayload;
//     type Result = HookResult<ToolPreInvokePayload>;
//     const NAME: &'static str = "tool_pre_invoke";
// }
//
// pub trait ToolPreInvokeHandler: Plugin + Send + Sync {
//     fn tool_pre_invoke(
//         &self,
//         payload: ToolPreInvokePayload,
//         extensions: &FilteredExtensions,
//         ctx: &PluginContext,
//     ) -> HookResult<ToolPreInvokePayload>;
// }

The handler always receives an owned payload in its signature. The executor decides whether to pass a clone or the original based on mode:

• Sequential / Transform — executor clones, passes owned. Plugin may return modifications.
• Audit / Concurrent / FireAndForget — executor calls a read-only dispatch path internally. Any modifications returned are discarded.

CMF Hooks: One Handler, Multiple Hook Names

CMF plugins implement one handler function that handles all CMF hook points. The MessageHookType field on the payload tells the plugin which hook fired.

Two levels:

• Hook type (typed) — CmfHook defines payload and result types.
• Hook name (string) — "cmf.tool_pre_invoke", "cmf.llm_input", etc. Multiple names share one hook type.

CMF Payload

pub enum MessageHookType {
    ToolPreInvoke,
    ToolPostInvoke,
    LlmInput,
    LlmOutput,
    PromptPreFetch,
    PromptPostFetch,
    ResourcePreFetch,
    ResourcePostFetch,
}

/// CMF message payload. Extensions are NOT here — they are
/// passed separately as FilteredExtensions.
pub struct MessagePayload {
    pub message: Message,
    pub views: Vec<MessageView>,
    pub hook: MessageHookType,
}

CMF Hook Definition

define_hook! {
    /// CMF message evaluation hook.
    /// One hook type, multiple hook names.
    CmfHook {
        payload: MessagePayload,
        result: HookResult<MessagePayload>,
    }
}

CMF Registration

registry.register_for_names::<CmfHook>(
    plugin.clone(),
    config.clone(),
    &[
        "cmf.tool_pre_invoke",
        "cmf.tool_post_invoke",
        "cmf.llm_input",
        "cmf.llm_output",
        "cmf.prompt_pre_fetch",
        "cmf.prompt_post_fetch",
        "cmf.resource_pre_fetch",
        "cmf.resource_post_fetch",
    ],
);

CMF Plugin Example

struct AplPolicy {
    config: PluginConfig,
    engine: PolicyEngine,
}

impl CmfHookHandler for AplPolicy {
    fn cmf_hook(
        &self,
        payload: MessagePayload,
        extensions: &FilteredExtensions,
        ctx: &PluginContext,
    ) -> HookResult<MessagePayload> {
        match payload.hook {
            MessageHookType::ToolPreInvoke => {
                if !extensions.has_role("hr") {
                    return HookResult::deny("missing hr role");
                }
                HookResult::allow()
            }
            MessageHookType::ToolPostInvoke => {
                let mut modified = payload;
                modified.message.redact_field("salary");

                let mut ext_updates = Extensions::default();
                ext_updates.security_labels_add("SALARY_REDACTED");

                HookResult::modified(modified, Some(ext_updates))
            }
            _ => HookResult::allow(),
        }
    }
}

Custom (Non-CMF) Hook Example

Hosts define domain-specific hooks with their own payload types:

pub struct RateLimitPayload {
    pub client_id: String,
    pub endpoint: String,
    pub request_count: u64,
    pub window_seconds: u64,
}

pub enum RateLimitResult {
    Allow,
    Throttle { retry_after_seconds: u64 },
    Block { reason: String },
}

define_hook! {
    RateLimit {
        payload: RateLimitPayload,
        result: RateLimitResult,
    }
}

impl RateLimitHandler for MyRateLimiter {
    fn rate_limit(
        &self,
        payload: RateLimitPayload,
        extensions: &FilteredExtensions,
        ctx: &PluginContext,
    ) -> RateLimitResult {
        if payload.request_count > 100 {
            RateLimitResult::Throttle { retry_after_seconds: 30 }
        } else {
            RateLimitResult::Allow
        }
    }
}

Python Integration

The typed hook system is internal to the Rust core. Python plugin authors see the same API as the current Python framework — @hook decorators, Plugin base class, payload/context/extensions parameters, block()/allow() helpers. The cpex-hosts::python adapter translates at the boundary.

What Python Plugin Authors See (unchanged)

class MyPlugin(Plugin):
    @hook("cmf.tool_pre_invoke", mode="sequential")
    async def evaluate(self, payload, context, extensions):
        if not extensions.has_role("hr"):
            return block("missing hr role")
        return allow()

The @hook decorator, separate extensions parameter, and result helpers are identical to the current framework. Plugin authors don't know the executor is Rust.

How the Bridge Works (cpex-hosts::python)

The Python adapter implements the Rust handler trait and translates at the boundary:

impl CmfHookHandler for PythonPluginAdapter {
    fn cmf_hook(
        &self,
        payload: MessagePayload,
        extensions: &FilteredExtensions,
        ctx: &PluginContext,
    ) -> HookResult<MessagePayload> {
        Python::with_gil(|py| {
            // Wrap Rust structs as PyO3 objects — NOT serialization,
            // just wrapping references so Python can access fields
            let py_payload = PyMessagePayload::from_rust(py, &payload);
            let py_ext = PyFilteredExtensions::from_rust(py, extensions);
            let py_ctx = PyPluginContext::from_rust(py, ctx);

            // Call the Python plugin's hook method
            let result = self.py_plugin.call_method1(
                py, "evaluate", (py_payload, py_ctx, py_ext)
            )?;

            // Convert Python result back to Rust
            HookResult::from_py(py, result, payload)
        })
    }
}

Python objects (PyMessagePayload, PyFilteredExtensions) are PyO3 wrappers around Rust types. Python reads .message, .views, .hook as normal attributes — PyO3 intercepts access and returns Python-compatible values. This is attribute-level conversion, not JSON serialization.

Four Ways to Define and Implement Hooks

Hooks can be defined in Rust or Python, and plugins can be written in either language. This gives four combinations:

Hook defined in	Plugin written in	Payload type	Serialization	Use case
Rust (define_hook!)	Rust	Typed struct	None	Performance-critical (APL, identity)
Rust (define_hook!)	Python	PyO3 wrapper around Rust struct	PyO3 attribute conversion	Rapid iteration on typed hooks (best of both worlds)
Python (register_hook_type)	Python	Python class (Pydantic)	None (stays in Python)	Domain-specific hooks, prototyping
Python (register_hook_type)	Rust	PyObject / dynamic extraction	PyO3 extraction	Unusual but supported

Rust-defined hook, Python plugin (row 2) gives plugin authors typed, validated payloads defined in Rust — with the ability to write the logic in Python:

# Payload (MessagePayload) is defined in Rust, exposed via PyO3
# Python gets typed attributes: payload.message, payload.views, payload.hook

class PiiRedactor(Plugin):
    @hook("cmf.tool_post_invoke", mode="transform")
    async def evaluate(self, payload, context, extensions):
        if "salary" in payload.message.get_text_content():
            if not extensions.has_role("hr"):
                payload.message.redact_field("salary")
                return modify(payload, extensions_update={"labels_add": ["SALARY_REDACTED"]})
        return allow()

Python-Defined Custom Hooks

Python can define entirely new hook types at runtime. The payload is a Python class — Rust doesn't know the fields at compile time but still handles all framework guarantees:

class DeploymentPayload(PluginPayload):
    service_name: str
    environment: str
    version: str
    rollback_available: bool

# Register with the Rust manager
manager.register_hook_type(
    name="deployment_pre_approve",
    payload_class=DeploymentPayload,
)

class DeploymentGate(Plugin):
    @hook("deployment_pre_approve", mode="sequential")
    async def check_deployment(self, payload, context, extensions):
        if payload.environment == "production" and not payload.rollback_available:
            return block("production deployments require rollback")
        return allow()

The Rust executor treats the payload as opaque (PyObject) but still enforces:

• 5-phase mode-based scheduling
• Priority ordering from trusted config
• Capability-gated extension filtering
• Timeout protection and error isolation

What Stays the Same for Python Plugin Authors

• @hook decorator with hook name and mode
• Plugin base class with initialize() / shutdown()
• payload, context, extensions as separate parameters
• block(), allow(), modify() result helpers
• extensions.has_role(), extensions.labels, etc.
• YAML config format for plugin declarations

What Changes Under the Hood (invisible to plugin authors)

• The executor is Rust, not Python
• Payload/extension objects are PyO3 wrappers when the hook is Rust-defined
• Scheduling (5-phase) happens in Rust
• Extension filtering and tier validation happen in Rust

Where Serialization Happens

Serialization is an adapter concern in cpex-hosts and cpex-ffi, never in cpex-core.

Plugin type	Payload	Extensions	Serialization?
Native Rust	Typed struct (direct)	&FilteredExtensions (direct)	None
Python (Rust-defined hook)	PyO3-wrapped Rust structs	PyO3-wrapped	PyO3 attribute conversion
Python (Python-defined hook)	Python class (opaque to Rust)	PyO3-wrapped	None (stays in Python)
WASM (cpex-hosts::wasm)	MessagePack in guest memory	MessagePack in guest memory	MessagePack at boundary
Go (cpex-ffi)	MessagePack across C ABI	MessagePack across C ABI	MessagePack at boundary

Registry

The registry stores type-erased handlers keyed by hook name. Multiple hook names can map to the same typed handler (the CMF pattern):

pub struct HookRegistry {
    handlers: HashMap<String, Vec<(PluginRef, Arc<dyn AnyHookHandler>)>>,
}

impl HookRegistry {
    /// Register a typed handler for a single hook name.
    pub fn register<H: HookType>(&mut self, handler: Arc<dyn Plugin>, config: PluginConfig) { ... }

    /// Register a typed handler for multiple hook names (CMF pattern).
    pub fn register_for_names<H: HookType>(&mut self, handler: Arc<dyn Plugin>, config: PluginConfig, names: &[&str]) { ... }
}

Multi-Hook Plugins

A single plugin can implement multiple hook type handlers:

impl CmfHookHandler for AuthPlugin {
    fn cmf_hook(&self, payload: MessagePayload, ext: &FilteredExtensions, ctx: &PluginContext) -> HookResult<MessagePayload> { ... }
}

impl RateLimitHandler for AuthPlugin {
    fn rate_limit(&self, payload: RateLimitPayload, ext: &FilteredExtensions, ctx: &PluginContext) -> RateLimitResult { ... }
}

registry.register_for_names::<CmfHook>(plugin.clone(), config.clone(), &["cmf.tool_pre_invoke"]);
registry.register::<RateLimit>(plugin.clone(), config.clone());