cqrs_es_crypto_derive/

lib.rs

//! Proc-macro crate for `#[derive(PiiCodec)]`.
//!
//! Generates a `{Name}PiiCodec` struct and a [`PiiEventCodec`] implementation
//! from an annotated event enum.
//!
//! # Usage
//!
//! ```rust,ignore
//! use cqrs_es_crypto::PiiCodec;
//!
//! #[derive(PiiCodec)]
//! enum MyEvent {
//!     #[pii(event_type = "SensitiveEvent")]
//!     SensitiveEvent {
//!         #[pii(subject)]   subject_id: uuid::Uuid,
//!         #[pii(plaintext)] tag: String,
//!         #[pii(secret)]    secret: String,
//!     },
//!     PlainEvent { data: String },
//! }
//! // Generates: pub struct MyEventPiiCodec;
//! // + impl PiiEventCodec for MyEventPiiCodec { ... }
//! ```
//!
//! # Field types and redaction
//!
//! `#[pii(secret)]` fields are redacted to a per-type default when the
//! subject's DEK has been deleted. The defaults are:
//!
//! | Field type            | Redaction value | Notes                                       |
//! |-----------------------|-----------------|---------------------------------------------|
//! | `String`              | `"[redacted]"`  | fixed; not user-overridable                 |
//! | `Option<_>`           | `null`          | fixed; not user-overridable                 |
//! | `serde_json::Value`   | `{}`            | fixed; not user-overridable                 |
//! | `Vec<_>`              | `[]`            | fixed; not user-overridable                 |
//! | `chrono::NaiveDate`   | `"0000-01-01"`  | requires the `chrono` feature; overridable  |
//!
//! For types that don't have an inferred default (or to override one that
//! does support overrides) supply an explicit redaction value:
//!
//! ```rust,ignore
//! #[derive(PiiCodec)]
//! enum MyEvent {
//!     #[pii(event_type = "PersonCaptured")]
//!     PersonCaptured {
//!         #[pii(subject)]                       subject_id: uuid::Uuid,
//!         #[pii(secret)]                        name: String,
//!         // Default `"0000-01-01"` (requires the `chrono` feature):
//!         #[pii(secret)]                        dob: chrono::NaiveDate,
//!         // Custom override:
//!         #[pii(secret, redact = "1900-01-01")] dod: chrono::NaiveDate,
//!     },
//! }
//! ```

mod model;
mod parse;

use zyn::{
    ToTokens as _,
    proc_macro2::{Delimiter, Group, Ident, Literal, Span, TokenStream, TokenTree},
    syn::LitStr,
};

use crate::model::{PiiVariantModel, RedactValue};

// ── Helpers ───────────────────────────────────────────────────────────────────

/// Precomputed data for a single plaintext field: the JSON key as a string
/// literal and the local variable name that will hold the extracted value.
///
/// For a field named `person_ref`:
/// - `name_str` → `"person_ref"` (emitted as a token wherever the JSON key is needed)
/// - `binding`  → `person_ref_str` (the local `let` variable in the generated arm)
struct PlaintextFieldData {
    name_str: LitStr,
    binding: Ident,
}

fn plaintext_field_data(variant: &PiiVariantModel, span: Span) -> Vec<PlaintextFieldData> {
    variant
        .plaintext_fields()
        .map(|f| PlaintextFieldData {
            name_str: LitStr::new(&f.ident.to_string(), span),
            binding: zyn::format_ident!("{}_str", f.ident),
        })
        .collect()
}

/// Convert a [`model::RedactValue`] into the `proc_macro2` tokens that represent
/// the JSON literal to emit for that value (e.g. `"[redacted]"`, `null`, `{}`).
///
/// These tokens are inserted directly into the body of a `serde_json::json!`
/// invocation generated by [`redact_arm`].
fn redact_value_to_tokens(rv: &RedactValue, span: Span) -> TokenStream {
    match rv {
        RedactValue::Literal(s) => {
            std::iter::once(TokenTree::Literal(Literal::string(s))).collect()
        }
        RedactValue::Null => std::iter::once(TokenTree::Ident(Ident::new("null", span))).collect(),
        RedactValue::EmptyObject => std::iter::once(TokenTree::Group(Group::new(
            Delimiter::Brace,
            TokenStream::new(),
        )))
        .collect(),
        RedactValue::EmptyArray => std::iter::once(TokenTree::Group(Group::new(
            Delimiter::Bracket,
            TokenStream::new(),
        )))
        .collect(),
    }
}

