contextgraph-conformance 2.0.0

//! Reference-serialized wire vectors: proof that the schema, the reference
//! types, and the examples describe **one** wire (issue #54).
//!
//! Until now, schema validation only ever ran over *hand-authored* transcripts
//! (`schema/validate-examples.py` over `examples/`). Nothing validated what the
//! reference serializer actually emits. That gap hid a whole class of bug —
//! a field listed as `required` in the schema but omitted by
//! `skip_serializing_if` in the Rust type, which makes a legitimate value
//! un-representable in conformant JSON. ADR 0006 hit it on `ContextFrame`
//! (`provenance`/`relations`); the same defect was still live on `ContextQuery`
//! (`kinds`/`anchors`), where it made the *unfiltered* query — the single most
//! common query there is, and the one this very suite's [`sample_query`] sends
//! — fail validation.
//!
//! The fix is structural, not another one-off patch:
//!
//! 1. This test constructs a reference value for **every** envelope variant, in
//!    both its **minimal** form (empty vecs, `None` options — where omission
//!    bugs live) and a **maximal** form (every optional field populated).
//! 2. It serializes them to `schema/reference-vectors.ndjson`, committed to the
//!    repo, and fails on any drift (regenerate with `REGENERATE_VECTORS=1`).
//! 3. `schema/validate-examples.py` validates every line of that file against
//!    the JSON Schema in CI — real schema validation, so `type`, `pattern`, and
//!    `allOf` are covered, not merely required-keys.
//!
//! So the vectors are generated by Rust and checked by the schema, and the two
//! halves cannot drift apart without a red build. The file doubles as an
//! attested vector set downstream implementations can diff against (issue #52):
//! [`vectors_are_conformant`] asserts every frame in it satisfies the frame
//! contract (B3 costs, F5 digests, representation invariants), so a vector is
//! never merely well-formed — it is *conformant*.

use std::fs;
use std::path::PathBuf;

use contextgraph_conformance::sample_query;
use contextgraph_host::{Envelope, decode_line};
use contextgraph_types::{
    ALGORITHM_ED25519, Capabilities, ContentFidelity, ContentRef, ContextFrame, ContextQuery,
    ContextQueryResult, DataFlow, EgressScope, ErrorCode, FrameAttestation, FrameEmbedding,
    FrameId, FrameKind, FrameVerdict, InclusionProof, InclusionStep, InlineContentRequirement,
    PROTOCOL_VERSION, Provenance, ProvenanceAttestation, ProviderInfo, QueryCapability, Relation,
    Representation, Transform, Verdict, VerifyRequest, VerifyResponse, budget_tokens,
};

/// Regenerate with: `REGENERATE_VECTORS=1 cargo test -p contextgraph-conformance --test reference_vectors`
const REGENERATE_ENV: &str = "REGENERATE_VECTORS";
const VECTOR_FILE: &str = "schema/reference-vectors.ndjson";

/// A digest of the empty string — a real, well-formed `sha256:<64 lowercase
/// hex>` (SPEC.md §6.2 F5), so the vectors carry grammar-valid digests rather
/// than the `sha256:abc` placeholder the repo used to ship.
const DIGEST_A: &str = "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
const DIGEST_B: &str = "sha256:5891b5b522d5df086d0ff0b110fbd9d21bb4fc7163af34d08286a2e846f6be03";
const DIGEST_C: &str = "sha256:6b86b273ff34fce19d6b804eff5a3f5747ada4eaa22f1d49c01e52ddb7875b4b";

/// The provider that serves and signs the attested vector.
const ATTESTING_PROVIDER: &str = "repo-indexer";

