sessions/rust/crates/session_protocol/tests/envelope_parity.rs

//! Wave 2 envelope parity test (PR 13a — spec freeze gate).
//!
//! Wire-shape pin for the `v` / `channel` / `kind` / `body` envelope. Any
//! future change to those four field names breaks this fixture by design —
//! Wave 2 implementations (PR 13b channel supervisor, PR 16 PR-A worker
//! body) must round-trip through this exact NDJSON shape, so the freeze
//! lives here in tests rather than buried in implementation files.
//!
//! Internal serde behaviour is covered by `envelope::tests` inside the
//! crate. This integration test exists for the *cross-crate parity*
//! contract — it imports through the public `session_protocol` re-export
//! exactly as `local_bridge` / `session_helper` / `sessions_native` will.

use session_protocol::{CHANNEL_ENVELOPE_V1, Envelope, reference_dispatch};

#[test]
fn envelope_canonical_ndjson_shape_is_frozen() -> Result<(), serde_json::Error> {
    // The four-field shape every Wave 2 channel handler must accept. If you
    // need to extend the wire shape, bump CHANNEL_ENVELOPE_V1 and add a new
    // parity fixture below — do not edit this one.
    let canonical = serde_json::json!({
        "v": "sessions.channel.v1",
        "channel": "control",
        "kind": "echo",
        "body": {"hello": "world"},
    });
    let env: Envelope = serde_json::from_value(canonical.clone())?;
    assert_eq!(env.v, CHANNEL_ENVELOPE_V1);
    assert_eq!(env.channel, "control");
    assert_eq!(env.kind, "echo");
    assert_eq!(env.body, serde_json::json!({"hello": "world"}));

    let re_serialized = serde_json::to_value(&env)?;
    assert_eq!(re_serialized, canonical);
    Ok(())
}

#[test]
fn reference_dispatch_round_trips_control_echo() {
    let request = Envelope::new(
        "control",
        "echo",
        serde_json::json!({"id": "req-1", "payload": [1, 2, 3]}),
    );
    let response = reference_dispatch(&request);
    assert!(response.is_current_version());
    assert_eq!(response.channel, "control");
    assert_eq!(response.kind, "echo_response");
    assert_eq!(
        response.body,
        serde_json::json!({"id": "req-1", "payload": [1, 2, 3]}),
    );
}

#[test]
fn reference_dispatch_rejects_stale_version() {
    let request = Envelope {
        v: "sessions.channel.v0".to_string(),
        channel: "control".to_string(),
        kind: "echo".to_string(),
        body: serde_json::Value::Null,
    };
    let response = reference_dispatch(&request);
    assert_eq!(response.kind, "error");
    assert_eq!(response.body["code"], "envelope_version_mismatch");
    // The error envelope itself is *current* version — only the rejected
    // request held the stale `v`.
    assert!(response.is_current_version());
}

#[test]
fn unknown_channel_kind_yields_structured_error_envelope() {
    let request = Envelope::new("file", "tree/list", serde_json::Value::Null);
    let response = reference_dispatch(&request);
    assert_eq!(response.kind, "error");
    assert_eq!(response.body["code"], "channel_kind_unhandled");
    // PR 13b will replace this branch with a real `file` channel handler.
    assert_eq!(response.body["channel"], "file");
    assert_eq!(response.body["kind"], "tree/list");
}

#[test]
fn ndjson_round_trip_preserves_byte_for_byte_field_names() -> Result<(), serde_json::Error> {
    // Byte-level pin: serde-derived Serialize emits keys in struct order.
    // PR 16 (PR-A) relies on this when comparing recorded fixtures.
    let env = Envelope::new("control", "echo", serde_json::json!({"x": 1}));
    let line = serde_json::to_string(&env)?;
    assert_eq!(
        line,
        r#"{"v":"sessions.channel.v1","channel":"control","kind":"echo","body":{"x":1}}"#,
    );
    Ok(())
}