/// Precomputed data for a single secret field: the JSON key as a string literal
/// and the token stream representing the redaction placeholder value.
struct SecretFieldData {
    name_str: LitStr,
    /// Tokens to emit in the redacted JSON (e.g. `"[redacted]"`, `null`, `{}`).
    redact_ts: TokenStream,
}

fn secret_field_data(variant: &PiiVariantModel, span: Span) -> Vec<SecretFieldData> {
    variant
        .secret_fields()
        .map(|f| SecretFieldData {
            name_str: LitStr::new(&f.ident.to_string(), span),
            redact_ts: redact_value_to_tokens(
                f.redact
                    .as_ref()
                    .expect("secret fields always have a RedactValue"),
                span,
            ),
        })
        .collect()
}

// ── Elements ──────────────────────────────────────────────────────────────────

/// Generates one match arm for the `classify` method.
///
/// For a variant with **multiple** secret fields the PII blob is a JSON object
/// keyed by field name.  For a variant with exactly **one** secret field the
/// blob is that field's value directly (no wrapping object).
///
/// Plaintext fields (e.g. `person_ref`) are extracted into local `*_str`
/// variables so the `move` closure in `build_encrypted_payload` can capture
/// them.
#[zyn::element]
fn classify_arm(variant: PiiVariantModel) -> zyn::TokenStream {
    let span = Span::call_site();

    let event_type = LitStr::new(&variant.event_type, span);
    let sentinel = LitStr::new(&variant.sentinel, span);
    let subject_str = LitStr::new(&variant.subject_field().ident.to_string(), span);

    let plaintext = plaintext_field_data(variant, span);

    // Secret field JSON keys — used for multi-secret bundling.
    let secret_strs: Vec<LitStr> = variant
        .secret_fields()
        .map(|f| LitStr::new(&f.ident.to_string(), span))
        .collect();

    let is_single = variant.is_single_secret();

    // For the single-secret case: the one secret field's JSON key.
    let single_secret_str = is_single.then(|| {
        LitStr::new(
            &variant.secret_fields().next().unwrap().ident.to_string(),
            span,
        )
    });

    zyn::zyn! {
        {{ event_type }} => {
            let __key = {{ event_type }};
            let __subject_id_str = event.payload[__key][{{ subject_str }}]
                .as_str()?.to_string();
            let __subject_id = ::uuid::Uuid::parse_str(&__subject_id_str).ok()?;

            // Extract each plaintext field into a named local variable so it
            // can be moved into the build_encrypted_payload closure below.
            // Clone the JSON value as-is so non-string plaintext fields
            // (numbers, nulls, bools) survive the round-trip; coercing via
            // `as_str().unwrap_or("")` would corrupt them to the empty string.
            @for (pt in plaintext.iter()) {
                let {{ pt.binding }} = event.payload[__key][{{ pt.name_str }}].clone();
            }

            // Build the plaintext PII blob.
            // Single secret → use the field value directly.
            // Multiple secrets → bundle into a JSON object keyed by field name.
            @if (is_single) {
                let __plaintext_pii =
                    event.payload[__key][{{ single_secret_str.as_ref().unwrap() }}].clone();
            } @else {
                let __inner = event.payload[__key].as_object()?;
                let __plaintext_pii = ::serde_json::json!({
                    @for (s in secret_strs.iter()) {
                        {{ s }}: __inner.get({{ s }})
                            .cloned()
                            .unwrap_or(::serde_json::Value::Null),
                    }
                });
            }

            ::core::option::Option::Some(::cqrs_es_crypto::PiiFields {
                subject_id: __subject_id,
                plaintext_pii: __plaintext_pii,
                build_encrypted_payload: ::std::boxed::Box::new(move |__sentinel| {
                    ::serde_json::json!({
                        {{ event_type }}: {
                            @for (pt in plaintext.iter()) {
                                {{ pt.name_str }}: {{ pt.binding }},
                            }
                            {{ subject_str }}: __subject_id_str,
                            {{ sentinel }}: __sentinel.ciphertext_b64,
                            "nonce": __sentinel.nonce_b64,
                        }
                    })
                }),
            })
        }
    }
}

