fix(conformance,docs): unblock CI and address Sonar findings

- conformance/schema/vector.schema.json: allow hyphens in id segments so
  existing ids like auth.brc31-handshake validate cleanly; unblocks 8
  vector files that the new ajv-backed validation was rejecting.
- conformance/runner/src/runner.js: refactor validateFile into focused
  helpers (checkTopLevelShape, checkRequiredFields, checkRegressionMetadata,
  runSchemaValidator) to reduce cognitive complexity (S3776).
- scripts/generate-parity-matrix.mjs: split main into describeFile and
  buildSummary helpers, extract tallyParity/collectTagCategories,
  switch to replaceAll (S7781), use top-level await (S7785), and
  reduce cognitive complexity (S3776).
- conformance/PARITY_MATRIX.json: regenerate after script refactor.
- docs/architecture/conformance.md, docs/conformance/index.md: link
  PORTING_GUIDE.md by GitHub URL since file lives outside docs/ tree;
  fixes docs-site check-links.mjs failures.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: sirdeggen

conformance/PARITY_MATRIX.json

@@ -1,8 +1,8 @@
 {
   "schema_version": "1.0",
-  "generated_at": "2026-05-14",
+  "generated_at": "2026-05-19",
   "source": "ts-stack conformance corpus",
-  "description": "Machine-readable parity status for cross-language SDK implementations (Go, Rust, Python). Use this to track and drive conformance. Regenerate with: node scripts/generate-parity-matrix.mjs",
+  "description": "Machine-readable parity status for cross-language SDK implementations (Go, Rust, Python). Use this to track and drive conformance.",
   "summary": {
     "total_files": 72,
     "total_vectors": 6625,

conformance/runner/src/runner.js

@@ -137,62 +137,75 @@ const REQUIRED_TOP_LEVEL = ['vectors']
 const REGRESSION_RECOMMENDED_TOP_LEVEL = ['version', 'domain', 'category', 'description', 'regression']
 const REQUIRED_VECTOR_FIELDS = ['id', 'input', 'expected']
 
-function validateFile (path, data) {
-  const errors = []
-
-  if (typeof data !== 'object' || data === null || Array.isArray(data)) {
-    // Legacy format: bare array of vectors (no top-level envelope)
-    if (Array.isArray(data)) {
-      errors.push(`WARN: ${path} uses legacy bare-array format — wrap in { "vectors": [...] } envelope`)
-      return { errors, vectors: data }
+function checkTopLevelShape (path, data) {
+  if (Array.isArray(data)) {
+    return {
+      errors: [`WARN: ${path} uses legacy bare-array format — wrap in { "vectors": [...] } envelope`],
+      vectors: data,
+      done: true
     }
-    errors.push(`ERROR: ${path} top level must be an object or array`)
-    return { errors, vectors: [] }
   }
+  if (typeof data !== 'object' || data === null) {
+    return {
+      errors: [`ERROR: ${path} top level must be an object or array`],
+      vectors: [],
+      done: true
+    }
+  }
+  return { errors: [], vectors: null, done: false }
+}
 
-  const isRegression = path.includes('/regressions/')
-
-  // Check required top-level fields (lightweight fast check before full schema validation)
+function checkRequiredFields (path, data) {
+  const errors = []
   for (const field of REQUIRED_TOP_LEVEL) {
     if (!(field in data)) {
       errors.push(`ERROR: ${path} missing required top-level field "${field}"`)
     }
   }
+  return errors
+}
 
-  // For regressions we still do some lightweight metadata checks (the regression schema
-  // is intentionally more permissive at the top level than the standard one).
-  if (isRegression) {
-    for (const field of REGRESSION_RECOMMENDED_TOP_LEVEL) {
-      if (!(field in data)) {
-        errors.push(`WARN: ${path} missing recommended regression field "${field}"`)
-      }
-    }
-    if (!data.regression || typeof data.regression !== 'object' || !data.regression.issue) {
-      errors.push(`WARN: ${path} regression file is missing regression.issue metadata`)
+function checkRegressionMetadata (path, data) {
+  const errors = []
+  for (const field of REGRESSION_RECOMMENDED_TOP_LEVEL) {
+    if (!(field in data)) {
+      errors.push(`WARN: ${path} missing recommended regression field "${field}"`)
     }
   }
-
-  const vectors = Array.isArray(data.vectors) ? data.vectors : []
-
-  if (!Array.isArray(data.vectors)) {
-    errors.push(`ERROR: ${path} "vectors" must be an array`)
-    return { errors, vectors: [] }
+  if (!data.regression || typeof data.regression !== 'object' || !data.regression.issue) {
+    errors.push(`WARN: ${path} regression file is missing regression.issue metadata`)
   }
+  return errors
+}
 
-  // --- Strict JSON Schema validation (always enforced) ---
+function runSchemaValidator (path, data, isRegression) {
   const validator = isRegression ? validateRegression : validateStandard
   const schemaName = isRegression ? 'regression-vector.schema.json' : 'vector.schema.json'
+  if (!validator || validator(data)) return []
+  return (validator.errors || []).map(e => {
+    const instancePath = e.instancePath || '(root)'
+    return `ERROR: ${path} SCHEMA: ${schemaName} ${instancePath} ${e.message}`
+  })
+}
+
+function validateFile (path, data) {
+  const shape = checkTopLevelShape(path, data)
+  if (shape.done) return { errors: shape.errors, vectors: shape.vectors }
 
-  if (validator && !validator(data)) {
-    const ajvErrors = (validator.errors || []).map(e => {
-      const instancePath = e.instancePath || '(root)'
-      return `SCHEMA: ${schemaName} ${instancePath} ${e.message}`
-    })
-    // Schema violations are fatal — this is the authoritative check for cross-language ports
-    ajvErrors.forEach(msg => errors.push(`ERROR: ${path} ${msg}`))
+  const errors = checkRequiredFields(path, data)
+  const isRegression = path.includes('/regressions/')
+
+  if (isRegression) {
+    errors.push(...checkRegressionMetadata(path, data))
+  }
+
+  if (!Array.isArray(data.vectors)) {
+    errors.push(`ERROR: ${path} "vectors" must be an array`)
+    return { errors, vectors: [] }
   }
 
-  return { errors, vectors }
+  errors.push(...runSchemaValidator(path, data, isRegression))
+  return { errors, vectors: data.vectors }
 }
 
 function validateVector (filePath, vec, index) {

conformance/schema/vector.schema.json

@@ -9,8 +9,8 @@
     "$schema": { "type": "string" },
     "id": {
       "type": "string",
-      "pattern": "^[a-z][a-z0-9]*(?:\\.[a-z][a-z0-9]*)*$",
-      "description": "Stable dot-separated identifier, e.g. sdk.crypto.ecdsa"
+      "pattern": "^[a-z][a-z0-9-]*(?:\\.[a-z][a-z0-9-]*)*$",
+      "description": "Stable dot-separated identifier with lowercase alphanumerics and hyphens, e.g. sdk.crypto.ecdsa or auth.brc31-handshake"
     },
     "name": { "type": "string" },
     "brc": {

docs/architecture/conformance.md

@@ -102,5 +102,5 @@ See [Contributing Vectors](../conformance/contributing-vectors.md) for the file
 
 - [Conformance Testing](../conformance/index.md)
 - [Vector Catalog](../conformance/vectors.md)
-- **[Porting Guide](../conformance/PORTING_GUIDE.md)** — Essential reading when aligning another language implementation
+- **[Porting Guide](https://github.com/bsv-blockchain/ts-stack/blob/main/conformance/PORTING_GUIDE.md)** — Essential reading when aligning another language implementation
 - [BRC Standards Index](../reference/brc-index.md)

docs/conformance/index.md

@@ -101,4 +101,4 @@ For a non-TypeScript SDK or wallet:
 - [TypeScript Runner](./runner-ts.md) — Runner commands and limitations
 - [Contributing Vectors](./contributing-vectors.md) — Add or refine fixtures
 - [Architecture View](../architecture/conformance.md) — High-level overview for port planning teams
-- **[Porting Guide](../conformance/PORTING_GUIDE.md)** — Practical guide for aligning Go, Rust, Python, or other language implementations (including known deviations and conformance tiers)
+- **[Porting Guide](https://github.com/bsv-blockchain/ts-stack/blob/main/conformance/PORTING_GUIDE.md)** — Practical guide for aligning Go, Rust, Python, or other language implementations (including known deviations and conformance tiers)

scripts/generate-parity-matrix.mjs

@@ -15,6 +15,8 @@ const ROOT = join(__dirname, '..');
 const VECTORS_DIR = join(ROOT, 'conformance/vectors');
 const OUTPUT = join(ROOT, 'conformance/PARITY_MATRIX.json');
 
+const STATEFUL_TAG_KEYS = ['funded', 'live_overlay', 'state', 'harness'];
+
 async function walk(dir) {
   const entries = await readdir(dir, { withFileTypes: true });
   const files = [];
@@ -29,93 +31,99 @@ async function walk(dir) {
   return files;
 }
 
-async function main() {
-  const jsonFiles = await walk(VECTORS_DIR);
-  const files = [];
+function isStatefulTag(tag) {
+  return STATEFUL_TAG_KEYS.some(k => tag.includes(k));
+}
 
-  for (const fullPath of jsonFiles) {
-    const relPath = relative(VECTORS_DIR, fullPath).replace(/\\/g, '/');
-    const raw = await readFile(fullPath, 'utf8');
-    const data = JSON.parse(raw);
-
-    const fileId = data.id || null;
-    const fileLevelParity = data.parity_class || 'required';
-    const vectors = Array.isArray(data.vectors) ? data.vectors : [];
-
-    let required = 0;
-    let intended = 0;
-    let skipped = 0;
-    const skipReasons = new Set();
-    const categories = new Set();
-
-    for (const vec of vectors) {
-      const p = vec.parity_class || fileLevelParity;
-      if (p === 'required') required++;
-      else if (p === 'intended') intended++;
-      else if (p === 'best-effort') categories.add('best-effort');
-
-      if (vec.skip === true) skipped++;
-
-      if (vec.skip_reason) skipReasons.add(vec.skip_reason);
-      if (vec.tags) {
-        for (const tag of vec.tags) {
-          if (['funded', 'live_overlay', 'state', 'harness'].some(k => tag.includes(k))) {
-            categories.add('wallet_stateful_harness');
-          }
-        }
-      }
-    }
+function tallyParity(parity, counts, categories) {
+  if (parity === 'required') counts.required++;
+  else if (parity === 'intended') counts.intended++;
+  else if (parity === 'best-effort') categories.add('best-effort');
+}
 
-    const total = vectors.length;
-    let effectiveStatus = 'required';
-    if (intended > 0) effectiveStatus = intended === total ? 'intended' : 'mixed';
-    else if (skipped > 0) effectiveStatus = 'mixed';
-
-    let reasonCategory = 'fully_supported';
-    let justification = '';
-
-    if (relPath.startsWith('regressions/')) {
-      reasonCategory = 'historical_regression';
-      justification = 'Historical cross-SDK bug reproduction vector';
-    } else if (relPath.includes('wallet/brc100/')) {
-      if (intended > 0 || skipped > 0) {
-        reasonCategory = 'wallet_stateful_harness_required';
-        justification = 'Requires funded UTXOs + realistic fee model, live overlay, or pre-existing wallet state (see COVERAGE.md)';
-      }
-    } else if (relPath.includes('sdk/scripts/evaluation')) {
-      if (intended > 0) {
-        reasonCategory = 'partial_ts_behavioral_difference';
-        justification = `${intended} tx_invalid / MINIMALDATA / OP_VER edge cases intentionally differ from reference test vectors`;
-      }
-    }
+function collectTagCategories(tags, categories) {
+  if (!tags) return;
+  for (const tag of tags) {
+    if (isStatefulTag(tag)) categories.add('wallet_stateful_harness');
+  }
+}
 
-    if (skipReasons.size > 0 && !justification) {
-      justification = Array.from(skipReasons).join(' | ');
-    }
+function aggregateVectors(vectors, fileLevelParity) {
+  const counts = { required: 0, intended: 0, skipped: 0 };
+  const skipReasons = new Set();
+  const categories = new Set();
 
-    files.push({
-      path: relPath,
-      id: fileId,
-      total_vectors: total,
-      file_level_parity: fileLevelParity,
-      effective_status: effectiveStatus,
-      required_count: required,
-      intended_count: intended,
-      skipped_count: skipped,
-      reason_category: reasonCategory,
-      justification: justification || undefined,
-      categories: Array.from(categories)
-    });
+  for (const vec of vectors) {
+    tallyParity(vec.parity_class || fileLevelParity, counts, categories);
+    if (vec.skip === true) counts.skipped++;
+    if (vec.skip_reason) skipReasons.add(vec.skip_reason);
+    collectTagCategories(vec.tags, categories);
   }
 
-  // Sort for stability
-  files.sort((a, b) => a.path.localeCompare(b.path));
+  return { counts, skipReasons, categories };
+}
 
-  const totalVectors = files.reduce((sum, f) => sum + f.total_vectors, 0);
+function effectiveStatus(counts, total) {
+  if (counts.intended > 0) return counts.intended === total ? 'intended' : 'mixed';
+  if (counts.skipped > 0) return 'mixed';
+  return 'required';
+}
 
+function classifyReason(relPath, counts) {
+  if (relPath.startsWith('regressions/')) {
+    return {
+      reasonCategory: 'historical_regression',
+      justification: 'Historical cross-SDK bug reproduction vector'
+    };
+  }
+  if (relPath.includes('wallet/brc100/') && (counts.intended > 0 || counts.skipped > 0)) {
+    return {
+      reasonCategory: 'wallet_stateful_harness_required',
+      justification: 'Requires funded UTXOs + realistic fee model, live overlay, or pre-existing wallet state (see COVERAGE.md)'
+    };
+  }
+  if (relPath.includes('sdk/scripts/evaluation') && counts.intended > 0) {
+    return {
+      reasonCategory: 'partial_ts_behavioral_difference',
+      justification: `${counts.intended} tx_invalid / MINIMALDATA / OP_VER edge cases intentionally differ from reference test vectors`
+    };
+  }
+  return { reasonCategory: 'fully_supported', justification: '' };
+}
+
+async function describeFile(fullPath) {
+  const relPath = relative(VECTORS_DIR, fullPath).replaceAll('\\', '/');
+  const raw = await readFile(fullPath, 'utf8');
+  const data = JSON.parse(raw);
+
+  const fileId = data.id || null;
+  const fileLevelParity = data.parity_class || 'required';
+  const vectors = Array.isArray(data.vectors) ? data.vectors : [];
+
+  const { counts, skipReasons, categories } = aggregateVectors(vectors, fileLevelParity);
+  const total = vectors.length;
+  const { reasonCategory, justification: baseJustification } = classifyReason(relPath, counts);
+  const justification = baseJustification || (skipReasons.size > 0 ? Array.from(skipReasons).join(' | ') : '');
+
+  return {
+    path: relPath,
+    id: fileId,
+    total_vectors: total,
+    file_level_parity: fileLevelParity,
+    effective_status: effectiveStatus(counts, total),
+    required_count: counts.required,
+    intended_count: counts.intended,
+    skipped_count: counts.skipped,
+    reason_category: reasonCategory,
+    justification: justification || undefined,
+    categories: Array.from(categories)
+  };
+}
+
+function buildSummary(files) {
   const summary = {
     total_files: files.length,
-    total_vectors: totalVectors,
+    total_vectors: files.reduce((sum, f) => sum + f.total_vectors, 0),
     fully_required_files: files.filter(f => f.effective_status === 'required').length,
     files_with_intended: files.filter(f => f.intended_count > 0).length,
     files_with_mixed_status: files.filter(f => f.effective_status === 'mixed').length,
@@ -131,6 +139,18 @@ async function main() {
     summary.by_reason_category[f.reason_category] = (summary.by_reason_category[f.reason_category] || 0) + f.total_vectors;
   }
 
+  return summary;
+}
+
+try {
+  const jsonFiles = await walk(VECTORS_DIR);
+  const files = [];
+  for (const fullPath of jsonFiles) {
+    files.push(await describeFile(fullPath));
+  }
+  files.sort((a, b) => a.path.localeCompare(b.path));
+
+  const summary = buildSummary(files);
   const matrix = {
     schema_version: '1.0',
     generated_at: new Date().toISOString().split('T')[0],
@@ -145,9 +165,7 @@ async function main() {
   console.log(`  Files: ${summary.total_files}`);
   console.log(`  Vectors: ${summary.total_vectors}`);
   console.log(`  Fully required files: ${summary.fully_required_files}`);
-}
-
-main().catch(err => {
+} catch (err) {
   console.error(err);
   process.exit(1);
-});
+}