/// The `frames/attested` vector's root, commitments, and signatures
/// (`SPEC.md` §6.5).
///
/// Written out rather than computed, for two reasons. The generator has to
/// build the same bytes whether or not `contextgraph-types`' `attestation`
/// feature is on, or the committed vector file would depend on a feature flag.
/// And a literal is a *fixture*: recomputing these here would make the vector
/// agree with whatever the code currently does, which is exactly the property a
/// reference vector must not have.
///
/// They are not taken on trust either. `tests/attestation_wire.rs` recomputes
/// every one of them from the frames in this file and verifies both signatures
/// against the published example key, so editing an attested frame here without
/// re-signing it turns that suite red.
///
/// Leaf order is canonical [`FrameId`] order (§6.3), which puts
/// `frame:minimal` before `frame:policy:retry` — not the order the frames are
/// carried in.
mod attested {
    /// The §6.5.3 Merkle root over both frames' commitments.
    pub const ROOT: &str =
        "sha256:e7c84f0a6b2a7f7a6f14b12baa276af1d9347d82561fa1a797b47a7334660b4f";
    /// The detached signature over [`ROOT`].
    pub const ROOT_SIGNATURE: &str = "78439a36f599aeecaa4e36c653b647ec1c02395a4563dfe89efbeff375f21a8ca58de0b7ce6779f3cc93f445fb18a91f6ef8ad0ca651853a17056b3da4633602";
    /// The sibling leaf 0's proof climbs past — `maximal_frame`'s leaf hash.
    pub const MINIMAL_SIBLING: &str =
        "sha256:de4b8191386772610af0fcdb0c9908d38ae1feb5dc65aa0098f82bc18ebfa56e";
    /// Leaf 1: `maximal_frame`'s §6.5.2 commitment.
    pub const MAXIMAL_COMMITMENT: &str =
        "sha256:78df51a8d632df287957f71a792aca4628542e9e2ef8ef677e1dea2b67e7c499";
    /// The detached signature over [`MAXIMAL_COMMITMENT`].
    pub const MAXIMAL_SIGNATURE: &str = "1d9bd851829a0c6c3ce5eb4933a1852db7ca09034f092ebd2937c111d48e0f992a28882a6c22b1c8beea92073914e5ffe141b820f2a153bdbb0134ed305c0a09";
    /// The sibling leaf 1's proof climbs past — `minimal_frame`'s leaf hash.
    pub const MAXIMAL_SIBLING: &str =
        "sha256:6b1d8bc0f9f73a6ab9e84ccfaf35af23e83aa32441c75450783c699f9d8b2eae";
    /// When the example provider issued them.
    pub const ISSUED_AT: &str = "2026-08-29T12:00:00Z";
    /// The signing key's id. Rotation mints a new id; it never reuses one.
    pub const KEY_ID: &str = "repo-indexer-2026-08";
}

/// One attestation of the `frames/attested` vector, in the shape a provider
/// assembles after signing a commitment with its own backend.
fn attestation(signed_commitment: &str, signature: &str) -> ProvenanceAttestation {
    ProvenanceAttestation::new(
        signed_commitment,
        attested::KEY_ID,
        ALGORITHM_ED25519,
        ATTESTING_PROVIDER,
        signature,
        attested::ISSUED_AT,
    )
}

fn repo_root() -> PathBuf {
    PathBuf::from(env!("CARGO_MANIFEST_DIR"))
        .parent()
        .expect("crate dir has a parent")
        .to_path_buf()
}

