Flesh out docs.rs documentation for the Rust crate

The crate-level page (lib.rs) is now a proper landing page: overview,
threat model, architecture table pointing into each module, failure-mode
table, quick start, and links to the wire-format spec, the companion
preprint, and the Python and TypeScript ports.

Each module gets a real intro plus runnable doctest examples:
  attestation.rs  to_json/from_json round-trip
  hash.rs         NFC normalization for hash_text;
                  canonical f32 endianness for canonical_vector_bytes;
                  sha256:<hex> shape for hash_vector
  signer.rs       basic generate+pin; deterministic pin_with_options
                  using PinOptions for explicit dtype + timestamp
  verifier.rs     full verify, signature-only, vector tamper caught
                  as VerifyError::VectorTampered, key rotation

Doctests grew from 1 → 12, all green. Strict doc build is also green:

  RUSTDOCFLAGS="-D missing_docs \
                -D rustdoc::broken_intra_doc_links \
                -D rustdoc::missing_crate_level_docs"

Cargo.toml gains [package.metadata.docs.rs] with all-features = true
so docs.rs always builds the full surface. lib.rs adds the matching
warn lints so future doc rot is caught locally.

The crates.io README (rust/vectorpin/README.md) is rewritten to match
the docs.rs landing-page tone: badges, what gets pinned, failure-mode
table, threat model summary, and pointers into docs.rs and the spec.

Author: jaschadub

rust/vectorpin/Cargo.toml

@@ -33,3 +33,7 @@ default = []
 [[bench]]
 name = "perf"
 harness = false
+
+# docs.rs builds the documentation with these settings.
+[package.metadata.docs.rs]
+all-features = true

rust/vectorpin/README.md

@@ -1,58 +1,97 @@
 # vectorpin
 
