@nuggetslife/vc 0.0.30 → 0.2.0

package/test_interop_smoke.mjs

@@ -0,0 +1,388 @@
+#!/usr/bin/env node
+// Cross-stack BBS+ sign-verify smoke harness (Sprint 4 Phase D).
+//
+// Layered on top of the parity harness (test_interop.mjs): the parity gate
+// ensures frame + canonize byte-equality between V2 native and jsonld.js;
+// THIS gate ensures a full cryptographic round-trip across the two stacks.
+//
+// For each fixture × direction:
+//   1. V2 native sign  → @mattrglobal/jsonld-signatures-bbs verify
+//   2. @mattrglobal/jsonld-signatures-bbs sign  → V2 native verify
+// Both directions must succeed (verified: true) for the fixture to "pass smoke".
+//
+// Usage:
+//   node test_interop_smoke.mjs --check     (CI default; exits 1 on any
+//                                            non-allowlisted failure)
+//   node test_interop_smoke.mjs --report    (local triage; prints diagnostic
+//                                            per failure, always exits 0)
+//
+// Fixture subset rationale:
+//   The corpus is 9 fixtures across 6 families. After clientffi#69 (Phase E
+//   canonize_dispatch fix — mirror of the Phase A frame_native hotfix), the
+//   smoke harness covers all 9: caller-registered contexts now thread
+//   through the V2 BBS+ sign / verify chain, so OB v3 / EBSI / VP fixtures
+//   that reference spec-sourced (non-bundled) contexts can now round-trip.
+//
+//   Included (9):
+//     - w3c-vc-v1/permanent-resident-card    — canonical W3C VC v1 + BBS+
+//     - idv2/full-disclosure                 — Nuggets identity-v2 (post-#56)
+//     - nuggets/identity-v1                  — Nuggets identity-v1 (post-#63)
+//     - nuggets/kyb-v1                       — Nuggets kyb-v1 (post-#65)
+//     - vp/single-vc-wrap                    — VP wrapping a VC (post-#66)
+//     - openbadges-v3/basic-achievement      — OB v3 spec context
+//     - openbadges-v3/with-allowed-values    — OB v3 spec context
+//     - ebsi/diploma-simple                  — EBSI essif spec context
+//     - ebsi/diploma-elm                     — EBSI ELM (V2-pinned, see #61)
+//
+// Hardcoded BBS+ keypair: `did:example:489398593#test`, the same keypair
+// used by the existing test infrastructure (vc/js/test-data/keyPair.json,
+// matching vc/rs/src/jsonld/signatures/bbs/data/sample_data.rs::KEY_PAIR).
+
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+import { ldSign, ldVerify } from './index.js';
+
+const require = createRequire(import.meta.url);
+const { Bls12381G2KeyPair } = require('@mattrglobal/bls12381-key-pair');
+const { BbsBlsSignature2020 } = require('@mattrglobal/jsonld-signatures-bbs');
+const jsigs = require('jsonld-signatures');
+const { extendContextLoader, purposes } = jsigs;
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const fixturesRoot = resolve(__dirname, 'test-fixtures', 'interop');
+
+const args = process.argv.slice(2);
+const checkMode = args.includes('--check');
+const reportMode = args.includes('--report');
+if (!checkMode && !reportMode) {
+  console.error('Usage: test_interop_smoke.mjs [--check | --report]');
+  process.exit(2);
+}
+
+const allowlistPath = resolve(__dirname, 'interop-smoke-allowlist.json');
+const allowlist = existsSync(allowlistPath)
+  ? JSON.parse(readFileSync(allowlistPath, 'utf8'))
+  : { expect_fail: [] };
+const expectFail = new Set((allowlist.expect_fail || []).map((e) => e.fixture));
+
+// All corpus fixtures included in the smoke gate — see header rationale.
+const SMOKE_FIXTURES = [
+  'w3c-vc-v1/permanent-resident-card',
+  'idv2/full-disclosure',
+  'nuggets/identity-v1',
+  'nuggets/kyb-v1',
+  'vp/single-vc-wrap',
+  'openbadges-v3/basic-achievement',
+  'openbadges-v3/with-allowed-values',
+  'ebsi/diploma-simple',
+  'ebsi/diploma-elm',
+];
+
+// BBS+ keypair — `did:example:489398593#test`. Single source of truth is
+// vc/js/test-data/keyPair.json, which mirrors
+// vc/rs/src/jsonld/signatures/bbs/data/sample_data.rs::KEY_PAIR. The on-disk
+// file omits `type` (consumed by other tests that don't need it); we patch
+// it in here so the BBS+ suites resolve the verification method correctly.
+const KEYPAIR_PATH = resolve(__dirname, 'test-data', 'keyPair.json');
+const KEYPAIR_JSON = {
+  ...JSON.parse(readFileSync(KEYPAIR_PATH, 'utf8')),
+  type: 'Bls12381G2Key2020',
+};
+
+const CONTROLLER_DOC = {
+  '@context': 'https://w3id.org/security/v2',
+  id: KEYPAIR_JSON.controller,
+  assertionMethod: [KEYPAIR_JSON.id],
+};
+
+// Load offline interop contexts the same way test_interop.mjs does.
+function loadOfflineContexts() {
+  const dir = join(fixturesRoot, '_contexts');
+  const out = {};
+  if (!existsSync(dir)) return out;
+  for (const f of readdirSync(dir)) {
+    if (!f.endsWith('.jsonld') && !f.endsWith('.json')) continue;
+    const doc = JSON.parse(readFileSync(join(dir, f), 'utf8'));
+    if (!doc.__url__) continue;
+    const url = doc.__url__;
+    const copy = JSON.parse(JSON.stringify(doc));
+    delete copy.__url__;
+    out[url] = copy;
+  }
+  return out;
+}
+
+// Augment with the contexts the BBS+ suites resolve at sign/verify time:
+// the keypair URL itself, the controller doc, and the JWS suite context the
+// `@mattrglobal/jsonld-signatures-bbs` `getVerificationMethod` framing pulls
+// in. `jsonld-signatures` already bundles `security/v1` + `security/v2`
+// (via its `extendContextLoader`), so we don't need to re-add those.
+function buildContexts(offline) {
+  const suiteContextPath = resolve(__dirname, 'test-data', 'suiteContext.json');
+  const suiteContext = JSON.parse(readFileSync(suiteContextPath, 'utf8'));
+  return {
+    ...offline,
+    [KEYPAIR_JSON.id]: KEYPAIR_JSON,
+    [KEYPAIR_JSON.controller]: CONTROLLER_DOC,
+    'https://w3id.org/security/suites/jws-2020/v1': suiteContext,
+  };
+}
+
+function buildJsigsLoader(contextMap) {
+  const loader = (url) => {
+    const doc = contextMap[url];
+    if (doc) return { contextUrl: null, document: doc, documentUrl: url };
+    throw new Error(`Smoke harness: unbundled context requested: ${url}`);
+  };
+  return extendContextLoader(loader);
+}
+
+// Strip an existing proof if present (some fixtures may carry one). For the
+// smoke harness we always sign fresh.
+function stripProof(doc) {
+  const copy = JSON.parse(JSON.stringify(doc));
+  delete copy.proof;
+  return copy;
+}
+
+// All current smoke fixtures are VCs — no wrapper unwrapping needed; we
+// just strip any incidental embedded proof before signing.
+function unwrapForSigning(_fixtureId, doc) {
+  return stripProof(doc);
+}
+
+// Some inputs don't carry the BBS+ context — V2 ldSign auto-adds it; we
+// ensure jsonld-signatures-bbs sees it the same way by injecting it before
+// calling sign. (The suite would otherwise call its own `ensureSuiteContext`
+// which mutates the input but produces an identical effect.)
+function ensureBbsContext(doc) {
+  const BBS_URL = 'https://w3id.org/security/bbs/v1';
+  const ctx = doc['@context'];
+  if (!ctx) {
+    doc['@context'] = [BBS_URL];
+    return doc;
+  }
+  if (Array.isArray(ctx)) {
+    if (!ctx.includes(BBS_URL)) doc['@context'] = [...ctx, BBS_URL];
+    return doc;
+  }
+  // string or object
+  doc['@context'] = [ctx, BBS_URL];
+  return doc;
+}
+
+async function v2Sign(input, contexts) {
+  return await ldSign({
+    document: input,
+    keyPair: KEYPAIR_JSON,
+    contexts,
+  });
+}
+
+async function v2Verify(signedDoc, contexts) {
+  return await ldVerify({
+    document: signedDoc,
+    contexts,
+  });
+}
+
+async function mattrSign(input, contexts) {
+  const keyPair = await Bls12381G2KeyPair.from({
+    id: KEYPAIR_JSON.id,
+    controller: KEYPAIR_JSON.controller,
+    publicKeyBase58: KEYPAIR_JSON.publicKeyBase58,
+    privateKeyBase58: KEYPAIR_JSON.privateKeyBase58,
+  });
+  const suite = new BbsBlsSignature2020({ key: keyPair });
+  const documentLoader = buildJsigsLoader(contexts);
+  // Mutate-safe: ensureBbsContext is applied before suite.sign so that
+  // expansion has the same vocabulary V2 ldSign would have used.
+  const docToSign = ensureBbsContext(JSON.parse(JSON.stringify(input)));
+  return await jsigs.sign(docToSign, {
+    suite,
+    purpose: new purposes.AssertionProofPurpose(),
+    documentLoader,
+  });
+}
+
+async function mattrVerify(signedDoc, contexts) {
+  const documentLoader = buildJsigsLoader(contexts);
+  const result = await jsigs.verify(signedDoc, {
+    suite: new BbsBlsSignature2020(),
+    purpose: new purposes.AssertionProofPurpose(),
+    documentLoader,
+  });
+  return result;
+}
+
+function summariseError(err) {
+  if (!err) return 'unknown';
+  if (typeof err === 'string') return err;
+  if (err.message) return err.message;
+  if (err.errors && err.errors.length) {
+    return err.errors.map((e) => e.message || String(e)).join('; ');
+  }
+  return String(err);
+}
+
+async function runDirection(directionId, signFn, verifyFn, input, contexts) {
+  let signed;
+  try {
+    signed = await signFn(input, contexts);
+  } catch (err) {
+    return { direction: directionId, status: 'error', stage: 'sign', error: summariseError(err) };
+  }
+  let verifyResult;
+  try {
+    verifyResult = await verifyFn(signed, contexts);
+  } catch (err) {
+    return { direction: directionId, status: 'error', stage: 'verify', error: summariseError(err) };
+  }
+  if (verifyResult && verifyResult.verified === true) {
+    return { direction: directionId, status: 'pass' };
+  }
+  return {
+    direction: directionId,
+    status: 'fail',
+    stage: 'verify',
+    error: summariseError(verifyResult && verifyResult.error),
+  };
+}
+
+async function runFixture(fixture, contexts) {
+  const inputPath = join(fixture.dir, 'input.jsonld');
+  if (!existsSync(inputPath)) {
+    return { id: fixture.id, status: 'skip', reason: 'missing input.jsonld' };
+  }
+  const raw = JSON.parse(readFileSync(inputPath, 'utf8'));
+  const input = unwrapForSigning(fixture.id, raw);
+
+  const v2ToMattr = await runDirection(
+    'v2->jsonld',
+    v2Sign,
+    mattrVerify,
+    input,
+    contexts,
+  );
+  const mattrToV2 = await runDirection(
+    'jsonld->v2',
+    mattrSign,
+    v2Verify,
+    input,
+    contexts,
+  );
+
+  const overall =
+    v2ToMattr.status === 'pass' && mattrToV2.status === 'pass'
+      ? 'pass'
+      : 'fail';
+
+  return {
+    id: fixture.id,
+    status: overall,
+    directions: { v2ToMattr, mattrToV2 },
+  };
+}
+
+async function main() {
+  const offline = loadOfflineContexts();
+  const contexts = buildContexts(offline);
+
+  const fixtures = SMOKE_FIXTURES.map((id) => ({
+    id,
+    dir: join(fixturesRoot, ...id.split('/')),
+  }));
+
+  const results = [];
+  for (const fx of fixtures) {
+    process.stderr.write(`  smoke ${fx.id}…\n`);
+    results.push(await runFixture(fx, contexts));
+  }
+
+  const pass = results.filter((r) => r.status === 'pass').length;
+  const fail = results.filter((r) => r.status === 'fail').length;
+  const skip = results.filter((r) => r.status === 'skip').length;
+
+  console.log(`\n========== INTEROP SMOKE ==========`);
+  console.log(`pass:  ${pass}`);
+  console.log(`fail:  ${fail}`);
+  console.log(`skip:  ${skip}`);
+
+  // Per-fixture results table
+  console.log(`\nfixture                                    | v2->jsonld | jsonld->v2 | overall`);
+  console.log(`-------------------------------------------+------------+------------+--------`);
+  for (const r of results) {
+    const v2j = r.directions ? r.directions.v2ToMattr.status : '-';
+    const jv2 = r.directions ? r.directions.mattrToV2.status : '-';
+    const id = r.id.padEnd(42);
+    console.log(`${id} | ${v2j.padEnd(10)} | ${jv2.padEnd(10)} | ${r.status}`);
+  }
+
+  const regressions = [];
+  const improvements = [];
+  const expectedFails = [];
+  const skips = [];
+  for (const r of results) {
+    if (r.status === 'pass') {
+      if (expectFail.has(r.id)) improvements.push(r);
+    } else if (r.status === 'fail') {
+      if (expectFail.has(r.id)) expectedFails.push(r);
+      else regressions.push(r);
+    } else if (r.status === 'skip') {
+      skips.push(r);
+    }
+  }
+
+  if (reportMode) {
+    for (const r of [...regressions, ...expectedFails]) {
+      console.log(`\n--- ${r.id} (${r.status}) ---`);
+      if (r.directions) {
+        for (const d of [r.directions.v2ToMattr, r.directions.mattrToV2]) {
+          if (d.status === 'pass') continue;
+          console.log(`  [${d.direction}] ${d.status} @ ${d.stage}: ${d.error}`);
+        }
+      }
+    }
+    console.log(
+      `\n[--report] ${regressions.length} divergence(s); ${expectedFails.length} expected-fail; ${improvements.length} improvement(s); ${skips.length} skip(s).`,
+    );
+    process.exit(0);
+  }
+
+  // --check mode
+  if (improvements.length) {
+    console.log(`\n${improvements.length} fixture(s) newly passing — please ratchet interop-smoke-allowlist.json:`);
+    for (const r of improvements) console.log(`  + ${r.id}`);
+    process.exit(1);
+  }
+  if (regressions.length) {
+    console.log(`\n${regressions.length} REGRESSION(S):`);
+    for (const r of regressions) {
+      console.log(`  - ${r.id}`);
+      if (r.directions) {
+        for (const d of [r.directions.v2ToMattr, r.directions.mattrToV2]) {
+          if (d.status === 'pass') continue;
+          console.log(`      [${d.direction}] ${d.status} @ ${d.stage}: ${d.error}`);
+        }
+      }
+    }
+    process.exit(1);
+  }
+  if (skips.length) {
+    console.log(`\n${skips.length} skipped fixture(s):`);
+    for (const r of skips) console.log(`  ! ${r.id}: ${r.reason}`);
+    process.exit(1);
+  }
+  console.log(
+    `\nAll smoke fixtures round-trip cleanly.${
+      expectedFails.length ? ' (' + expectedFails.length + ' tracked expect-fail.)' : ''
+    }`,
+  );
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

package/test_jsonld_crossverify.mjs

@@ -135,7 +135,10 @@ test('cross-verify: flatten(inputDocument, null) matches JS reference', async ()
     const napiResult = await proc.flatten(inputDocument, null);
     const jsResult = await jsonld.flatten(inputDocument, null, { documentLoader });
 
-    assert.deepStrictEqual(napiResult, jsResult);
+    // Flatten without compaction returns an unordered set of node objects
+    // (each keyed by @id). Sort by @id before comparing.
+    const sortById = arr => [...arr].sort((a, b) => String(a['@id'] || '').localeCompare(String(b['@id'] || '')));
+    assert.deepStrictEqual(sortById(napiResult), sortById(jsResult));
 });
 
 
