@nuggetslife/vc 0.0.30 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuggetslife/vc",
-  "version": "0.0.30",
+  "version": "0.2.0",
   "main": "index.js",
   "types": "index.d.ts",
   "napi": {
@@ -22,7 +22,8 @@
     "@mattrglobal/jsonld-signatures-bbs": "^1.2.0",
     "@napi-rs/cli": "^2.18.3",
     "@types/node": "^20.14.9",
-    "jsonld": "^8.3.3"
+    "jsonld": "^8.3.3",
+    "jsonld-signatures": "^7.0.0"
   },
   "engines": {
     "node": ">= 10"
@@ -41,11 +42,11 @@
   },
   "packageManager": "yarn@4.3.1",
   "optionalDependencies": {
-    "@nuggetslife/vc-darwin-arm64": "0.0.30",
-    "@nuggetslife/vc-linux-arm64-gnu": "0.0.30",
-    "@nuggetslife/vc-linux-arm64-musl": "0.0.30",
-    "@nuggetslife/vc-linux-x64-gnu": "0.0.30",
-    "@nuggetslife/vc-linux-x64-musl": "0.0.30"
+    "@nuggetslife/vc-darwin-arm64": "0.2.0",
+    "@nuggetslife/vc-linux-arm64-gnu": "0.2.0",
+    "@nuggetslife/vc-linux-arm64-musl": "0.2.0",
+    "@nuggetslife/vc-linux-x64-gnu": "0.2.0",
+    "@nuggetslife/vc-linux-x64-musl": "0.2.0"
   },
   "dependencies": {}
 }

package/scripts/fetch-w3c-tests.sh

@@ -12,6 +12,9 @@ JLD_API_SHA="04a4eb7dc7cbc313f3f5be7ad9a3b06e87741693"
 RDF_CANON_REPO="https://github.com/w3c/rdf-canon.git"
 RDF_CANON_SHA="15619df2fda7a4ca88308733789b6774517f9638"
 
+JLD_FRAMING_REPO="https://github.com/w3c/json-ld-framing.git"
+JLD_FRAMING_SHA="fa228743e890499c35bc61aabf01e44cf5bbc3bc"
+
 mkdir -p tmp-w3c-tests
 cd tmp-w3c-tests
 
@@ -25,4 +28,9 @@ if [ ! -d rdf-canon ]; then
 fi
 (cd rdf-canon && git fetch --depth=1 origin "$RDF_CANON_SHA" && git checkout --detach "$RDF_CANON_SHA")
 
+if [ ! -d json-ld-framing ]; then
+    git clone --filter=blob:none "$JLD_FRAMING_REPO"
+fi
+(cd json-ld-framing && git fetch --depth=1 origin "$JLD_FRAMING_SHA" && git checkout --detach "$JLD_FRAMING_SHA")
+
 echo "W3C suites fetched at pinned SHAs."

package/src/jsonld.rs

@@ -1,12 +1,13 @@
 use serde_json::{json, Value};
+use std::collections::HashMap;
 use std::sync::Arc;
 
 use vc::{
-    document_loader::nuggets::DocumentLoader,
-    jsonld::{self, context_resolver::ContextResolver},
+  document_loader::nuggets::DocumentLoader,
+  jsonld::{self, context_resolver::ContextResolver},
 };
 
-use crate::ld_signatures::loader_from_contexts;
+use crate::ld_signatures::create_document_loader;
 
 /// JSON-LD processor — drop-in replacement for the jsonld.js API.
 ///
