Module v1 

Wire schema version 1 (baseline).

Shared types between host (cc-lb-runtime-wasmtime) and guest (cc-lb-pdk-wasmtime) compiled in lockstep.

Wire types for the three hooks the wasmtime runtime ships: filter (Phase 1), shape (Phase 2), observe (Phase 2). Signer extension is intentionally not exposed across the plugin boundary — host-side built-in AnthropicKeySigner / AnthropicOAuthSigner handle credential signing in-process.

rkyv derives Archive + Serialize + Deserialize for every wire type. The host calls rkyv::access::<ArchivedFilterRequest, rkyv::rancor::Error> to get a zero-copy &ArchivedFilterRequest view straight out of guest linear memory; the guest mirrors that pattern in reverse for the response.

ABI invariants (review consensus)

• Every guest-allocated buffer is aligned to align_of::<Archived<T>>() for its root type. rkyv 0.8’s default relative pointers require this; the alignment is propagated through cc_lb_alloc(size, align).
• Arc/Rc MUST NOT appear in any wire type (rkyv 0.8 Issue #670 — ArchivedRc::verify can be bypassed for DST shared pointers).
• The wire schema is fingerprinted via BLAKE3 of cc_lb_schema_hash custom section content. Host and guest must agree byte-for-byte.

Borrowed-wire optimisation (RFC-0001 #9)

Host-to-guest request types (FilterRequest, ShapeRequest) come in two flavours that produce IDENTICAL archived bytes:

• Owned (FilterRequest, ShapeRequest, …) — owned Box<str> / Box<[u8]> fields. Used by the guest for rkyv::deserialize round-trips and for round-trip test fixtures.
• Borrowed ref (FilterRequestRef<'a>, ShapeRequestRef<'a>, …) — &'a str / &'a [u8] fields with #[rkyv(with = InlineAsBox)]. Used by the host in wire_to_host_wire_request so the request body (up to 100 MiB on /v1/files) is serialised IN PLACE from the request pipeline’s bytes::Bytes without any .to_vec() copy.

Both variants archive to the same ArchivedBox<ArchivedSlice<u8>> / ArchivedBox<ArchivedStr> byte layouts — verified by the wire round-trip tests in crates/cc-lb-plugin-wire/tests/borrowed_wire_roundtrip.rs. When either variant is written to guest memory, the guest reads it via rkyv::access::<ArchivedFilterRequest, _> — the archived type name is identical because the owned type is the sole Archive source of truth; the ref type carries #[rkyv(archived = ...)] to reuse the owned type’s archived form.

See docs/rfc/0001-plugin-runtime-vnext.md.

Structs

ArchivedClaim

An archived Claim

ArchivedClaimRef

An archived ClaimRef

ArchivedFilterRequest

An archived FilterRequest

ArchivedFilterRequestRef

An archived FilterRequestRef

ArchivedFilterResponse

An archived FilterResponse

ArchivedHeader

An archived Header

ArchivedHeaderRef

An archived HeaderRef

ArchivedPerCandidateReason

An archived PerCandidateReason

ArchivedPrincipal

An archived Principal

ArchivedPrincipalRef

An archived PrincipalRef

ArchivedQueryRef

An archived QueryRef

ArchivedShapeRequest

An archived ShapeRequest

ArchivedShapeRequestRef

An archived ShapeRequestRef

ArchivedShapeResponse

An archived ShapeResponse

ArchivedUpstreamCandidate

An archived UpstreamCandidate

ArchivedUpstreamCandidateRef

An archived UpstreamCandidateRef

Claim

One claim key/value pair — see Principal::claims. Named struct (not tuple) so that ClaimRef<'a> matches the archived byte layout without an extra Ref wrapper.

ClaimRef

One claim entry inside PrincipalRef. The tuple form used by the owned type does not have a straight borrowed equivalent, so we promote it to a named struct with two borrowed fields.

ClaimRefResolver

The resolver for an archived ClaimRef

ClaimResolver

The resolver for an archived Claim

FilterRequest

Filter hook input (owned form used by the guest).

FilterRequestRef

Borrowed mirror of FilterRequest used by the host encode path. Serialising this emits the same archived byte layout as FilterRequest so the guest reads it via rkyv::access::<ArchivedFilterRequest, _> unchanged.

FilterRequestRefResolver

The resolver for an archived FilterRequestRef

FilterRequestResolver

The resolver for an archived FilterRequest

FilterResponse

Filter hook output.

FilterResponseResolver

The resolver for an archived FilterResponse

Header

One header on the inbound request.

HeaderRef

Borrowed mirror of Header.

HeaderRefResolver

The resolver for an archived HeaderRef

HeaderResolver

The resolver for an archived Header

PerCandidateReason

Decision the plugin made for one candidate.

PerCandidateReasonResolver

The resolver for an archived PerCandidateReason

Principal

Principal context as seen by the filter plugin.

PrincipalRef

Borrowed mirror of Principal used by the host encode path. Every reference field carries #[rkyv(with = InlineAsBox)] so serialising this struct emits the same archived byte layout as Principal.

PrincipalRefResolver

The resolver for an archived PrincipalRef

PrincipalResolver

The resolver for an archived Principal

QueryRef

Borrowed wrapper for the optional query field. Necessary because Option<InlineAsBox<&'a str>> does not compose directly at the derive layer; a named struct pushes the #[rkyv(with = ...)] attribute onto the inner reference.

QueryRefResolver

The resolver for an archived QueryRef

ShapeRequest

Shape hook input (owned form).

ShapeRequestRef

Borrowed mirror of ShapeRequest used by the host encode path.

ShapeRequestRefResolver

The resolver for an archived ShapeRequestRef

ShapeRequestResolver

The resolver for an archived ShapeRequest

ShapeResponse

Shape hook output — the upstream-bound request the plugin produced.

ShapeResponseResolver

The resolver for an archived ShapeResponse

UpstreamCandidate

One upstream candidate the filter plugin can choose to keep or drop.

UpstreamCandidateRef

Borrowed mirror of UpstreamCandidate.

UpstreamCandidateRefResolver

The resolver for an archived UpstreamCandidateRef

UpstreamCandidateResolver

The resolver for an archived UpstreamCandidate

Enums

ArchivedObserveEvent

An archived ObserveEvent

ArchivedUpstream

An archived Upstream

ArchivedUpstreamRef

An archived UpstreamRef

ObserveEvent

Lifecycle event delivered to the observe hook. rkyv mirror of cc_lb_plugin_api::ObserveEvent.

ObserveEventResolver

The resolver for an archived ObserveEvent

Upstream

Upstream backend exposed to plugins. Mirrors cc_lb_plugin_api::Upstream (currently a single variant — extending the host enum requires extending this one in lockstep and bumping a wire schema tag).

UpstreamRef

Borrowed mirror of Upstream.

UpstreamRefResolver

The resolver for an archived UpstreamRef

UpstreamResolver

The resolver for an archived Upstream