@@ -171,7 +174,10 @@ test('cross-verify: toRDF(inputDocument, n-quads) matches JS reference', async (
     const napiResult = await proc.toRDF(inputDocument, { format: 'application/n-quads' });
     const jsResult = await jsonld.toRDF(inputDocument, { documentLoader, format: 'application/n-quads' });
 
-    assert.strictEqual(napiResult, jsResult);
+    // toRDF triple order is implementation-defined (RDFC-1.0 normalises it later).
+    // Compare as a set: split into lines, drop empties, sort.
+    const norm = s => s.split('\n').filter(l => l.length).sort().join('\n');
+    assert.strictEqual(norm(napiResult), norm(jsResult));
 });
 
 

package/test_w3c_conformance.mjs

@@ -32,6 +32,7 @@ const updateBaseline = flag('--update');
 
 const TESTS_ROOT = resolve(__dirname, 'tmp-w3c-tests');
 const JLD_TESTS = join(TESTS_ROOT, 'json-ld-api', 'tests');
+const JLD_FRAMING_TESTS = join(TESTS_ROOT, 'json-ld-framing', 'tests');
 const RDFC_TESTS = join(TESTS_ROOT, 'rdf-canon', 'tests');
 const JLD_BASE = 'https://w3c.github.io/json-ld-api/tests/';
 const BASELINE_PATH = join(__dirname, 'w3c-baseline.json');