/// A `full` frame with every optional field populated — the maximal shape.
fn maximal_frame() -> ContextFrame {
    let content = "Retry with exponential backoff, at most 3 times.";
    let mut frame = ContextFrame::full(
        "frame:policy:retry",
        FrameKind::Doc,
        "Retry policy",
        content,
        0.875,
        budget_tokens(content),
    );
    frame.content_digest = Some(DIGEST_A.into());
    frame.uri = Some("file:///repo/docs/retry-policy.md".into());
    frame.content_fidelity = Some(ContentFidelity::Exact);
    frame.minimum_content_fidelity = Some(ContentFidelity::Normalized);
    frame.inline_content_requirement = Some(InlineContentRequirement::Required);
    frame.canonical_token_cost = Some(budget_tokens(content));
    frame.tokenizer_ref = Some("openai:o200k_base".into());
    frame.valid_from = Some("2026-01-01T00:00:00Z".into());
    frame.valid_to = Some("2026-12-31T23:59:59Z".into());
    frame.recorded_at = Some("2026-07-21T12:34:56Z".into());
    frame.citation_label = Some("retry-policy.md L10-18".into());
    frame.provenance = vec![
        Provenance {
            kind: "file".into(),
            uri: Some("file:///repo/docs/retry-policy.md".into()),
            range: Some("L10-18".into()),
            digest: Some(DIGEST_A.into()),
            method: Some("file-read".into()),
            by: Some("repo-indexer".into()),
        },
        // A `derivation` link has no addressable bytes, so F5 does not hold it
        // to a digest (SPEC.md §6.2) — the vector exercises that asymmetry.
        Provenance {
            kind: "derivation".into(),
            uri: Some("contextgraph://repo-indexer/retry-policy".into()),
            range: None,
            digest: None,
            method: Some("summary".into()),
            by: Some("repo-indexer".into()),
        },
    ];
    frame.embedding = Some(FrameEmbedding {
        fingerprint: "bge-small-en-v1.5/384/l2".into(),
        vector: Some(vec![0.125, -0.5, 1.0]),
    });
    frame.relations = vec![Relation {
        rel: "doc.documents".into(),
        target_uri: "symbol:///repo/src/retry.rs#RetryPolicy".into(),
        display_name: Some("RetryPolicy".into()),
    }];
    frame
}

/// The minimal legal `full` frame: every skip-when-empty field omitted.
fn minimal_frame() -> ContextFrame {
    let content = "Default arrays are omitted on the wire.";
    let mut frame = ContextFrame::full(
        "frame:minimal",
        FrameKind::Fact,
        "Minimal conforming frame",
        content,
        1.0,
        budget_tokens(content),
    );
    // F3 still requires a citation label — minimal is not the same as invalid.
    frame.citation_label = Some("minimal vector".into());
    frame
}

/// A `compact` frame: inline distilled content plus the full P2 field set.
fn compact_frame() -> ContextFrame {
    let distilled = "Retry: exponential backoff, max 3.";
    let mut frame = ContextFrame::full(
        "frame:policy:retry#compact",
        FrameKind::Doc,
        "Retry policy (distilled)",
        distilled,
        0.8,
        budget_tokens(distilled),
    );
    frame.representation = Representation::Compact;
    frame.content_digest = Some(DIGEST_B.into());
    frame.canonical_content_hash = Some(DIGEST_A.into());
    frame.content_fidelity = Some(ContentFidelity::Summarized);
    frame.content_ref = Some(ContentRef {
        provider_id: "repo-indexer".into(),
        uri: "contextgraph-ref://repo-indexer/frame:policy:retry".into(),
        expires_at: Some("2026-12-31T23:59:59Z".into()),
    });
    frame.transform = Some(Transform {
        method: "extractive-summary".into(),
        implementation: "repo-indexer/distill".into(),
        version: "1.0.0".into(),
    });
    // P4/B3: the declared cost is the *inline* cost; the full-source cost lives
    // in the separate optional field, never smuggled into token_cost.
    frame.canonical_token_cost = Some(budget_tokens(
        "Retry with exponential backoff, at most 3 times.",
    ));
    frame.citation_label = Some("retry-policy.md (distilled)".into());
    frame
}

/// A `reference` frame: no inline content at all, so B3 costs it at 0.
fn reference_frame() -> ContextFrame {
    let mut frame = ContextFrame::reference(
        "frame:policy:retry#ref",
        FrameKind::Doc,
        "Retry policy (reference)",
        ContentRef {
            provider_id: "repo-indexer".into(),
            uri: "contextgraph-ref://repo-indexer/frame:policy:retry".into(),
            expires_at: None,
        },
        DIGEST_A,
        0.7,
    );
    frame.content_fidelity = Some(ContentFidelity::Omitted);
    frame.inline_content_requirement = Some(InlineContentRequirement::ResolvableReferenceAllowed);
    frame.canonical_token_cost = Some(budget_tokens(
        "Retry with exponential backoff, at most 3 times.",
    ));
    frame.citation_label = Some("retry-policy.md (reference)".into());
    frame
}