-Rust port of [VectorPin](https://vectorpin.org) — verifiable integrity for AI embedding stores.
+[![Crates.io](https://img.shields.io/crates/v/vectorpin.svg)](https://crates.io/crates/vectorpin)
+[![Docs.rs](https://docs.rs/vectorpin/badge.svg)](https://docs.rs/vectorpin)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
 
-Part of the [ThirdKey](https://thirdkey.ai) Trust Stack.
+Verifiable integrity for AI embedding stores. Rust reference implementation of the [VectorPin](https://github.com/ThirdKeyAI/VectorPin) attestation protocol.
 
-## Why a Rust crate
+VectorPin pins each embedding to its source content and the producing model via an Ed25519 signature over a canonical byte representation. Any post-pinning modification of the vector or source text — including covert [steganographic exfiltration attacks](https://doi.org/10.5281/zenodo.20058256) that current vector databases ingest without complaint — breaks signature verification on read.
 
-Symbiont — the Rust-native policy-governed agent runtime in the Trust Stack — needs to verify VectorPin attestations in-process, without a Python sidecar. This crate is the canonical Rust implementation and is bit-for-bit compatible with the Python reference: the same protocol v1 wire format, the same canonical bytes, the same Ed25519 signatures.
+This crate is **byte-for-byte compatible** with the Python reference (`pip install vectorpin`) and the TypeScript reference (`npm install vectorpin`). A pin produced by any of the three implementations verifies on the other two; the contract is enforced by shared test vectors that every port consumes in CI.
 
-Cross-language compatibility is enforced by the test vectors in `../../testvectors/`, which both the Python and Rust test suites consume.
+Part of the [ThirdKey](https://thirdkey.ai) Trust Stack, alongside [Symbiont](https://github.com/ThirdKeyAI/Symbiont) — the Rust-native policy-governed agent runtime that consumes these attestations in-process without a Python sidecar.
 
 ## Quick start
 
-Add to your `Cargo.toml`:
-
 ```toml
 [dependencies]
 vectorpin = "0.1"
 ```
 
 ```rust
-use vectorpin::{Signer, Verifier, VerifyError};
-
-fn main() -> anyhow::Result<()> {
-    let signer = Signer::generate("prod-2026-05".to_string());
-
-    // Some embedding produced by a model
-    let embedding: Vec<f32> = my_model_embed("The quick brown fox.");
-
-    let pin = signer.pin(
-        "The quick brown fox.",
-        "text-embedding-3-large",
-        &embedding,
-    )?;
-
-    // Store pin.to_json() alongside the embedding in your vector DB.
-
-    let mut verifier = Verifier::new();
-    verifier.add_key(signer.key_id(), signer.public_key_bytes());
-
-    let result = verifier.verify_full(
-        &pin,
-        Some("The quick brown fox."),
-        Some(&embedding),
-        None,
-    );
-    assert!(result.is_ok());
-    Ok(())
-}
+use vectorpin::{Signer, Verifier};
+
+// Ingestion: produce an embedding, sign a pin for it.
+let signer = Signer::generate("prod-2026-05".to_string());
+let embedding: Vec<f32> = my_model_embed("The quick brown fox.");
+
+let pin = signer.pin(
+    "The quick brown fox.",
+    "text-embedding-3-large",
+    embedding.as_slice(),
+)?;
+
+// Persist `pin.to_json()` alongside the embedding in your vector DB.
+let stored: String = pin.to_json();
+
+// Read/audit: parse the stored JSON and verify against ground truth.
+let parsed = vectorpin::Pin::from_json(&stored)?;
+let mut verifier = Verifier::new();
+verifier.add_key(signer.key_id(), signer.public_key_bytes());
+
+let result = verifier.verify_full(
+    &parsed,
+    Some("The quick brown fox."),
+    Some(embedding.as_slice()),
+    None,
+);
+assert!(result.is_ok());
 ```
 
+## What gets pinned
+
+Each `Pin` commits to:
+
+- **The source text**, by SHA-256 of UTF-8 NFC-normalized bytes.
+- **The model**, by identifier (and optionally by content hash).
+- **The vector itself**, by SHA-256 of canonical little-endian f32/f64 bytes.
+- **The producer**, by Ed25519 signing-key identifier (`kid`).
+- **The time**, by RFC 3339 timestamp.
+
+Verification distinguishes failure modes via the `VerifyError` enum so callers can route them differently:
+
+| Variant | Meaning |
+|---|---|
+| `SignatureInvalid` | Pin was forged or re-signed by an attacker |
+| `VectorTampered` | Embedding modified after pinning — the steganography kill shot |
+| `SourceMismatch` | Source text differs from what was pinned |
+| `ModelMismatch` | Pin produced by a different embedding model than expected |
+| `UnknownKey` | Pin signed by a key not in the verifier's registry |
+| `UnsupportedVersion` | Protocol version mismatch |
+| `ShapeMismatch` | Supplied vector's dim disagrees with the pin header |
+
+## Threat model
+
+VectorPin is designed against an attacker who can:
+
+- Modify vectors after they are produced — via a poisoned ingestion pipeline, a compromised vector DB, or backup-level access.
+- See the public verification key but not the private signing key.
+- Replay or selectively delete pins.
+
+It does **not** defend against:
+
+- An attacker with the private signing key (key custody is the user's responsibility).
+- An attacker who modifies the source documents *before* embedding (use upstream content integrity controls).
+- An attacker who uses a legitimate signing key to attest a malicious vector at ingestion time (use upstream input validation).
+
+For the empirical evaluation of the attack class VectorPin is built to defeat, see the companion preprint at <https://doi.org/10.5281/zenodo.20058256>.
+
 ## Status
 
-Alpha. Protocol v1 stable; covered by the cross-language test vectors.
+Alpha (`v0.1`). Protocol v1 stable; covered by the cross-language test vectors. The wire format will not break compatibility without a major-version bump.
+
+See the full [protocol specification](https://github.com/ThirdKeyAI/VectorPin/blob/main/docs/spec.md) and [docs.rs](https://docs.rs/vectorpin) for the complete API reference.
 
 ## License
 

rust/vectorpin/src/attestation.rs

@@ -1,13 +1,41 @@
 // Copyright 2025 Jascha Wanger / Tarnover, LLC
 // SPDX-License-Identifier: Apache-2.0
 
-//! Pin attestation format and canonicalization.
+//! Pin attestation data structures and canonical serialization.
 //!
-//! See `docs/spec.md` in the repo root for the protocol specification.
-//! In summary: a [`Pin`] is a JSON object with a header (the signed
-//! payload) plus a key id and signature. The header canonicalizes to a
-//! deterministic byte sequence — sorted keys, no whitespace — that
-//! both Python and Rust implementations agree on byte-for-byte.
+//! A [`Pin`] is a JSON object with a header (the signed payload) plus a
+//! key id and a signature. The header canonicalizes to a deterministic
+//! byte sequence — sorted keys, no whitespace, raw UTF-8 (non-ASCII
+//! is *not* escaped to `\uXXXX`) — that the Python, Rust, and
+//! TypeScript reference implementations agree on byte-for-byte.
+//!
+//! That deterministic byte sequence is what gets signed by Ed25519, not
+//! the JSON wire form. Re-serializing a pin (different whitespace,
+//! different key order) therefore does *not* invalidate the signature
+//! as long as the canonical form is recoverable.
+//!
+//! For the full wire-format specification — every field, every supported
+//! dtype, the exact canonicalization algorithm — see
+//! [`docs/spec.md`](https://github.com/ThirdKeyAI/VectorPin/blob/main/docs/spec.md).
+//!
+//! # Example
+//!
+//! ```
+//! use vectorpin::{Pin, Signer};
+//!
+//! let signer = Signer::generate("demo".to_string());
+//! let v: Vec<f32> = vec![1.0, 2.0, 3.0];
+//! let pin = signer.pin("hello", "test-model", v.as_slice()).unwrap();
+//!
+//! // Compact JSON for storage in your vector DB metadata.
+//! let json: String = pin.to_json();
+//! assert!(!json.contains(": "));
+//! assert!(!json.contains(", "));
+//!
+//! // Round-trip through wire form preserves the pin exactly.
+//! let parsed = Pin::from_json(&json).unwrap();
+//! assert_eq!(pin, parsed);
+//! ```
 
 use std::collections::BTreeMap;
 
@@ -21,8 +49,14 @@ pub const PROTOCOL_VERSION: u32 = 1;
 /// The signed portion of a [`Pin`].
 ///
 /// Two pins are considered equivalent iff their headers canonicalize to
-/// identical bytes. Optional fields (`model_hash`, `extra`) are omitted
-/// from the canonical form when unset, never written as `null`.
+/// identical bytes. Optional fields ([`model_hash`](Self::model_hash),
+/// [`extra`](Self::extra)) are omitted from the canonical form when
+/// unset, never written as `null` — this matters because adding a
+/// `null` would change the byte sequence the signature commits to.
+///
+/// You normally do not construct `PinHeader` directly; obtain one from
+/// [`Signer::pin`](crate::Signer::pin) or
+/// [`Signer::pin_with_options`](crate::signer::Signer::pin_with_options).
 #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
 pub struct PinHeader {
     /// Protocol version. Must equal [`PROTOCOL_VERSION`].
@@ -99,8 +133,25 @@ impl PinHeader {
     }
 }
 
-/// A signed VectorPin attestation. Serialize with [`Pin::to_json`] and
-/// store alongside the embedding in vector store metadata.
+/// A signed VectorPin attestation.
+///
+/// Serialize with [`Pin::to_json`] and store the resulting string
+/// alongside the embedding in vector-store metadata. On read, parse
+/// with [`Pin::from_json`] and hand to [`Verifier::verify_full`](crate::Verifier::verify_full).
+///
+/// # Example
+///
+/// ```
+/// use vectorpin::{Pin, Signer, Verifier};
+///
+/// let signer = Signer::generate("k1".to_string());
+/// let v: Vec<f32> = vec![1.0, 2.0, 3.0];
+/// let pin = signer.pin("hello", "m", v.as_slice()).unwrap();
+///
+/// let mut verifier = Verifier::new();
+/// verifier.add_key(signer.key_id(), signer.public_key_bytes());
+/// assert!(verifier.verify_signature(&Pin::from_json(&pin.to_json()).unwrap()).is_ok());
+/// ```
 #[derive(Debug, Clone, PartialEq, Eq)]
 pub struct Pin {
     /// The signed payload.

rust/vectorpin/src/hash.rs

@@ -5,12 +5,43 @@
 //!
 //! These three operations are the only places in the protocol where
 //! semantic content gets turned into bytes. Any disagreement between
-//! Python and Rust here breaks cross-language verification, so the
-//! semantics are pinned down explicitly:
+//! the Python, Rust, and TypeScript ports here breaks cross-language
+//! verification, so the semantics are pinned down explicitly:
 //!
 //! * Vectors: little-endian, 1-D, packed `f32` or `f64` bytes.
 //! * Text: UTF-8 of the NFC-normalized string.
 //! * Output digests: prefixed with `"sha256:"` and lowercase hex.
+//!
+//! Cross-language byte-for-byte parity for the functions in this module
+//! is asserted by `tests/cross_lang.rs` against the shared fixtures in
+//! [`testvectors/`](https://github.com/ThirdKeyAI/VectorPin/tree/main/testvectors).
+//!
+//! # Examples
+//!
+//! Hashing source text is NFC-normalized so that visually identical
+//! strings stored in different Unicode forms hash equal:
+//!
+//! ```
+//! use vectorpin::hash_text;
+//!
+//! let composed = "caf\u{00e9}";        // 'é' as one codepoint (NFC)
+//! let decomposed = "cafe\u{0301}";     // 'e' + combining acute (NFD)
+//! assert_eq!(hash_text(composed), hash_text(decomposed));
+//! assert!(hash_text("hello").starts_with("sha256:"));
+//! ```
+//!
+//! Hashing a vector requires the dtype the caller wants to commit to.
+//! The same numeric values hashed under f32 and f64 produce different
+//! digests, by design — the dtype is part of the signed contract:
+//!
+//! ```
+//! use vectorpin::{hash_vector, hash::VectorRef, VecDtype};
+//!
+//! let v: Vec<f32> = vec![0.1, 0.2, 0.3];
+//! let h32 = hash_vector(VectorRef::F32(&v), VecDtype::F32);
+//! assert!(h32.starts_with("sha256:"));
+//! assert_eq!(h32.len(), "sha256:".len() + 64);
+//! ```
 
 use sha2::{Digest, Sha256};
 use unicode_normalization::UnicodeNormalization;
@@ -117,8 +148,20 @@ impl<'a> From<&'a [f64]> for VectorRef<'a> {
 /// Reproducible byte form of an embedding vector.
 ///
 /// Always little-endian, always packed, always under the dtype
-/// requested by the caller. Two implementations must agree on these
-/// bytes byte-for-byte for cross-language verification to work.
+/// requested by the caller. The Python, Rust, and TypeScript ports
+/// must agree on these bytes byte-for-byte for cross-language
+/// verification to work.
+///
+/// # Example
+///
+/// ```
+/// use vectorpin::{canonical_vector_bytes, hash::VectorRef, VecDtype};
+///
+/// let v = [1.0_f32];
+/// let bytes = canonical_vector_bytes(VectorRef::F32(&v), VecDtype::F32);
+/// // 1.0_f32 in IEEE-754 little-endian.
+/// assert_eq!(bytes, [0x00, 0x00, 0x80, 0x3f]);
+/// ```
 pub fn canonical_vector_bytes(vector: VectorRef<'_>, dtype: VecDtype) -> Vec<u8> {
     match (vector, dtype) {
         (VectorRef::F32(v), VecDtype::F32) => f32_le_bytes(v),