@@ -70,6 +71,7 @@ function preloadJldContexts() {
         }
     }
     walk(JLD_TESTS, '');
+    if (existsSync(JLD_FRAMING_TESTS)) walk(JLD_FRAMING_TESTS, '');
     return ctxs;
 }
 
@@ -84,6 +86,25 @@ const normNQuads = (s) => typeof s === 'string'
     ? s.split('\n').map(l => l.trim()).filter(Boolean).sort().join('\n')
     : s;
 
+// W3C toRdf expected fixtures contain post-URDNA2015 blank-node labels
+// (e.g. `_:c14n0`), but the spec itself defines toRdf as producing
+// pre-canonical labels (e.g. `_:b0`). jsonld.js exhibits the same
+// pre-canonical output. To compare semantically we run URDNA2015 on both
+// sides before string-matching. Falls back to normNQuads if either side
+// can't be canonicalized (so a bug in the processor still surfaces).
+const canonProc = new JsonLd();
+async function nquadsEqual(got, expected) {
+    if (typeof got !== 'string' || typeof expected !== 'string') return false;
+    try {
+        const opts = { algorithm: 'URDNA2015', inputFormat: 'application/n-quads', format: 'application/n-quads' };
+        const a = await canonProc.canonize(got, opts);
+        const b = await canonProc.canonize(expected, opts);
+        return a === b;
+    } catch {
+        return normNQuads(got) === normNQuads(expected);
+    }
+}
+
 const DENYLIST_PATH = join(__dirname, 'w3c-denylist.json');
 let DENYLIST = {};
 if (existsSync(DENYLIST_PATH)) {
@@ -144,10 +165,18 @@ async function runJld(algo, methodName) {
         const opt = entry.option || {};
         const callOpts = { base: opt.base || inputUrl };
         if (opt.processingMode) callOpts.processingMode = opt.processingMode;
+        else if (opt.specVersion) callOpts.processingMode = opt.specVersion;
         if (opt.expandContext) {
             const ctxUrl = JLD_BASE + opt.expandContext;
             callOpts.expandContext = contexts[ctxUrl] || ctxUrl;
         }
+        // toRdf-specific options from W3C test entries
+        if (opt.rdfDirection) callOpts.rdfDirection = opt.rdfDirection;
+        if (opt.produceGeneralizedRdf != null) callOpts.produceGeneralizedRdf = opt.produceGeneralizedRdf;
+        if (opt.compactArrays != null) callOpts.compactArrays = opt.compactArrays;
+        // fromRDF-specific options
+        if (opt.useNativeTypes != null) callOpts.useNativeTypes = opt.useNativeTypes;
+        if (opt.useRdfType != null) callOpts.useRdfType = opt.useRdfType;
 
         try {
             const input = methodName === 'fromRDF' ? loadText(inputPath) : loadJson(inputPath);
@@ -172,7 +201,7 @@ async function runJld(algo, methodName) {
             const expected = methodName === 'toRDF' ? loadText(expectPath) : loadJson(expectPath);
 
             const ok = methodName === 'toRDF'
-                ? normNQuads(napiResult) === normNQuads(expected)
+                ? await nquadsEqual(napiResult, expected)
                 : jsonEqual(napiResult, expected);
             record(algo, id, ok ? 'pass' : 'fail');
         } catch (e) {
@@ -229,20 +258,64 @@ async function runOnce(algo) {
     else if (algo === 'flatten') await runJld('flatten', 'flatten');
     else if (algo === 'toRdf') await runJld('toRdf', 'toRDF');
     else if (algo === 'fromRdf') await runJld('fromRdf', 'fromRDF');
+    else if (algo === 'frame') await runFraming();
 }
 
+async function runFraming() {
+    const manifestPath = join(JLD_FRAMING_TESTS, 'frame-manifest.jsonld');
+    if (!existsSync(manifestPath)) return;
+    const manifest = loadJson(manifestPath);
+    const contexts = preloadJldContexts();
+    const proc = new JsonLd({ contexts });
+    let seen = 0;
+    for (const entry of manifest.sequence) {
+        const types = Array.isArray(entry['@type']) ? entry['@type'] : [entry['@type']];
+        if (!types.includes('jld:PositiveEvaluationTest') && !types.includes('jld:NegativeEvaluationTest')) continue;
+        const id = entry['@id'];
+        if (isDenied('frame', id)) continue;
+        if (!isInCheckScope('frame', id)) continue;
+        seen += 1;
+        if (seen % PROGRESS_EVERY === 0) process.stderr.write(`  frame: ${seen} tests processed\n`);
+        if (!entry.input || !entry.frame) { record('frame', id, 'err'); continue; }
+        const inputPath = join(JLD_FRAMING_TESTS, entry.input);
+        const framePath = join(JLD_FRAMING_TESTS, entry.frame);
+        const expectPath = entry.expect ? join(JLD_FRAMING_TESTS, entry.expect) : null;
+        if (!existsSync(inputPath) || !existsSync(framePath)) { record('frame', id, 'err'); continue; }
+        const opt = entry.option || {};
+        const inputUrl = 'https://w3c.github.io/json-ld-framing/tests/' + entry.input;
+        const callOpts = { base: opt.base || inputUrl };
+        if (opt.processingMode) callOpts.processingMode = opt.processingMode;
+        else if (opt.specVersion) callOpts.processingMode = opt.specVersion;
+        if (opt.omitGraph != null) callOpts.omitGraph = opt.omitGraph;
+        if (opt.requireAll != null) callOpts.requireAll = opt.requireAll;
+        try {
+            const input = loadJson(inputPath);
+            const frame = loadJson(framePath);
+            const napiResult = await withTimeout(proc.frame(input, frame, callOpts), id);
+            if (!expectPath || !existsSync(expectPath)) { record('frame', id, 'err'); continue; }
+            const expected = loadJson(expectPath);
+            record('frame', id, jsonEqual(napiResult, expected) ? 'pass' : 'fail');
+        } catch (e) {
+            const isTimeout = e && /^timeout:/.test(e.message || '');
+            record('frame', id, isTimeout ? 'err' : 'err');
+        }
+    }
+}
+
+
 async function main() {
     if (!existsSync(JLD_TESTS) || !existsSync(RDFC_TESTS)) {
         console.error('W3C test suites not found at ' + TESTS_ROOT);
         console.error('Run: vc/js/scripts/fetch-w3c-tests.sh');
         process.exit(2);
     }
-    // flatten and toRdf are not in the default run because clientffi has
-    // Rust-level deadlocks in those algos. Pass --only flatten or --only toRdf
-    // to opt in when investigating. They'll move into the default list once
-    // their hangs are fixed.
-    const algos = ['canonize', 'fromRdf', 'expand', 'compact'];
-    const allAlgos = ['expand', 'compact', 'flatten', 'toRdf', 'fromRdf', 'canonize'];
+    // flatten and toRdf are gated by V2: the v1 path has Rust-level deadlocks
+    // (sync block_on bridging into tokio::sync locks in the document loader and
+    // node_map). The v2 path (jsonld_v2::flatten_v2 / to_nquads_v2) uses a
+    // pre-resolved HashMap loader with no tokio sync primitives and runs the
+    // suite without hangs, so it is included in the default list.
+    const algos = ['canonize', 'fromRdf', 'expand', 'compact', 'flatten', 'toRdf', 'frame'];
+    const allAlgos = ['expand', 'compact', 'flatten', 'toRdf', 'fromRdf', 'canonize', 'frame'];
     if (onlyArg && !allAlgos.includes(onlyArg)) {
         console.error(`Invalid --only value: ${onlyArg}. Expected one of: ${allAlgos.join(', ')}`);
         process.exit(2);

package/tools/regen_expected.mjs

@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+// Regenerate `expected.nq` for one or more interop fixtures using jsonld.js
+// (the third-party reference). The harness in `test_interop.mjs` then asserts
+// V2 native produces byte-equal output. Never hand-edit `expected.nq`.
+//
+// Usage:
+//   node tools/regen_expected.mjs <fixture-dir> [<fixture-dir>...]
+//   node tools/regen_expected.mjs --all
+//
+// Examples:
+//   node tools/regen_expected.mjs test-fixtures/interop/w3c-vc-v1/permanent-resident-card
+//   node tools/regen_expected.mjs --all
+
+import { readFileSync, writeFileSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { resolve, dirname, join, relative } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import jsonld from 'jsonld';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(__dirname, '..');
+const fixturesRoot = resolve(repoRoot, 'test-fixtures', 'interop');
+
+const args = process.argv.slice(2);
+if (args.length === 0) {
+  console.error('Usage: regen_expected.mjs <fixture-dir>... | --all');
+  process.exit(2);
+}
+
+// Build the offline document loader from the fixtures' contexts. We don't
+// fetch anything from the network — every context referenced by a fixture
+// must resolve from the bundled `vc/js/test-fixtures/interop/_contexts/` dir
+// or from inline contexts (i.e. embedded `@context` objects).
+const contextDir = resolve(fixturesRoot, '_contexts');
+const offlineContexts = {};
+if (existsSync(contextDir)) {
+  for (const f of readdirSync(contextDir)) {
+    if (!f.endsWith('.jsonld') && !f.endsWith('.json')) continue;
+    const doc = JSON.parse(readFileSync(join(contextDir, f), 'utf8'));
+    const url = doc.__url__;
+    if (!url) {
+      console.error(`context ${f} missing __url__ marker`);
+      process.exit(2);
+    }
+    delete doc.__url__;
+    offlineContexts[url] = doc;
+  }
+}
+
+const documentLoader = async (url) => {
+  if (!offlineContexts[url]) {
+    throw new Error(`offline loader: unknown context ${url}`);
+  }
+  return { contextUrl: null, document: offlineContexts[url], documentUrl: url };
+};
+
+async function regen(fixtureDir) {
+  const inputPath = join(fixtureDir, 'input.jsonld');
+  const framePath = join(fixtureDir, 'frame.jsonld');
+  const expectedPath = join(fixtureDir, 'expected.nq');
+  if (!existsSync(inputPath) || !existsSync(framePath)) {
+    console.error(`skipping ${fixtureDir}: missing input.jsonld or frame.jsonld`);
+    return false;
+  }
+  const input = JSON.parse(readFileSync(inputPath, 'utf8'));
+  const frame = JSON.parse(readFileSync(framePath, 'utf8'));
+  const framed = await jsonld.frame(input, frame, { documentLoader });
+  const nquads = await jsonld.canonize(framed, {
+    algorithm: 'URDNA2015',
+    format: 'application/n-quads',
+    documentLoader,
+  });
+  // Normalize: LF, trailing newline, no BOM
+  const normalized = nquads.endsWith('\n') ? nquads : nquads + '\n';
+  writeFileSync(expectedPath, normalized, { encoding: 'utf8' });
+  console.log(`wrote ${relative(repoRoot, expectedPath)} (${normalized.length} bytes)`);
+  return true;
+}
+
+function discoverFixtureDirs(root) {
+  const out = [];
+  for (const family of readdirSync(root)) {
+    if (family.startsWith('_')) continue; // skip _contexts/
+    const familyDir = join(root, family);
+    if (!statSync(familyDir).isDirectory()) continue;
+    for (const name of readdirSync(familyDir)) {
+      const fixtureDir = join(familyDir, name);
+      if (!statSync(fixtureDir).isDirectory()) continue;
+      out.push(fixtureDir);
+    }
+  }
+  return out;
+}
+
+const targets = args[0] === '--all'
+  ? discoverFixtureDirs(fixturesRoot)
+  : args.map((a) => resolve(a));
+
+let ok = 0, skipped = 0, failed = 0;
+for (const dir of targets) {
+  try {
+    if (await regen(dir)) ok += 1; else skipped += 1;
+  } catch (err) {
+    failed += 1;
+    console.error(`failed ${dir}: ${err && err.message ? err.message : err}`);
+  }
+}
+console.log(`\nregenerated: ${ok}; skipped: ${skipped}; failed: ${failed}`);
+process.exit(failed > 0 ? 1 : 0);