fn maximal_capabilities() -> Capabilities {
    Capabilities {
        query: QueryCapability {
            kinds: vec!["doc".into(), "snippet".into()],
        },
        correlation: true,
        graph: true,
        embeddings_fingerprint: Some("bge-small-en-v1.5/384/l2".into()),
        verify: true,
        representations: vec![
            Representation::Full,
            Representation::Compact,
            Representation::Reference,
        ],
        resolve: true,
    }
}

/// Every wire vector, in a fixed order. The label is the failure message's
/// handle on a drifted line; it is deliberately *not* serialized, because an
/// extra member would violate the schema's authoring-strict
/// `additionalProperties: false`.
fn vectors() -> Vec<(&'static str, Envelope)> {
    vec![
        (
            "handshake",
            Envelope::Handshake {
                protocol_version: PROTOCOL_VERSION.into(),
            },
        ),
        // Minimal ack: default capabilities, local-only data flow, no scopes.
        (
            "handshake_ack/minimal",
            Envelope::HandshakeAck {
                attester_keys: vec![],
                protocol_version: PROTOCOL_VERSION.into(),
                provider: ProviderInfo {
                    name: "minimal-provider".into(),
                    version: "0.1.0".into(),
                    data_flow: DataFlow::default(),
                },
                capabilities: Capabilities::default(),
            },
        ),
        (
            "handshake_ack/maximal",
            Envelope::HandshakeAck {
                attester_keys: vec![],
                protocol_version: PROTOCOL_VERSION.into(),
                provider: ProviderInfo {
                    name: "example-docs".into(),
                    version: "1.0.0".into(),
                    data_flow: DataFlow {
                        reads: true,
                        writes: true,
                        egress: true,
                        egress_scopes: vec![
                            EgressScope::OrgTenant,
                            EgressScope::ThirdPartyModel,
                            EgressScope::Custom("acme:vector-store".into()),
                        ],
                    },
                },
                capabilities: maximal_capabilities(),
            },
        ),
        // THE regression vector for #54: the conformance suite's own probe.
        // `kinds`, `anchors`, and `representation_preferences` are all empty, so
        // the reference serializer omits them; the schema listed the first two
        // as `required`, which made this exact query invalid.
        (
            "query/minimal-unfiltered",
            Envelope::Query {
                id: None,
                query: sample_query(),
            },
        ),
        (
            "query/maximal",
            Envelope::Query {
                id: Some("req-1".into()),
                query: ContextQuery {
                    goal: "explain the retry policy".into(),
                    query_text: Some("retry backoff".into()),
                    embedding: Some(vec![0.1, -0.25, 0.5]),
                    kinds: vec![FrameKind::Doc, FrameKind::Snippet],
                    anchors: vec!["file:///repo/src/retry.rs".into()],
                    max_frames: 8,
                    max_tokens: 4096,
                    as_of: Some("2026-07-21T12:34:56Z".into()),
                    representation_preferences: vec![Representation::Compact, Representation::Full],
                },
            },
        ),
        // An empty result is a legitimate answer, not an error (SPEC.md §5).
        (
            "frames/empty",
            Envelope::Frames {
                id: None,
                result: ContextQueryResult {
                    frames: vec![],
                    truncated: false,
                    dropped_estimate: None,
                    ..Default::default()
                },
            },
        ),
        (
            "frames/all-representations",
            Envelope::Frames {
                id: Some("req-1".into()),
                result: ContextQueryResult {
                    frames: vec![
                        maximal_frame(),
                        minimal_frame(),
                        compact_frame(),
                        reference_frame(),
                    ],
                    truncated: true,
                    dropped_estimate: Some(12),
                    ..Default::default()
                },
            },
        ),
        // A signed answer (SPEC.md §6.5.5, F11-F13). It shows both shapes an
        // entry can take: `frame:policy:retry` carries its own signature AND a
        // proof, while `frame:minimal` is attested only through the root — the
        // cheapest honest shape, one signature instead of n. `frame:minimal`
        // also declares no `content_digest`, so the vector exercises the
        // `enc_opt(None)` arm of the §6.5.2 preimage.
        (
            "frames/attested",
            Envelope::Frames {
                id: Some("req-2".into()),
                result: ContextQueryResult {
                    frames: vec![maximal_frame(), minimal_frame()],
                    truncated: false,
                    dropped_estimate: None,
                    frame_attestations: vec![
                        FrameAttestation::signed(
                            FrameId::new(
                                ATTESTING_PROVIDER,
                                "frame:policy:retry",
                                Some(DIGEST_A.into()),
                            ),
                            attestation(attested::MAXIMAL_COMMITMENT, attested::MAXIMAL_SIGNATURE),
                        )
                        .with_inclusion_proof(InclusionProof {
                            leaf_index: 1,
                            leaf_count: 2,
                            path: vec![InclusionStep {
                                sibling: attested::MAXIMAL_SIBLING.into(),
                                sibling_is_left: true,
                            }],
                        }),
                        FrameAttestation::proven(
                            FrameId::new(ATTESTING_PROVIDER, "frame:minimal", None),
                            InclusionProof {
                                leaf_index: 0,
                                leaf_count: 2,
                                path: vec![InclusionStep {
                                    sibling: attested::MINIMAL_SIBLING.into(),
                                    sibling_is_left: false,
                                }],
                            },
                        ),
                    ],
                    result_attestation: Some(attestation(attested::ROOT, attested::ROOT_SIGNATURE)),
                },
            },
        ),
        (
            "verify",
            Envelope::Verify {
                request: VerifyRequest::new(vec![
                    FrameId::new("repo-indexer", "frame:policy:retry", Some(DIGEST_A.into())),
                    // V1: a digest-less identity is unverifiable, and the shape
                    // must still be representable so a host can say so.
                    FrameId::new("repo-indexer", "frame:minimal", None),
                ]),
            },
        ),
        (
            "verified",
            Envelope::Verified {
                response: VerifyResponse::new(vec![
                    FrameVerdict::new(
                        FrameId::new("repo-indexer", "frame:policy:retry", Some(DIGEST_A.into())),
                        Verdict::Valid,
                    ),
                    FrameVerdict::new(
                        FrameId::new("repo-indexer", "frame:changed", Some(DIGEST_B.into())),
                        Verdict::Stale {
                            replacement_digest: Some(DIGEST_C.into()),
                        },
                    ),
                    // A `stale` verdict need not know the replacement (V4).
                    FrameVerdict::new(
                        FrameId::new("repo-indexer", "frame:changed-unknown-to", None),
                        Verdict::Stale {
                            replacement_digest: None,
                        },
                    ),
                    FrameVerdict::new(
                        FrameId::new("repo-indexer", "frame:deleted", None),
                        Verdict::Gone,
                    ),
                    FrameVerdict::new(
                        FrameId::new("repo-indexer", "frame:never-served", None),
                        Verdict::Unknown,
                    ),
                ]),
            },
        ),
        ("shutdown", Envelope::Shutdown),
        // A provider written against an earlier revision omits `code`; a host
        // reads that absence as `internal` (SPEC.md §10).
        (
            "error/uncoded",
            Envelope::Error {
                id: None,
                code: None,
                message: "malformed line".into(),
            },
        ),
        (
            "error/coded",
            Envelope::Error {
                id: Some("req-1".into()),
                code: Some(ErrorCode::BadRequest),
                message: "query.max_tokens must be positive".into(),
            },
        ),
        // X1/U1 forward compatibility: an unrecognised code survives the
        // round-trip verbatim rather than being coerced on the way through.
        (
            "error/unknown-code",
            Envelope::Error {
                id: None,
                code: Some(ErrorCode::Unknown("quota_exhausted".into())),
                message: "a code this revision does not define".into(),
            },
        ),
    ]
}