@@ -20,159 +21,229 @@ use crate::ld_signatures::loader_from_contexts;
 /// ```
 #[napi]
 pub struct JsonLd {
-    loader: Arc<DocumentLoader>,
-    cr: Arc<ContextResolver>,
+  loader: Arc<DocumentLoader>,
+  cr: Arc<ContextResolver>,
+  additional_contexts: Arc<HashMap<String, Value>>,
+}
+
+impl JsonLd {
+  fn additional_contexts(&self) -> Arc<HashMap<String, Value>> {
+    Arc::clone(&self.additional_contexts)
+  }
 }
 
 #[napi]
 impl JsonLd {
-    /// Create a new JSON-LD processor.
-    ///
-    /// Accepts optional `{ contexts?: Record<string, any> }` to register
-    /// additional URL → document mappings in the document loader (on top
-    /// of the built-in nuggets contexts).
-    #[napi(constructor)]
-    pub fn new(options: Option<Value>) -> Self {
-        let contexts = options.as_ref().and_then(|o| o.get("contexts"));
-        let (loader, cr) = loader_from_contexts(contexts);
-        Self { loader, cr }
+  /// Create a new JSON-LD processor.
+  ///
+  /// Accepts optional `{ contexts?: Record<string, any> }` to register
+  /// additional URL → document mappings in the document loader (on top
+  /// of the built-in nuggets contexts).
+  #[napi(constructor)]
+  pub fn new(options: Option<Value>) -> Self {
+    let additional_contexts: HashMap<String, Value> = options
+      .as_ref()
+      .and_then(|o| o.get("contexts"))
+      .and_then(|v| v.as_object())
+      .map(|obj| obj.iter().map(|(k, v)| (k.clone(), v.clone())).collect())
+      .unwrap_or_default();
+    let (loader, cr) = create_document_loader(additional_contexts.clone());
+    Self {
+      loader,
+      cr,
+      additional_contexts: Arc::new(additional_contexts),
     }
+  }
 
-    /// Expand a JSON-LD document.
-    ///
-    /// `options` can include: `base`, `expandContext`, `keepFreeFloatingNodes`,
-    /// `processingMode`.
-    ///
-    /// Returns an array of expanded JSON-LD objects.
-    #[napi]
-    pub async fn expand(
-        &self,
-        input: Value,
-        options: Option<Value>,
-    ) -> napi::Result<Value> {
-        let opts = options.unwrap_or(json!({}));
-        jsonld::expand(input, self.loader.clone(), self.cr.clone(), opts)
-            .await
-            .map_err(|e| napi::Error::from_reason(format!("expand failed: {e}")))
+  /// Expand a JSON-LD document.
+  ///
+  /// `options` can include: `base`, `expandContext`, `keepFreeFloatingNodes`,
+  /// `processingMode`.
+  ///
+  /// Returns an array of expanded JSON-LD objects.
+  #[napi]
+  pub async fn expand(&self, input: Value, options: Option<Value>) -> napi::Result<Value> {
+    let opts = options.unwrap_or(json!({}));
+    if vc::jsonld_v2::use_v2() {
+      let additional = self.additional_contexts();
+      vc::jsonld_v2::expand_v2_sync(input, &additional, opts)
+        .map_err(|e| napi::Error::from_reason(format!("expand (v2) failed: {e}")))
+    } else {
+      jsonld::expand(input, self.loader.clone(), self.cr.clone(), opts)
+        .await
+        .map_err(|e| napi::Error::from_reason(format!("expand failed: {e}")))
     }
+  }
 
-    /// Compact a JSON-LD document using a context.
-    ///
-    /// `ctx` — the compaction context (object, array, or string URL).
-    /// `options` can include: `base`, `compactArrays`, `graph`,
-    /// `skipExpansion`, `processingMode`.
-    ///
-    /// Returns the compacted JSON-LD object.
-    #[napi]
-    pub async fn compact(
-        &self,
-        input: Value,
-        ctx: Value,
-        options: Option<Value>,
-    ) -> napi::Result<Value> {
-        let opts = options.unwrap_or(json!({}));
-        jsonld::compact_api(input, ctx, self.loader.clone(), self.cr.clone(), opts)
-            .await
-            .map_err(|e| napi::Error::from_reason(format!("compact failed: {e}")))
+  /// Compact a JSON-LD document using a context.
+  ///
+  /// `ctx` — the compaction context (object, array, or string URL).
+  /// `options` can include: `base`, `compactArrays`, `graph`,
+  /// `skipExpansion`, `processingMode`.
+  ///
+  /// Returns the compacted JSON-LD object.
+  #[napi]
+  pub async fn compact(
+    &self,
+    input: Value,
+    ctx: Value,
+    options: Option<Value>,
+  ) -> napi::Result<Value> {
+    let opts = options.unwrap_or(json!({}));
+    if vc::jsonld_v2::use_v2() {
+      let additional = self.additional_contexts();
+      vc::jsonld_v2::compact_v2_sync(input, ctx, &additional, opts)
+        .map_err(|e| napi::Error::from_reason(format!("compact (v2) failed: {e}")))
+    } else {
+      jsonld::compact_api(input, ctx, self.loader.clone(), self.cr.clone(), opts)
+        .await
+        .map_err(|e| napi::Error::from_reason(format!("compact failed: {e}")))
     }
+  }
 
-    /// Flatten a JSON-LD document.
-    ///
-    /// `ctx` — optional context for compacting the flattened result.
-    ///   Pass `null` to get the flattened expanded form.
-    /// `options` can include: `base`, `expandContext`, `processingMode`.
-    ///
-    /// Returns flattened array (no context) or compacted object (with context).
-    #[napi]
-    pub async fn flatten(
-        &self,
-        input: Value,
-        ctx: Option<Value>,
-        options: Option<Value>,
-    ) -> napi::Result<Value> {
-        let opts = options.unwrap_or(json!({}));
-        // Filter out null ctx (JS passes null, Rust expects None)
-        let ctx = ctx.filter(|v| !v.is_null());
-        jsonld::flatten(input, ctx, self.loader.clone(), self.cr.clone(), opts)
-            .await
-            .map_err(|e| napi::Error::from_reason(format!("flatten failed: {e}")))
+  /// Flatten a JSON-LD document.
+  ///
+  /// `ctx` — optional context for compacting the flattened result.
+  ///   Pass `null` to get the flattened expanded form.
+  /// `options` can include: `base`, `expandContext`, `processingMode`.
+  ///
+  /// Returns flattened array (no context) or compacted object (with context).
+  #[napi]
+  pub async fn flatten(
+    &self,
+    input: Value,
+    ctx: Option<Value>,
+    options: Option<Value>,
+  ) -> napi::Result<Value> {
+    let opts = options.unwrap_or(json!({}));
+    // Filter out null ctx (JS passes null, Rust expects None)
+    let ctx = ctx.filter(|v| !v.is_null());
+    if vc::jsonld_v2::use_v2() {
+      let additional = self.additional_contexts();
+      vc::jsonld_v2::flatten_v2_sync(input, ctx, &additional, opts)
+        .map_err(|e| napi::Error::from_reason(format!("flatten (v2) failed: {e}")))
+    } else {
+      jsonld::flatten(input, ctx, self.loader.clone(), self.cr.clone(), opts)
+        .await
+        .map_err(|e| napi::Error::from_reason(format!("flatten failed: {e}")))
     }
+  }
 
-    /// Frame a JSON-LD document.
-    ///
-    /// `frame` — the framing template.
-    /// `options` can include: `base`, `embed`, `explicit`, `requireAll`,
-    /// `omitDefault`, `omitGraph`, `processingMode`.
-    ///
-    /// Returns the framed JSON-LD object.
-    #[napi]
-    pub async fn frame(
-        &self,
-        input: Value,
-        frame: Value,
-        options: Option<Value>,
-    ) -> napi::Result<Value> {
-        let opts = options.unwrap_or(json!({}));
-        jsonld::frame(input, frame, self.loader.clone(), self.cr.clone(), opts)
-            .await
-            .map_err(|e| napi::Error::from_reason(format!("frame failed: {e}")))
+  /// Frame a JSON-LD document.
+  ///
+  /// `frame` — the framing template.
+  /// `options` can include: `base`, `embed`, `explicit`, `requireAll`,
+  /// `omitDefault`, `omitGraph`, `processingMode`.
+  ///
+  /// Returns the framed JSON-LD object.
+  #[napi]
+  pub async fn frame(
+    &self,
+    input: Value,
+    frame: Value,
+    options: Option<Value>,
+  ) -> napi::Result<Value> {
+    let opts = options.unwrap_or(json!({}));
+    if vc::jsonld_v2::use_v2() {
+      // Sprint 3 Phase D cutover: V2 frame is always the native typed-tree
+      // walker. CLIENTFFI_FRAME_NATIVE / CLIENTFFI_FRAME_FAST flags are no
+      // longer consulted — frame_v2 / frame_v2_fast public APIs were
+      // retired in this commit.
+      let loader = self.loader.clone();
+      let cr = self.cr.clone();
+      let additional = self.additional_contexts();
+      let join = tokio::task::spawn_blocking(move || {
+        vc::jsonld_v2::frame_native_sync(input, frame, loader, cr, opts, &additional)
+          .map_err(|e| napi::Error::from_reason(format!("frame (native) failed: {e}")))
+      });
+      join
+        .await
+        .map_err(|e| napi::Error::from_reason(format!("frame (v2) join: {e}")))?
+    } else {
+      jsonld::frame(input, frame, self.loader.clone(), self.cr.clone(), opts)
+        .await
+        .map_err(|e| napi::Error::from_reason(format!("frame failed: {e}")))
     }
+  }
 
-    /// Convert a JSON-LD document to an RDF dataset.
-    ///
-    /// `options` can include: `base`, `expandContext`, `skipExpansion`,
-    /// `format` (`"application/n-quads"` for string output), `processingMode`.
-    ///
-    /// Returns an array of quads or an N-Quads string (depending on `format`).
-    #[napi(js_name = "toRDF")]
-    pub async fn to_rdf(
-        &self,
-        input: Value,
-        options: Option<Value>,
-    ) -> napi::Result<Value> {
-        let opts = options.unwrap_or(json!({}));
-        jsonld::to_rdf(input, self.loader.clone(), self.cr.clone(), opts)
-            .await
-            .map_err(|e| napi::Error::from_reason(format!("toRDF failed: {e}")))
+  /// Convert a JSON-LD document to an RDF dataset.
+  ///
+  /// `options` can include: `base`, `expandContext`, `skipExpansion`,
+  /// `format` (`"application/n-quads"` for string output), `processingMode`.
+  ///
+  /// Returns an array of quads or an N-Quads string (depending on `format`).
+  #[napi(js_name = "toRDF")]
+  pub async fn to_rdf(&self, input: Value, options: Option<Value>) -> napi::Result<Value> {
+    let opts = options.unwrap_or(json!({}));
+    // v2 only produces N-Quads string output. If caller expects
+    // a quads-array (default when format is omitted), fall back to v1.
+    let wants_nquads = opts
+      .get("format")
+      .and_then(|v| v.as_str())
+      .map(|s| s == "application/n-quads")
+      .unwrap_or(false);
+    if vc::jsonld_v2::use_v2() && wants_nquads {
+      let additional = self.additional_contexts();
+      let nquads = vc::jsonld_v2::to_nquads_v2_sync(input, &additional, opts)
+        .map_err(|e| napi::Error::from_reason(format!("toRDF (v2) failed: {e}")))?;
+      Ok(Value::String(nquads))
+    } else {
+      jsonld::to_rdf(input, self.loader.clone(), self.cr.clone(), opts)
+        .await
+        .map_err(|e| napi::Error::from_reason(format!("toRDF failed: {e}")))
     }
+  }
 
-    /// Convert an RDF dataset to a JSON-LD document.
-    ///
-    /// `dataset` — N-Quads string or array of quads.
-    /// `options` can include: `useRdfType`, `useNativeTypes`, `rdfDirection`.
-    ///
-    /// Returns an array of JSON-LD objects.
-    #[napi(js_name = "fromRDF")]
-    pub fn from_rdf(&self, dataset: Value, options: Option<Value>) -> napi::Result<Value> {
-        let opts = options.unwrap_or(json!({}));
-        jsonld::from_rdf_api(dataset, opts)
-            .map_err(|e| napi::Error::from_reason(format!("fromRDF failed: {e}")))
-    }
+  /// Convert an RDF dataset to a JSON-LD document.
+  ///
+  /// `dataset` — N-Quads string or array of quads.
+  /// `options` can include: `useRdfType`, `useNativeTypes`, `rdfDirection`.
+  ///
+  /// Returns an array of JSON-LD objects.
+  #[napi(js_name = "fromRDF")]
+  pub fn from_rdf(&self, dataset: Value, options: Option<Value>) -> napi::Result<Value> {
+    let opts = options.unwrap_or(json!({}));
+    jsonld::from_rdf_api(dataset, opts)
+      .map_err(|e| napi::Error::from_reason(format!("fromRDF failed: {e}")))
+  }
 
-    /// Canonize (normalize) a JSON-LD document.
-    ///
-    /// `options` can include: `base`, `expandContext`, `skipExpansion`,
-    /// `inputFormat` (`"application/n-quads"`), `format`, `algorithm`,
-    /// `processingMode`.
-    ///
-    /// Returns the canonical N-Quads string.
-    #[napi]
-    pub async fn canonize(
-        &self,
-        input: Value,
-        options: Option<Value>,
-    ) -> napi::Result<Value> {
-        let mut opts = options.unwrap_or(json!({}));
-        // Defaults matching JS jsonld.js canonize()
-        if opts.get("algorithm").is_none() {
-            opts["algorithm"] = json!("RDFC-1.0");
-        }
-        if opts.get("format").is_none() {
-            opts["format"] = json!("application/n-quads");
-        }
-        let result = jsonld::canonize(input, self.loader.clone(), self.cr.clone(), opts)
-            .await
-            .map_err(|e| napi::Error::from_reason(format!("canonize failed: {e}")))?;
-        Ok(Value::String(result))
+  /// Canonize (normalize) a JSON-LD document.
+  ///
+  /// `options` can include: `base`, `expandContext`, `skipExpansion`,
+  /// `inputFormat` (`"application/n-quads"`), `format`, `algorithm`,
+  /// `processingMode`.
+  ///
+  /// Returns the canonical N-Quads string.
+  #[napi]
+  pub async fn canonize(&self, input: Value, options: Option<Value>) -> napi::Result<Value> {
+    let mut opts = options.unwrap_or(json!({}));
+    // Defaults matching JS jsonld.js canonize()
+    if opts.get("algorithm").is_none() {
+      opts["algorithm"] = json!("RDFC-1.0");
+    }
+    if opts.get("format").is_none() {
+      opts["format"] = json!("application/n-quads");
     }
+    let input_is_nquads = opts
+      .get("inputFormat")
+      .and_then(|v| v.as_str())
+      .map(|s| s == "application/n-quads")
+      .unwrap_or(false);
+    let result = if vc::jsonld_v2::use_v2() && !input_is_nquads {
+      let additional = self.additional_contexts();
+      vc::jsonld_v2::canonize_v2_sync(
+        input,
+        &additional,
+        self.loader.clone(),
+        self.cr.clone(),
+        opts,
+      )
+      .map_err(|e| napi::Error::from_reason(format!("canonize (v2) failed: {e}")))?
+    } else {
+      jsonld::canonize(input, self.loader.clone(), self.cr.clone(), opts)
+        .await
+        .map_err(|e| napi::Error::from_reason(format!("canonize failed: {e}")))?
+    };
+    Ok(Value::String(result))
+  }
 }

package/src/ld_signatures.rs

@@ -28,18 +28,27 @@ use vc::{
 };
 
 /// 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);
+    ctx.extend(additional_contexts.clone());
 
     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 loader = Arc::new(DocumentLoader::with_additional_contexts(
+        ctx,
+        additional_contexts,
+        resolver,
+        opts,
+    ));
     let cr = Arc::new(ContextResolver::new(LruCache::new(
         NonZeroUsize::new(10).unwrap(),
     )));

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.