@nuggetslife/vc 0.1.0 → 0.3.0

package/src/ld_signatures.rs

@@ -1,89 +1,79 @@
 use std::collections::{BTreeMap, HashMap};
-use std::num::NonZeroUsize;
 use std::sync::Arc;
 
 use base64::prelude::BASE64_STANDARD;
 use base64::Engine;
-use lru::LruCache;
 use napi::bindgen_prelude::*;
 use serde_json::Value;
 
 use vc::{
-    bbs_signatures::bls12381::{
-        bls_blind_signature_commitment, bls_unblind_signature, bls_verify_blind_signature_proof,
-    },
-    did_resolver::resolver::{DidResolutionOptions, Resolver, ResolverRegistry},
-    document_loader::nuggets::{load_nuggets_context, DocumentLoader},
-    jsonld::{
-        context_resolver::ContextResolver,
-        signatures::{
-            self,
-            bbs::{
-                bls_12381_g2_keypair::{types::KeyPairOptions, Bls12381G2KeyPair},
-                BbsBlsSignature2020 as BbsSignatureSuite, SignatureSuiteOptions,
-            },
-            AssertionProofPurpose,
-        },
+  bbs_signatures::bls12381::{
+    bls_blind_signature_commitment, bls_unblind_signature, bls_verify_blind_signature_proof,
+  },
+  did_resolver::resolver::{DidResolutionOptions, Resolver, ResolverRegistry},
+  document_loader::nuggets::{load_nuggets_context, DocumentLoader},
+  jsonld::signatures::{
+    self,
+    bbs::{
+      bls_12381_g2_keypair::{types::KeyPairOptions, Bls12381G2KeyPair},
+      BbsBlsSignature2020 as BbsSignatureSuite, SignatureSuiteOptions,
     },
+    AssertionProofPurpose,
+  },
 };
 
 /// Create a DocumentLoader with nuggets contexts plus additional caller-provided contexts.
+///
+/// Extras are layered into the V1 context map AND retained separately so
+/// the V2 dispatch chain (canonize_dispatch) can hand them to its own
+/// build_loader. See clientffi#69 / PR #59.
 pub(crate) fn create_document_loader(
-    additional_contexts: HashMap<String, Value>,
-) -> (Arc<DocumentLoader>, Arc<ContextResolver>) {
-    let mut ctx = load_nuggets_context();
-    ctx.extend(additional_contexts);
-
-    let resolver = Arc::new(tokio::sync::RwLock::new(Resolver::new(
-        ResolverRegistry::new(),
-        None,
-    )));
-    let opts = DidResolutionOptions::default();
-    let loader = Arc::new(DocumentLoader::new(ctx, resolver, opts));
-    let cr = Arc::new(ContextResolver::new(LruCache::new(
-        NonZeroUsize::new(10).unwrap(),
-    )));
-
-    (loader, cr)
+  additional_contexts: HashMap<String, Value>,
+) -> Arc<DocumentLoader> {
+  let mut ctx = load_nuggets_context();
+  ctx.extend(additional_contexts.clone());
+
+  let resolver = Arc::new(tokio::sync::RwLock::new(Resolver::new(
+    ResolverRegistry::new(),
+    None,
+  )));
+  let opts = DidResolutionOptions::default();
+  Arc::new(DocumentLoader::with_additional_contexts(
+    ctx,
+    additional_contexts,
+    resolver,
+    opts,
+  ))
 }
 
 /// Parse an optional nonce string: try base64 decode, fall back to raw bytes.
 fn parse_nonce(options: &Value) -> Option<Vec<u8>> {
-    options
-        .get("nonce")
-        .and_then(|v| v.as_str())
-        .map(|s| {
-            BASE64_STANDARD
-                .decode(s)
-                .unwrap_or_else(|_| s.as_bytes().to_vec())
-        })
+  options.get("nonce").and_then(|v| v.as_str()).map(|s| {
+    BASE64_STANDARD
+      .decode(s)
+      .unwrap_or_else(|_| s.as_bytes().to_vec())
+  })
 }
 
 /// Parse the `contexts` field from options JSON into a HashMap.
 pub(crate) fn parse_contexts(options: &Value) -> HashMap<String, Value> {
-    options
-        .get("contexts")
-        .and_then(|v| v.as_object())
-        .map(|obj| {
-            obj.iter()
-                .map(|(k, v)| (k.clone(), v.clone()))
-                .collect()
-        })
-        .unwrap_or_default()
+  options
+    .get("contexts")
+    .and_then(|v| v.as_object())
+    .map(|obj| obj.iter().map(|(k, v)| (k.clone(), v.clone())).collect())
+    .unwrap_or_default()
 }
 
-/// Create a DocumentLoader + ContextResolver from an optional contexts Value.
+/// Create a DocumentLoader from an optional contexts Value.
 ///
 /// This is the common pattern used by all class-based suite methods:
-/// takes the `contexts` field from options and creates the loader pair.
-pub(crate) fn loader_from_contexts(
-    contexts: Option<&Value>,
-) -> (Arc<DocumentLoader>, Arc<ContextResolver>) {
-    let additional = contexts
-        .and_then(|v| v.as_object())
-        .map(|obj| obj.iter().map(|(k, v)| (k.clone(), v.clone())).collect())
-        .unwrap_or_default();
-    create_document_loader(additional)
+/// takes the `contexts` field from options and creates the loader.
+pub(crate) fn loader_from_contexts(contexts: Option<&Value>) -> Arc<DocumentLoader> {
+  let additional = contexts
+    .and_then(|v| v.as_object())
+    .map(|obj| obj.iter().map(|(k, v)| (k.clone(), v.clone())).collect())
+    .unwrap_or_default();
+  create_document_loader(additional)
 }
 
 /// Sign a document with BbsBlsSignature2020 and embed the proof.
@@ -92,32 +82,32 @@ pub(crate) fn loader_from_contexts(
 /// Output: signed document JSON with embedded proof
 #[napi]
 pub async fn ld_sign(options: Value) -> napi::Result<Value> {
-    let document = options
-        .get("document")
-        .cloned()
-        .ok_or_else(|| napi::Error::from_reason("missing 'document' in options"))?;
-
-    let key_pair_opts: KeyPairOptions =
-        serde_json::from_value(options.get("keyPair").cloned().unwrap_or(Value::Null))
-            .map_err(|e| napi::Error::from_reason(format!("failed to parse keyPair: {e}")))?;
-
-    let additional_contexts = parse_contexts(&options);
-
-    let key = Bls12381G2KeyPair::new(Some(key_pair_opts));
-    let (loader, cr) = create_document_loader(additional_contexts);
-
-    let suite = BbsSignatureSuite::new(SignatureSuiteOptions {
-        key,
-        verification_method: None,
-        date: None,
-        canonize_options: None,
-    })
-    .await;
-
-    let purpose = AssertionProofPurpose::new();
-    signatures::sign(document, &suite, &purpose, loader, cr)
-        .await
-        .map_err(|e| napi::Error::from_reason(format!("ld_sign failed: {e}")))
+  let document = options
+    .get("document")
+    .cloned()
+    .ok_or_else(|| napi::Error::from_reason("missing 'document' in options"))?;
+
+  let key_pair_opts: KeyPairOptions =
+    serde_json::from_value(options.get("keyPair").cloned().unwrap_or(Value::Null))
+      .map_err(|e| napi::Error::from_reason(format!("failed to parse keyPair: {e}")))?;
+
+  let additional_contexts = parse_contexts(&options);
+
+  let key = Bls12381G2KeyPair::new(Some(key_pair_opts));
+  let loader = create_document_loader(additional_contexts);
+
+  let suite = BbsSignatureSuite::new(SignatureSuiteOptions {
+    key,
+    verification_method: None,
+    date: None,
+    canonize_options: None,
+  })
+  .await;
+
+  let purpose = AssertionProofPurpose::new();
+  signatures::sign(document, &suite, &purpose, loader)
+    .await
+    .map_err(|e| napi::Error::from_reason(format!("ld_sign failed: {e}")))
 }
 
 /// Verify a document with an embedded proof (auto-detects proof type).
@@ -126,23 +116,23 @@ pub async fn ld_sign(options: Value) -> napi::Result<Value> {
 /// Output: `{ verified: boolean, error?: string }`
 #[napi]
 pub async fn ld_verify(options: Value) -> napi::Result<Value> {
-    let document = options
-        .get("document")
-        .cloned()
-        .ok_or_else(|| napi::Error::from_reason("missing 'document' in options"))?;
-
-    let additional_contexts = parse_contexts(&options);
-
-    let (loader, cr) = create_document_loader(additional_contexts);
-    let purpose = AssertionProofPurpose::new();
-    let result = signatures::verify(&document, &purpose, loader, cr)
-        .await
-        .map_err(|e| napi::Error::from_reason(format!("ld_verify failed: {e}")))?;
-
-    Ok(serde_json::json!({
-        "verified": result.verified,
-        "error": result.error,
-    }))
+  let document = options
+    .get("document")
+    .cloned()
+    .ok_or_else(|| napi::Error::from_reason("missing 'document' in options"))?;
+
+  let additional_contexts = parse_contexts(&options);
+
+  let loader = create_document_loader(additional_contexts);
+  let purpose = AssertionProofPurpose::new();
+  let result = signatures::verify(&document, &purpose, loader)
+    .await
+    .map_err(|e| napi::Error::from_reason(format!("ld_verify failed: {e}")))?;
+
+  Ok(serde_json::json!({
+      "verified": result.verified,
+      "error": result.error,
+  }))
 }
 
 /// Derive a selective disclosure proof from a signed document.
@@ -151,24 +141,24 @@ pub async fn ld_verify(options: Value) -> napi::Result<Value> {
 /// Output: derived document JSON with embedded proof
 #[napi]
 pub async fn ld_derive_proof(options: Value) -> napi::Result<Value> {
-    let document = options
-        .get("document")
-        .cloned()
-        .ok_or_else(|| napi::Error::from_reason("missing 'document' in options"))?;
+  let document = options
+    .get("document")
+    .cloned()
+    .ok_or_else(|| napi::Error::from_reason("missing 'document' in options"))?;
 
-    let reveal_document = options
-        .get("revealDocument")
-        .cloned()
-        .ok_or_else(|| napi::Error::from_reason("missing 'revealDocument' in options"))?;
+  let reveal_document = options
+    .get("revealDocument")
+    .cloned()
+    .ok_or_else(|| napi::Error::from_reason("missing 'revealDocument' in options"))?;
 
-    let nonce = parse_nonce(&options);
+  let nonce = parse_nonce(&options);
 
-    let additional_contexts = parse_contexts(&options);
+  let additional_contexts = parse_contexts(&options);
 
-    let (loader, cr) = create_document_loader(additional_contexts);
-    signatures::derive_proof(&document, &reveal_document, nonce, loader, cr)
-        .await
-        .map_err(|e| napi::Error::from_reason(format!("ld_derive_proof failed: {e}")))
+  let loader = create_document_loader(additional_contexts);
+  signatures::derive_proof(&document, &reveal_document, nonce, loader)
+    .await
+    .map_err(|e| napi::Error::from_reason(format!("ld_derive_proof failed: {e}")))
 }
 
 /// Standalone deriveProof function matching the JS reference's
@@ -178,18 +168,18 @@ pub async fn ld_derive_proof(options: Value) -> napi::Result<Value> {
 /// Output: derived document JSON with embedded proof
 #[napi]
 pub async fn derive_proof(
-    proof_document: Value,
-    reveal_document: Value,
-    options: Value,
+  proof_document: Value,
+  reveal_document: Value,
+  options: Value,
 ) -> napi::Result<Value> {
-    let nonce = parse_nonce(&options);
+  let nonce = parse_nonce(&options);
 
-    let additional_contexts = parse_contexts(&options);
+  let additional_contexts = parse_contexts(&options);
 
-    let (loader, cr) = create_document_loader(additional_contexts);
-    signatures::derive_proof(&proof_document, &reveal_document, nonce, loader, cr)
-        .await
-        .map_err(|e| napi::Error::from_reason(format!("deriveProof failed: {e}")))
+  let loader = create_document_loader(additional_contexts);
+  signatures::derive_proof(&proof_document, &reveal_document, nonce, loader)
+    .await
+    .map_err(|e| napi::Error::from_reason(format!("deriveProof failed: {e}")))
 }
 
 /// Create a blind signature commitment (holder side).
@@ -199,33 +189,32 @@ pub async fn derive_proof(
 /// Output: `{ commitment, challengeHash, blindingFactor, proofOfHiddenMessages }` (all Uint8Array)
 #[napi]
 pub async fn create_commitment(
-    public_key: Uint8Array,
-    messages: Vec<Uint8Array>,
-    blinded: Vec<u32>,
-    nonce: Uint8Array,
-    known_message_count: u32,
+  public_key: Uint8Array,
+  messages: Vec<Uint8Array>,
+  blinded: Vec<u32>,
+  nonce: Uint8Array,
+  known_message_count: u32,
 ) -> napi::Result<serde_json::Value> {
-    let pk = public_key.to_vec();
-    let nonce_vec = nonce.to_vec();
-    let blinded_indices: Vec<usize> = blinded.iter().map(|&i| i as usize).collect();
-    let total_message_count = blinded_indices.len() + known_message_count as usize;
-
-    let mut msgs = BTreeMap::new();
-    for (idx, msg) in blinded_indices.iter().zip(messages.iter()) {
-        msgs.insert(*idx, msg.to_vec());
-    }
-
-    let result =
-        bls_blind_signature_commitment(pk, msgs, nonce_vec, total_message_count)
-            .await
-            .map_err(|e| napi::Error::from_reason(format!("createCommitment failed: {e}")))?;
-
-    Ok(serde_json::json!({
-        "commitment": base64::prelude::BASE64_STANDARD.encode(&result.commitment),
-        "challengeHash": base64::prelude::BASE64_STANDARD.encode(&result.challenge_hash),
-        "blindingFactor": base64::prelude::BASE64_STANDARD.encode(&result.blinding_factor),
-        "proofOfHiddenMessages": base64::prelude::BASE64_STANDARD.encode(&result.proof_of_hidden_messages),
-    }))
+  let pk = public_key.to_vec();
+  let nonce_vec = nonce.to_vec();
+  let blinded_indices: Vec<usize> = blinded.iter().map(|&i| i as usize).collect();
+  let total_message_count = blinded_indices.len() + known_message_count as usize;
+
+  let mut msgs = BTreeMap::new();
+  for (idx, msg) in blinded_indices.iter().zip(messages.iter()) {
+    msgs.insert(*idx, msg.to_vec());
+  }
+
+  let result = bls_blind_signature_commitment(pk, msgs, nonce_vec, total_message_count)
+    .await
+    .map_err(|e| napi::Error::from_reason(format!("createCommitment failed: {e}")))?;
+
+  Ok(serde_json::json!({
+      "commitment": base64::prelude::BASE64_STANDARD.encode(&result.commitment),
+      "challengeHash": base64::prelude::BASE64_STANDARD.encode(&result.challenge_hash),
+      "blindingFactor": base64::prelude::BASE64_STANDARD.encode(&result.blinding_factor),
+      "proofOfHiddenMessages": base64::prelude::BASE64_STANDARD.encode(&result.proof_of_hidden_messages),
+  }))
 }
 
 /// Verify a blind signature commitment (issuer side).
@@ -233,29 +222,29 @@ pub async fn create_commitment(
 /// Returns true if the commitment proof is valid.
 #[napi]
 pub async fn verify_commitment(
-    public_key: Uint8Array,
-    commitment: Uint8Array,
-    proof_of_hidden_messages: Uint8Array,
-    challenge_hash: Uint8Array,
-    blinded: Vec<u32>,
-    nonce: Uint8Array,
-    known_message_count: u32,
+  public_key: Uint8Array,
+  commitment: Uint8Array,
+  proof_of_hidden_messages: Uint8Array,
+  challenge_hash: Uint8Array,
+  blinded: Vec<u32>,
+  nonce: Uint8Array,
+  known_message_count: u32,
 ) -> napi::Result<bool> {
-    let pk = public_key.to_vec();
-    let blinded_indices: Vec<usize> = blinded.iter().map(|&i| i as usize).collect();
-    let total_message_count = blinded_indices.len() + known_message_count as usize;
-
-    bls_verify_blind_signature_proof(
-        pk,
-        commitment.to_vec(),
-        challenge_hash.to_vec(),
-        proof_of_hidden_messages.to_vec(),
-        blinded_indices,
-        nonce.to_vec(),
-        total_message_count,
-    )
-    .await
-    .map_err(|e| napi::Error::from_reason(format!("verifyCommitment failed: {e}")))
+  let pk = public_key.to_vec();
+  let blinded_indices: Vec<usize> = blinded.iter().map(|&i| i as usize).collect();
+  let total_message_count = blinded_indices.len() + known_message_count as usize;
+
+  bls_verify_blind_signature_proof(
+    pk,
+    commitment.to_vec(),
+    challenge_hash.to_vec(),
+    proof_of_hidden_messages.to_vec(),
+    blinded_indices,
+    nonce.to_vec(),
+    total_message_count,
+  )
+  .await
+  .map_err(|e| napi::Error::from_reason(format!("verifyCommitment failed: {e}")))
 }
 
 /// Unblind a blind signature (holder side).
@@ -264,14 +253,14 @@ pub async fn verify_commitment(
 /// returns the unblinded standard signature.
 #[napi]
 pub async fn unblind_signature(
-    blind_signature: Uint8Array,
-    blinding_factor: Uint8Array,
+  blind_signature: Uint8Array,
+  blinding_factor: Uint8Array,
 ) -> napi::Result<Uint8Array> {
-    let result = bls_unblind_signature(blind_signature.to_vec(), blinding_factor.to_vec())
-        .await
-        .map_err(|e| napi::Error::from_reason(format!("unblindSignature failed: {e}")))?;
+  let result = bls_unblind_signature(blind_signature.to_vec(), blinding_factor.to_vec())
+    .await
+    .map_err(|e| napi::Error::from_reason(format!("unblindSignature failed: {e}")))?;
 
-    Ok(Uint8Array::from(result))
+  Ok(Uint8Array::from(result))
 }
 
 /// Derive a selective disclosure proof from a holder-bound signed document.
@@ -281,49 +270,46 @@ pub async fn unblind_signature(
 /// Output: derived document JSON with embedded proof
 #[napi]
 pub async fn derive_proof_holder_bound(
-    proof_document: Value,
-    reveal_document: Value,
-    options: Value,
+  proof_document: Value,
+  reveal_document: Value,
+  options: Value,
 ) -> napi::Result<Value> {
-    let blinding_factor = options
-        .get("blindingFactor")
-        .and_then(|v| v.as_str())
-        .map(|s| {
-            base64::prelude::BASE64_STANDARD
-                .decode(s)
-                .map_err(|e| napi::Error::from_reason(format!("failed to decode blindingFactor: {e}")))
-        })
-        .transpose()?
-        .ok_or_else(|| napi::Error::from_reason("missing 'blindingFactor' in options"))?;
-
-    let blinded_messages: Vec<Vec<u8>> = options
-        .get("blindedMessages")
-        .and_then(|v| v.as_array())
-        .ok_or_else(|| napi::Error::from_reason("missing 'blindedMessages' in options"))?
-        .iter()
-        .map(|v| {
-            base64::prelude::BASE64_STANDARD
-                .decode(v.as_str().unwrap_or_default())
-                .map_err(|e| {
-                    napi::Error::from_reason(format!("failed to decode blinded message: {e}"))
-                })
-        })
-        .collect::<napi::Result<_>>()?;
-
-    let nonce = parse_nonce(&options);
-
-    let additional_contexts = parse_contexts(&options);
-
-    let (loader, cr) = create_document_loader(additional_contexts);
-    signatures::derive_proof_holder_bound(
-        &proof_document,
-        &reveal_document,
-        blinding_factor,
-        blinded_messages,
-        nonce,
-        loader,
-        cr,
-    )
-    .await
-    .map_err(|e| napi::Error::from_reason(format!("deriveProofHolderBound failed: {e}")))
+  let blinding_factor = options
+    .get("blindingFactor")
+    .and_then(|v| v.as_str())
+    .map(|s| {
+      base64::prelude::BASE64_STANDARD
+        .decode(s)
+        .map_err(|e| napi::Error::from_reason(format!("failed to decode blindingFactor: {e}")))
+    })
+    .transpose()?
+    .ok_or_else(|| napi::Error::from_reason("missing 'blindingFactor' in options"))?;
+
+  let blinded_messages: Vec<Vec<u8>> = options
+    .get("blindedMessages")
+    .and_then(|v| v.as_array())
+    .ok_or_else(|| napi::Error::from_reason("missing 'blindedMessages' in options"))?
+    .iter()
+    .map(|v| {
+      base64::prelude::BASE64_STANDARD
+        .decode(v.as_str().unwrap_or_default())
+        .map_err(|e| napi::Error::from_reason(format!("failed to decode blinded message: {e}")))
+    })
+    .collect::<napi::Result<_>>()?;
+
+  let nonce = parse_nonce(&options);
+
+  let additional_contexts = parse_contexts(&options);
+
+  let loader = create_document_loader(additional_contexts);
+  signatures::derive_proof_holder_bound(
+    &proof_document,
+    &reveal_document,
+    blinding_factor,
+    blinded_messages,
+    nonce,
+    loader,
+  )
+  .await
+  .map_err(|e| napi::Error::from_reason(format!("deriveProofHolderBound failed: {e}")))
 }

package/src/lib.rs

@@ -3,6 +3,14 @@
 #[macro_use]
 extern crate napi_derive;
 
+// mimalloc gives a sizeable perf win on darwin + linux-gnu (the dominant
+// consumer platforms), but is not compatible with Alpine/musl at runtime
+// (the static-link / TLS model differs). Fall back to the system allocator
+// on musl so Alpine consumers don't regress at startup.
+#[cfg(not(target_env = "musl"))]
+#[global_allocator]
+static GLOBAL: mimalloc::MiMalloc = mimalloc::MiMalloc;
+
 pub mod bbs_2023;
 pub mod bbs_ietf;
 pub mod bls_signatures;

package/test-fixtures/interop/README.md

@@ -0,0 +1,46 @@
+# Cross-stack BBS+ interop fixtures
+
+Fixtures for `vc/js/test_interop.mjs` — the cross-stack interop harness comparing V2 native (Rust `json-ld@0.21.4`) against `jsonld.js@^8.3.3` (the de facto third-party reference). Each fixture is a per-VC-schema test case in the form `<family>/<name>/`.
+
+## Layout
+
+```
+test-fixtures/interop/
+├── _contexts/                            # bundled JSON-LD contexts (see _contexts/README.md)
+├── <family>/<name>/
+│   ├── input.jsonld                      # the VC document
+│   ├── frame.jsonld                      # BBS+-style reveal frame
+│   ├── expected.nq                       # canonized N-Quads from jsonld.js (committed; ground truth)
+│   └── README.md                         # provenance + what this fixture tests
+```
+
+`_<dir>` (underscore-prefixed) directories are excluded from fixture discovery.
+
+## Workflow
+
+**Adding a new fixture:**
+
+1. Create `<family>/<name>/` with `input.jsonld`, `frame.jsonld`, and a brief `README.md` describing provenance.
+2. If the input references a context not yet in `_contexts/`, add it (see `_contexts/README.md`).
+3. Generate ground truth: `cd vc/js && node tools/regen_expected.mjs test-fixtures/interop/<family>/<name>`.
+4. Run the harness: `node test_interop.mjs --check` — if `pass`, commit; if `fail`, see "When the harness fails" below.
+
+**Regenerating after upstream context updates:** `node tools/regen_expected.mjs --all` from `vc/js/`. Re-run `--check` afterwards.
+
+## When the harness fails
+
+Three modes:
+
+- **Regression** (a previously-passing fixture fails): a real V2 native bug. Investigate via `node test_interop.mjs --report` to see the unified diff. Fix in `vc/rs/src/jsonld_v2/frame_native.rs` (or wherever the divergence originates).
+- **Expected fail** (fixture is in `interop-allowlist.json`): no action; the gap is tracked. The reason field + linked GitHub issue document next steps.
+- **Improvement** (an allowlisted fixture starts passing): the harness exits 1 with a "newly passing — please ratchet" message. Remove the allowlist entry and close the linked GitHub issue.
+
+The harness gates `vc-publish` via the `vc-interop-conformance` CI job, so a regression blocks release.
+
+## Related files
+
+- `vc/js/test_interop.mjs` — the harness (`--check`, `--report`)
+- `vc/js/tools/regen_expected.mjs` — ground-truth generator (jsonld.js + URDNA2015, offline document loader)
+- `vc/js/interop-allowlist.json` — `expect_fail` ratchet
+- `vc/js/test-fixtures/interop/_contexts/README.md` — bundled context conventions + Rust sync targets
+- `docs/plans/2026-05-05-sprint-4-phase-a.md` — Phase A implementation plan

package/test-fixtures/interop/_contexts/README.md

@@ -0,0 +1,51 @@
+# Interop fixture contexts
+
+Bundled JSON-LD contexts for the cross-stack interop test harness (`vc/js/test_interop.mjs`) and its ground-truth generator (`vc/js/tools/regen_expected.mjs`).
+
+## Convention
+
+Each `<name>.jsonld` here is loaded by the harness's offline document loader and indexed by its embedded `__url__` marker. Shape:
+
+```json
+{
+  "__url__": "<the URL the input.jsonld references>",
+  "@context": <verbatim copy of the upstream context body>
+}
+```
+
+The harness deletes `__url__` after reading and exposes the rest to JsonLd as a context document.
+
+Files starting with `_` (this `README.md`, etc.) are not loaded — only `*.jsonld` and `*.json` siblings.
+
+## Sync targets
+
+Each bundle here is a hand-copy of a context body. Most mirror a constant in the Rust codebase ("Rust-mirror" bundles); a few mirror an external spec that Nuggets does not issue ("spec-sourced" bundles, e.g. OpenBadges v3 added in Sprint 4 Phase B for cross-stack interop coverage). **When the canonical source updates, this bundle must be updated in lockstep** — otherwise cross-stack interop silently drifts and the harness will start producing false confidence in jsonld.js parity. There is no automated drift check today; this README is the audit trail.
+
+| bundle file | URL | Source |
+|---|---|---|
+| `credentials-v1.jsonld` | `https://www.w3.org/2018/credentials/v1` | Rust-mirror: `vc/rs/src/jsonld/signatures/bbs/data/sample_data.rs::CREDENTIALS_CONTEXT` |
+| `citizenship-v1.jsonld` | `https://w3id.org/citizenship/v1` | Rust-mirror: `vc/rs/src/jsonld/signatures/bbs/data/sample_data.rs::CITIZEN_VOCAB` |
+| `security-bbs-v1.jsonld` | `https://w3id.org/security/bbs/v1` | Rust-mirror: `vc/rs/src/jsonld/signatures/bbs/data/sample_data.rs::BBS` |
+| `identity-v2.jsonld` | `https://schemas.nuggets.life/identityV2.json` | Rust-mirror: `vc/rs/src/document_loader/context/identity_v2.rs::IDENTITY_V2` |
+| `bbs-bound-v1.jsonld` | `https://schemas.nuggets.life/bbsBoundv1.json` | Rust-mirror: `vc/rs/src/document_loader/context/bbs_bound_v1.rs::BBS_BOUND_V1` |
+| `nuggets-identity-v1.jsonld` | `https://schemas.nuggets.life/identity.json` | Rust-mirror: `vc/rs/src/document_loader/context/identity.rs::IDENTITY` |
+| `nuggets-kyb-v1.jsonld` | `https://schemas.nuggets.life/kybV1.json` | Rust-mirror: `vc/rs/src/document_loader/context/kyb.rs::KYB_V1` |
+| `openbadges-v3.jsonld` | `https://purl.imsglobal.org/spec/ob/v3p0/context-3.0.3.json` | Spec-sourced (no Rust mirror): IMS Global OpenBadges v3.0.3 context, retrieved 2026-05-06 from the canonical PURL above. The `https://w3id.org/openbadges/v3` alias currently 302s to a 404 (`https://openbadgespec.org/v3`), so OB v3 fixtures cite the IMS PURL directly. |
+| `essif-schemas-vc-2020-v1.jsonld` | `https://essif.europa.eu/schemas/vc/2020/v1` | Spec-sourced (no Rust mirror): EBSI/ESSIF schemas v1 context as distributed by the EBSI4Austria pilot at `https://github.com/danubetech/ebsi4austria-examples/blob/main/context/essif-schemas-vc-2020-v1.jsonld`, retrieved 2026-05-06. Used by `ebsi/diploma-simple`. |
+| `elm-edc-ap.jsonld` | `http://data.europa.eu/snb/model/context/edc-ap` | Spec-sourced (no Rust mirror): European Learning Model v3 EDC-AP context, retrieved 2026-05-06 from `https://github.com/european-commission-empl/European-Learning-Model/blob/master/rdf/ap/edc/edc-ap-context.jsonld`. The canonical `data.europa.eu` URL currently sits behind an Azure WAF JS challenge (cannot be fetched cleanly with curl/WebFetch); the European Commission's official ELM repo is the verbatim source. Used by `ebsi/diploma-elm`. |
+
+### Bundle classes
+
+- **Rust-mirror** — the upstream-of-record is a Rust constant in this repo. The bundle is a verbatim copy and must be re-synced when the Rust source changes.
+- **Spec-sourced** — the upstream-of-record is an external spec (e.g. OpenBadges v3). Nuggets does not issue these credentials; the bundle exists purely to feed cross-stack interop fixtures. Re-sync when the spec publishes a new revision.
+
+## Adding a new context
+
+When a new fixture references a context not yet bundled here:
+
+1. **Rust-mirror case** — find the canonical body in the Rust codebase (search `vc/rs/src/document_loader/` and `vc/rs/src/jsonld/signatures/bbs/data/`). **Don't network-fetch.**
+   **Spec-sourced case** — fetch the canonical context from the spec's PURL/URL with `curl -sL` and save the body verbatim.
+2. Create `_contexts/<short-name>.jsonld` with `{ "__url__": "<URL>", "@context": <body> }`.
+3. Verify the body is byte-equal to the source (Rust constant or fetched spec body).
+4. Add a row to the table above naming the source (Rust path + constant for mirrors; spec name + retrieval date for spec-sourced).
+5. Re-run `node tools/regen_expected.mjs --all` so all `expected.nq` files account for the new context.