fn render() -> String {
    let mut out = String::new();
    for (label, envelope) in vectors() {
        let line = serde_json::to_string(&envelope)
            .unwrap_or_else(|e| panic!("vector {label} must serialize: {e}"));
        out.push_str(&line);
        out.push('\n');
    }
    out
}

#[test]
fn reference_vectors_match_the_committed_file() {
    let path = repo_root().join(VECTOR_FILE);
    let rendered = render();

    if std::env::var_os(REGENERATE_ENV).is_some() {
        fs::write(&path, &rendered).expect("write reference vectors");
        return;
    }

    let committed = fs::read_to_string(&path).unwrap_or_else(|e| {
        panic!("{VECTOR_FILE} is missing ({e}). Regenerate: {REGENERATE_ENV}=1 cargo test -p contextgraph-conformance --test reference_vectors")
    });

    if committed == rendered {
        return;
    }

    // Name the first drifted vector rather than dumping two files at the
    // reader: the label is the whole point of keeping them ordered.
    let labels: Vec<_> = vectors().into_iter().map(|(l, _)| l).collect();
    let committed_lines: Vec<_> = committed.lines().collect();
    let rendered_lines: Vec<_> = rendered.lines().collect();
    for (i, label) in labels.iter().enumerate() {
        let old = committed_lines.get(i);
        let new = rendered_lines.get(i);
        if old != new {
            panic!(
                "reference vector `{label}` (line {}) drifted from {VECTOR_FILE}.\n  committed: {}\n  serialized: {}\n\nIf the wire change is intended, regenerate and re-validate:\n  {REGENERATE_ENV}=1 cargo test -p contextgraph-conformance --test reference_vectors\n  python3 schema/validate-examples.py",
                i + 1,
                old.unwrap_or(&"<missing>"),
                new.unwrap_or(&"<missing>"),
            );
        }
    }
    assert_eq!(
        committed_lines.len(),
        rendered_lines.len(),
        "{VECTOR_FILE} has a different number of vectors than the generator; regenerate with {REGENERATE_ENV}=1"
    );
}