/// Generates one match arm for the `extract_encrypted` method.
///
/// Returns `None` (via `?`) if:
/// - the sentinel field is absent — this is a legacy plaintext event and must
///   be passed through unchanged.
/// - any field is missing or malformed.
#[zyn::element]
fn extract_arm(variant: PiiVariantModel) -> zyn::TokenStream {
    let span = Span::call_site();

    let event_type = LitStr::new(&variant.event_type, span);
    let sentinel = LitStr::new(&variant.sentinel, span);
    let subject_str = LitStr::new(&variant.subject_field().ident.to_string(), span);

    zyn::zyn! {
        {{ event_type }} => {
            let __key = {{ event_type }};
            // No sentinel → legacy plaintext event; pass through unchanged.
            event.payload[__key].get({{ sentinel }})?;
            let __subject_id = ::uuid::Uuid::parse_str(
                event.payload[__key][{{ subject_str }}].as_str()?
            ).ok()?;
            let __ciphertext = <::base64::engine::general_purpose::GeneralPurpose
                as ::base64::Engine>::decode(
                    &::base64::engine::general_purpose::STANDARD,
                    event.payload[__key][{{ sentinel }}].as_str()?,
                ).ok()?;
            let __nonce = <::base64::engine::general_purpose::GeneralPurpose
                as ::base64::Engine>::decode(
                    &::base64::engine::general_purpose::STANDARD,
                    event.payload[__key]["nonce"].as_str()?,
                ).ok()?;
            ::core::option::Option::Some(::cqrs_es_crypto::EncryptedPiiExtract {
                subject_id: __subject_id,
                ciphertext: __ciphertext,
                nonce: __nonce,
            })
        }
    }
}

/// Generates one match arm for the `reconstruct` method.
///
/// Reads plaintext fields (including the subject field) from the stored
/// encrypted-form event, then merges them with the decrypted secret fields
/// from `plaintext_pii` to produce a fully-reconstructed event payload.
///
/// - Multi-secret variants: each secret field is accessed as
///   `plaintext_pii["field_name"]`.
/// - Single-secret variants: `plaintext_pii` is used directly as the field
///   value (it was never wrapped in an object during encryption).
#[zyn::element]
fn reconstruct_arm(variant: PiiVariantModel) -> zyn::TokenStream {
    let span = Span::call_site();

    let event_type = LitStr::new(&variant.event_type, span);
    let subject_str = LitStr::new(&variant.subject_field().ident.to_string(), span);
    let plaintext = plaintext_field_data(variant, span);

    let secret_strs: Vec<LitStr> = variant
        .secret_fields()
        .map(|f| LitStr::new(&f.ident.to_string(), span))
        .collect();

    let is_single = variant.is_single_secret();

    let single_secret_str = is_single.then(|| {
        LitStr::new(
            &variant.secret_fields().next().unwrap().ident.to_string(),
            span,
        )
    });

    zyn::zyn! {
        {{ event_type }} => {
            let __key = {{ event_type }};
            @for (pt in plaintext.iter()) {
                let {{ pt.binding }} = event.payload[__key][{{ pt.name_str }}].clone();
            }
            let __subject_id_val = event.payload[__key][{{ subject_str }}].clone();
            ::core::result::Result::Ok(::serde_json::json!({
                {{ event_type }}: {
                    @for (pt in plaintext.iter()) {
                        {{ pt.name_str }}: {{ pt.binding }},
                    }
                    {{ subject_str }}: __subject_id_val,
                    @if (is_single) {
                        {{ single_secret_str.as_ref().unwrap() }}: plaintext_pii,
                    } @else {
                        @for (s in secret_strs.iter()) {
                            {{ s }}: plaintext_pii[{{ s }}],
                        }
                    }
                }
            }))
        }
    }
}

/// Generates one match arm for the `redact` method.
///
/// Reads plaintext fields (including the subject field) from the stored
/// encrypted-form event, then emits static redaction placeholder values for
/// every secret field. The placeholders are derived from each field's
/// [`model::RedactValue`]:
///
/// - `String` → `"[redacted]"`
/// - `Option<_>` → `null`
/// - `Value` / `serde_json::Value` → `{}`
/// - `Vec<_>` → `[]`
#[zyn::element]
fn redact_arm(variant: PiiVariantModel) -> zyn::TokenStream {
    let span = Span::call_site();

    let event_type = LitStr::new(&variant.event_type, span);
    let subject_str = LitStr::new(&variant.subject_field().ident.to_string(), span);
    let plaintext = plaintext_field_data(variant, span);
    let secrets = secret_field_data(variant, span);

    zyn::zyn! {
        {{ event_type }} => {
            let __key = {{ event_type }};
            @for (pt in plaintext.iter()) {
                let {{ pt.binding }} = event.payload[__key][{{ pt.name_str }}].clone();
            }
            let __subject_id_val = event.payload[__key][{{ subject_str }}].clone();
            ::core::result::Result::Ok(::serde_json::json!({
                {{ event_type }}: {
                    @for (pt in plaintext.iter()) {
                        {{ pt.name_str }}: {{ pt.binding }},
                    }
                    {{ subject_str }}: __subject_id_val,
                    @for (sf in secrets.iter()) {
                        {{ sf.name_str }}: {{ sf.redact_ts }},
                    }
                }
            }))
        }
    }
}

// ── Derive entry point ────────────────────────────────────────────────────────

/// Derives a [`PiiEventCodec`](::cqrs_es_crypto::PiiEventCodec) implementation
/// from an annotated event enum.
///
/// See the [crate-level documentation](self) for the annotation syntax.
#[zyn::derive("PiiCodec", attributes(pii))]
fn pii_codec(
    #[zyn(input)] ident: zyn::Extract<Ident>,
    #[zyn(input)] variants: zyn::Variants,
) -> zyn::TokenStream {
    let codec_ident = zyn::format_ident!("{}PiiCodec", *ident);

    // Parse and validate `#[pii(...)]` annotations.  Any error is surfaced as
    // a `compile_error!` at the call site with an accurate source span.
    let pii_variants: Vec<PiiVariantModel> = match parse::parse_pii_variants(&variants) {
        Ok(v) => v,
        Err(e) => return e.into_compile_error().into(),
    };

    zyn::zyn! {
        /// [`PiiEventCodec`](::cqrs_es_crypto::PiiEventCodec) implementation
        /// generated by `#[derive(PiiCodec)]`.
        pub struct {{ codec_ident }};

        impl ::cqrs_es_crypto::PiiEventCodec for {{ codec_ident }} {
            fn classify(
                &self,
                event: &::cqrs_es::persist::SerializedEvent,
            ) -> ::core::option::Option<::cqrs_es_crypto::PiiFields> {
                match event.event_type.as_str() {
                    @for (v in pii_variants.iter()) {
                        @classify_arm(variant = v.clone())
                    }
                    _ => ::core::option::Option::None,
                }
            }

            fn extract_encrypted(
                &self,
                event: &::cqrs_es::persist::SerializedEvent,
            ) -> ::core::option::Option<::cqrs_es_crypto::EncryptedPiiExtract> {
                match event.event_type.as_str() {
                    @for (v in pii_variants.iter()) {
                        @extract_arm(variant = v.clone())
                    }
                    _ => ::core::option::Option::None,
                }
            }

            fn reconstruct(
                &self,
                event: &::cqrs_es::persist::SerializedEvent,
                plaintext_pii: &::serde_json::Value,
            ) -> ::core::result::Result<
                ::serde_json::Value,
                ::std::boxed::Box<dyn ::std::error::Error + Send + Sync>,
            > {
                match event.event_type.as_str() {
                    @for (v in pii_variants.iter()) {
                        @reconstruct_arm(variant = v.clone())
                    }
                    _ => ::core::result::Result::Ok(event.payload.clone()),
                }
            }

            fn redact(
                &self,
                event: &::cqrs_es::persist::SerializedEvent,
            ) -> ::core::result::Result<
                ::serde_json::Value,
                ::std::boxed::Box<dyn ::std::error::Error + Send + Sync>,
            > {
                match event.event_type.as_str() {
                    @for (v in pii_variants.iter()) {
                        @redact_arm(variant = v.clone())
                    }
                    _ => ::core::result::Result::Ok(event.payload.clone()),
                }
            }
        }
    }
    .to_token_stream()
}