#[test]
fn every_vector_round_trips_through_the_wire_decoder() {
    for (label, envelope) in vectors() {
        let line = serde_json::to_string(&envelope).expect("serialize");
        let decoded = decode_line(&line)
            .unwrap_or_else(|e| panic!("vector {label} must decode back into an envelope: {e}"));
        assert_eq!(decoded, envelope, "vector {label} must round-trip exactly");
    }
}

/// The vectors are not merely schema-valid — they are *conformant*, so a
/// downstream implementation can diff against them as golden output (#52).
#[test]
fn vectors_are_conformant() {
    for (label, envelope) in vectors() {
        let Envelope::Frames { result, .. } = &envelope else {
            continue;
        };
        for frame in &result.frames {
            let id = &frame.id;
            assert!(
                frame.representation_invariants().is_ok(),
                "vector {label} frame {id} must satisfy its representation invariants: {:?}",
                frame.representation_invariants()
            );
            assert!(
                frame.declares_honest_token_cost(),
                "vector {label} frame {id} must declare an honest B3 token_cost \
                 (declared {}, canonical {})",
                frame.token_cost,
                frame.expected_inline_token_cost(),
            );
            assert!(
                frame.has_valid_score(),
                "vector {label} frame {id} must have a score in [0, 1]"
            );
            for provenance in &frame.provenance {
                if provenance.is_file_provenance() {
                    assert!(
                        provenance.has_well_formed_digest(),
                        "vector {label} frame {id} carries file provenance without an \
                         F5 digest — the vectors must model the rule, not dodge it"
                    );
                }
            }
        }
    }
}