// ── Tests ─────────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    use crate::model::{PiiFieldModel, PiiFieldRole, PiiVariantModel, RedactValue};

    use super::*;

    // ── Helpers ───────────────────────────────────────────────────────────────

    fn dummy_input() -> zyn::Input {
        zyn::parse!("enum TestEvent {}" => zyn::syn::DeriveInput)
            .unwrap()
            .into()
    }

    fn field(name: &str, role: PiiFieldRole) -> PiiFieldModel {
        PiiFieldModel {
            ident: zyn::format_ident!("{}", name),
            role,
            redact: None,
        }
    }

    fn str_secret_field(name: &str) -> PiiFieldModel {
        PiiFieldModel {
            ident: zyn::format_ident!("{}", name),
            role: PiiFieldRole::Secret,
            redact: Some(RedactValue::Literal("[redacted]".to_string())),
        }
    }

    fn value_secret_field(name: &str) -> PiiFieldModel {
        PiiFieldModel {
            ident: zyn::format_ident!("{}", name),
            role: PiiFieldRole::Secret,
            redact: Some(RedactValue::EmptyObject),
        }
    }

    fn vec_secret_field(name: &str) -> PiiFieldModel {
        PiiFieldModel {
            ident: zyn::format_ident!("{}", name),
            role: PiiFieldRole::Secret,
            redact: Some(RedactValue::EmptyArray),
        }
    }

    /// Multi-secret variant: `person_ref` (plaintext), `subject_id` (subject),
    /// name/email/phone (secret) — mirrors `PersonCaptured`.
    fn multi_secret_variant() -> PiiVariantModel {
        PiiVariantModel {
            event_type: "PersonCaptured".to_string(),
            sentinel: "encrypted_pii".to_string(),
            fields: vec![
                field("person_ref", PiiFieldRole::Plaintext),
                field("subject_id", PiiFieldRole::Subject),
                str_secret_field("name"),
                str_secret_field("email"),
                str_secret_field("phone"),
            ],
        }
    }

    /// Single-secret variant: `person_ref` (plaintext), `subject_id` (subject),
    /// `data` (secret, `Value` type) with a custom sentinel — mirrors `PersonDetailsUpdated`.
    fn single_secret_variant() -> PiiVariantModel {
        PiiVariantModel {
            event_type: "PersonDetailsUpdated".to_string(),
            sentinel: "encrypted_data".to_string(),
            fields: vec![
                field("person_ref", PiiFieldRole::Plaintext),
                field("subject_id", PiiFieldRole::Subject),
                value_secret_field("data"),
            ],
        }
    }

    /// Single-secret variant whose secret field is a `Vec<_>` type. Exercises
    /// the `EmptyArray` redaction path emitted by `redact_arm`.
    fn single_secret_vec_variant() -> PiiVariantModel {
        PiiVariantModel {
            event_type: "PhonesCaptured".to_string(),
            sentinel: "encrypted_pii".to_string(),
            fields: vec![
                field("person_ref", PiiFieldRole::Plaintext),
                field("subject_id", PiiFieldRole::Subject),
                vec_secret_field("phone_numbers"),
            ],
        }
    }

    /// Multi-secret variant whose subject field is named `user_id` instead of
    /// the conventional `subject_id`. Exercises the contract that
    /// `#[pii(subject)]` accepts any field name and that name flows into
    /// every JSON read/write site in the generated code.
    fn multi_secret_variant_with_custom_subject() -> PiiVariantModel {
        PiiVariantModel {
            event_type: "PersonCaptured".to_string(),
            sentinel: "encrypted_pii".to_string(),
            fields: vec![
                field("person_ref", PiiFieldRole::Plaintext),
                field("user_id", PiiFieldRole::Subject),
                str_secret_field("name"),
                str_secret_field("email"),
            ],
        }
    }

    // ── classify_arm ──────────────────────────────────────────────────────────

    #[test]
    fn classify_arm_emits_event_type_match_pattern() {
        let input = dummy_input();
        let output = zyn::zyn!(@classify_arm(variant = multi_secret_variant()));
        zyn::assert_tokens_contain!(output, "\"PersonCaptured\"");
    }

    #[test]
    fn classify_arm_extracts_subject_id_str() {
        let input = dummy_input();
        let output = zyn::zyn!(@classify_arm(variant = multi_secret_variant()));
        zyn::assert_tokens_contain!(output, "__subject_id_str");
        zyn::assert_tokens_contain!(output, "\"subject_id\"");
    }

    #[test]
    fn classify_arm_extracts_plaintext_fields_into_bindings() {
        let input = dummy_input();
        let output = zyn::zyn!(@classify_arm(variant = multi_secret_variant()));
        // plaintext field "person_ref" → binding "person_ref_str"
        zyn::assert_tokens_contain!(output, "person_ref_str");
        zyn::assert_tokens_contain!(output, "\"person_ref\"");
    }

    #[test]
    fn classify_arm_clones_plaintext_fields_to_preserve_json_type() {
        // Plaintext extraction must clone the JSON value to preserve its
        // type. The previous implementation coerced through
        // `as_str().unwrap_or("")`, silently corrupting non-string plaintext
        // fields (numbers, nulls, bools) to the empty string and breaking
        // deserialization on read-back.
        //
        // The single-secret variant is used because its generated body has
        // no other call site for `unwrap_or` — the multi-secret bundling
        // path legitimately uses `unwrap_or(Value::Null)`.
        let input = dummy_input();
        let output = zyn::zyn!(@classify_arm(variant = single_secret_variant()));
        let raw = output.to_string();
        assert!(
            !raw.contains("unwrap_or"),
            "classify_arm must not coerce plaintext fields via `unwrap_or`, got: {raw}"
        );
    }

    #[test]
    fn classify_arm_multi_secret_bundles_into_object() {
        let input = dummy_input();
        let output = zyn::zyn!(@classify_arm(variant = multi_secret_variant()));
        // multi-secret path uses __inner for the object bundling
        zyn::assert_tokens_contain!(output, "__inner");
        zyn::assert_tokens_contain!(output, "\"name\"");
        zyn::assert_tokens_contain!(output, "\"email\"");
        zyn::assert_tokens_contain!(output, "\"phone\"");
    }

    #[test]
    fn classify_arm_single_secret_uses_direct_value() {
        let input = dummy_input();
        let output = zyn::zyn!(@classify_arm(variant = single_secret_variant()));
        // single-secret path: no __inner bundling
        let raw = output.to_string();
        assert!(
            !raw.contains("__inner"),
            "single-secret classify arm must not bundle into a JSON object"
        );
        // direct field access for the single secret
        zyn::assert_tokens_contain!(output, "\"data\"");
    }

    #[test]
    fn classify_arm_uses_default_sentinel_in_closure() {
        let input = dummy_input();
        let output = zyn::zyn!(@classify_arm(variant = multi_secret_variant()));
        zyn::assert_tokens_contain!(output, "\"encrypted_pii\"");
    }

    #[test]
    fn classify_arm_uses_custom_sentinel_in_closure() {
        let input = dummy_input();
        let output = zyn::zyn!(@classify_arm(variant = single_secret_variant()));
        zyn::assert_tokens_contain!(output, "\"encrypted_data\"");
    }

    #[test]
    fn classify_arm_closure_captures_plaintext_bindings() {
        let input = dummy_input();
        let output = zyn::zyn!(@classify_arm(variant = multi_secret_variant()));
        // The closure body must reference person_ref_str and __subject_id_str
        zyn::assert_tokens_contain!(output, "build_encrypted_payload");
        zyn::assert_tokens_contain!(output, "__subject_id_str");
    }

    #[test]
    fn classify_arm_emits_pii_fields_struct() {
        let input = dummy_input();
        let output = zyn::zyn!(@classify_arm(variant = multi_secret_variant()));
        zyn::assert_tokens_contain!(output, "PiiFields");
        zyn::assert_tokens_contain!(output, "subject_id");
        zyn::assert_tokens_contain!(output, "plaintext_pii");
    }

    #[test]
    fn classify_arm_uses_custom_subject_name_in_both_read_and_write() {
        // Regression guard for the bug where the encrypted-payload write path
        // hardcoded `"subject_id"` instead of using the variant's actual
        // subject field name. The read path already used `subject_str`; this
        // test asserts both sides of `classify_arm` agree.
        let input = dummy_input();
        let output = zyn::zyn!(
            @classify_arm(variant = multi_secret_variant_with_custom_subject())
        );
        let raw = output.to_string();

        // The actual subject field name must appear in the generated tokens
        // (it is used both to read the value and as the JSON key in the
        // build_encrypted_payload closure).
        assert!(
            raw.contains("\"user_id\""),
            "classify_arm must use the variant's actual subject field name as the JSON key, got: {raw}"
        );

        // The hardcoded literal `"subject_id"` must NOT appear when the
        // variant's subject field is named something else.
        assert!(
            !raw.contains("\"subject_id\""),
            "classify_arm must not emit hardcoded \"subject_id\" when the variant uses a different subject name, got: {raw}"
        );
    }

    // ── extract_arm ───────────────────────────────────────────────────────────

    #[test]
    fn extract_arm_emits_event_type_match_pattern() {
        let input = dummy_input();
        let output = zyn::zyn!(@extract_arm(variant = multi_secret_variant()));
        zyn::assert_tokens_contain!(output, "\"PersonCaptured\"");
    }

    #[test]
    fn extract_arm_checks_sentinel_presence() {
        let input = dummy_input();
        let output = zyn::zyn!(@extract_arm(variant = multi_secret_variant()));
        // sentinel presence check via .get("encrypted_pii")?
        zyn::assert_tokens_contain!(output, "\"encrypted_pii\"");
        zyn::assert_tokens_contain!(output, "get");
    }

    #[test]
    fn extract_arm_uses_custom_sentinel() {
        let input = dummy_input();
        let output = zyn::zyn!(@extract_arm(variant = single_secret_variant()));
        zyn::assert_tokens_contain!(output, "\"encrypted_data\"");
    }

    #[test]
    fn extract_arm_extracts_subject_id() {
        let input = dummy_input();
        let output = zyn::zyn!(@extract_arm(variant = multi_secret_variant()));
        zyn::assert_tokens_contain!(output, "__subject_id");
        zyn::assert_tokens_contain!(output, "\"subject_id\"");
    }

    #[test]
    fn extract_arm_base64_decodes_ciphertext_and_nonce() {
        let input = dummy_input();
        let output = zyn::zyn!(@extract_arm(variant = multi_secret_variant()));
        zyn::assert_tokens_contain!(output, "STANDARD");
        zyn::assert_tokens_contain!(output, "__ciphertext");
        zyn::assert_tokens_contain!(output, "__nonce");
        zyn::assert_tokens_contain!(output, "\"nonce\"");
    }

    #[test]
    fn extract_arm_emits_encrypted_pii_extract_struct() {
        let input = dummy_input();
        let output = zyn::zyn!(@extract_arm(variant = multi_secret_variant()));
        zyn::assert_tokens_contain!(output, "EncryptedPiiExtract");
        zyn::assert_tokens_contain!(output, "ciphertext");
        zyn::assert_tokens_contain!(output, "nonce");
    }

    // ── reconstruct_arm ───────────────────────────────────────────────────────

    #[test]
    fn reconstruct_arm_emits_event_type_match_pattern() {
        let input = dummy_input();
        let output = zyn::zyn!(@reconstruct_arm(variant = multi_secret_variant()));
        zyn::assert_tokens_contain!(output, "\"PersonCaptured\"");
    }

    #[test]
    fn reconstruct_arm_contains_subject_field_name_and_binding() {
        let input = dummy_input();
        let output = zyn::zyn!(@reconstruct_arm(variant = multi_secret_variant()));
        zyn::assert_tokens_contain!(output, "\"subject_id\"");
        zyn::assert_tokens_contain!(output, "__subject_id_val");
    }

    #[test]
    fn reconstruct_arm_contains_plaintext_binding() {
        let input = dummy_input();
        let output = zyn::zyn!(@reconstruct_arm(variant = multi_secret_variant()));
        zyn::assert_tokens_contain!(output, "person_ref_str");
        zyn::assert_tokens_contain!(output, "\"person_ref\"");
    }

    #[test]
    fn reconstruct_arm_multi_secret_contains_indexed_plaintext_pii() {
        let input = dummy_input();
        let output = zyn::zyn!(@reconstruct_arm(variant = multi_secret_variant()));
        // multi-secret: references plaintext_pii and each secret field name
        zyn::assert_tokens_contain!(output, "plaintext_pii");
        zyn::assert_tokens_contain!(output, "\"name\"");
        zyn::assert_tokens_contain!(output, "\"email\"");
        zyn::assert_tokens_contain!(output, "\"phone\"");
    }

    #[test]
    fn reconstruct_arm_single_secret_uses_plaintext_pii_directly() {
        let input = dummy_input();
        let output = zyn::zyn!(@reconstruct_arm(variant = single_secret_variant()));
        // single-secret: plaintext_pii used directly, not indexed
        let raw = output.to_string();
        assert!(
            raw.contains("plaintext_pii"),
            "should reference plaintext_pii, got: {raw}"
        );
        assert!(
            !raw.contains("plaintext_pii [") && !raw.contains("plaintext_pii["),
            "single-secret reconstruct must not index into plaintext_pii, got: {raw}"
        );
        zyn::assert_tokens_contain!(output, "\"data\"");
    }

    #[test]
    fn reconstruct_arm_single_secret_emits_event_type() {
        let input = dummy_input();
        let output = zyn::zyn!(@reconstruct_arm(variant = single_secret_variant()));
        zyn::assert_tokens_contain!(output, "\"PersonDetailsUpdated\"");
    }

    // ── redact_arm ────────────────────────────────────────────────────────────

    #[test]
    fn redact_arm_emits_event_type_match_pattern() {
        let input = dummy_input();
        let output = zyn::zyn!(@redact_arm(variant = multi_secret_variant()));
        zyn::assert_tokens_contain!(output, "\"PersonCaptured\"");
    }

    #[test]
    fn redact_arm_contains_subject_field_and_plaintext_binding() {
        let input = dummy_input();
        let output = zyn::zyn!(@redact_arm(variant = multi_secret_variant()));
        zyn::assert_tokens_contain!(output, "__subject_id_val");
        zyn::assert_tokens_contain!(output, "person_ref_str");
    }

    #[test]
    fn redact_arm_multi_secret_emits_redacted_literal_for_string_fields() {
        let input = dummy_input();
        let output = zyn::zyn!(@redact_arm(variant = multi_secret_variant()));
        // String fields → "[redacted]"
        zyn::assert_tokens_contain!(output, "\"[redacted]\"");
        zyn::assert_tokens_contain!(output, "\"name\"");
        zyn::assert_tokens_contain!(output, "\"email\"");
        zyn::assert_tokens_contain!(output, "\"phone\"");
    }

    #[test]
    fn redact_arm_single_secret_emits_empty_object_for_value_field() {
        let input = dummy_input();
        let output = zyn::zyn!(@redact_arm(variant = single_secret_variant()));
        // Value field → {}
        let raw = output.to_string();
        assert!(
            raw.contains("{ }") || raw.contains("{}"),
            "single-secret redact arm should contain empty object `{{}}`, got: {raw}"
        );
        zyn::assert_tokens_contain!(output, "\"data\"");
    }

    #[test]
    fn redact_arm_single_secret_emits_event_type() {
        let input = dummy_input();
        let output = zyn::zyn!(@redact_arm(variant = single_secret_variant()));
        zyn::assert_tokens_contain!(output, "\"PersonDetailsUpdated\"");
    }

    #[test]
    fn redact_arm_single_secret_emits_empty_array_for_vec_field() {
        // `Vec<_>` field → `[]` in the redacted JSON. The serde_json::json!
        // macro accepts `[]` directly as an empty array value, just as it
        // accepts `{}` for an empty object.
        let input = dummy_input();
        let output = zyn::zyn!(@redact_arm(variant = single_secret_vec_variant()));
        let raw = output.to_string();
        assert!(
            raw.contains("[ ]") || raw.contains("[]"),
            "single-secret Vec redact arm should contain empty array `[]`, got: {raw}"
        );
        zyn::assert_tokens_contain!(output, "\"phone_numbers\"");
    }
}