audrey 0.23.1 → 1.0.1

package/benchmarks/validate-guardbench-artifacts.mjs

@@ -0,0 +1,343 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { basename, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { publicPath } from './public-paths.mjs';
+
+const DEFAULT_DIR = 'benchmarks/output';
+const DEFAULT_SEEDED_SECRET = 'sk-guardbench-secret-0000000000000000000000000000';
+const SCHEMA_FILES = {
+  manifest: 'guardbench-manifest.schema.json',
+  summary: 'guardbench-summary.schema.json',
+  raw: 'guardbench-raw.schema.json',
+  externalRun: 'guardbench-external-run.schema.json',
+  conformanceCard: 'guardbench-conformance-card.schema.json',
+};
+const ARTIFACT_FILES = {
+  manifest: 'guardbench-manifest.json',
+  summary: 'guardbench-summary.json',
+  raw: 'guardbench-raw.json',
+};
+const OPTIONAL_ARTIFACT_FILES = {
+  externalRun: 'external-run-metadata.json',
+  conformanceCard: 'guardbench-conformance-card.json',
+};
+
+function parseArgs(argv = process.argv.slice(2)) {
+  const args = {
+    dir: DEFAULT_DIR,
+    schemasDir: 'benchmarks/schemas',
+    seededSecrets: [DEFAULT_SEEDED_SECRET],
+    json: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if ((token === '--dir' || token === '--out-dir') && argv[i + 1]) args.dir = argv[++i];
+    else if (token === '--schemas-dir' && argv[i + 1]) args.schemasDir = argv[++i];
+    else if (token === '--seeded-secret' && argv[i + 1]) args.seededSecrets.push(argv[++i]);
+    else if (token === '--no-default-secret') args.seededSecrets = [];
+    else if (token === '--json') args.json = true;
+    else if (token === '--help') {
+      return { ...args, help: true };
+    }
+  }
+
+  return args;
+}
+
+function usage() {
+  return [
+    'Usage: node benchmarks/validate-guardbench-artifacts.mjs [--dir benchmarks/output] [--json]',
+    '',
+    'Validates guardbench-manifest.json, guardbench-summary.json, and',
+    'guardbench-raw.json against the published GuardBench JSON schemas.',
+    '',
+    'Options:',
+    '  --dir <path>             Directory containing GuardBench output artifacts.',
+    '  --schemas-dir <path>     Directory containing GuardBench schema files.',
+    '  --seeded-secret <value>  Additional seeded raw secret that must not appear.',
+    '  --no-default-secret      Do not check the built-in GuardBench redaction probe.',
+    '  --json                   Print a machine-readable validation report.',
+  ].join('\n');
+}
+
+function readText(path) {
+  if (!existsSync(path)) throw new Error(`Missing required file: ${path}`);
+  return readFileSync(path, 'utf-8');
+}
+
+function readJson(path) {
+  return JSON.parse(readText(path));
+}
+
+function sha256File(path) {
+  return createHash('sha256').update(readFileSync(path)).digest('hex');
+}
+
+export function computeGuardBenchArtifactHashes(dir, files = Object.values(ARTIFACT_FILES)) {
+  const resolvedDir = resolve(dir);
+  return Object.fromEntries(files.map(file => [file, sha256File(join(resolvedDir, file))]));
+}
+
+function typeOf(value) {
+  if (Array.isArray(value)) return 'array';
+  if (value === null) return 'null';
+  return typeof value;
+}
+
+export function validateSchema(value, schema, label, root = schema) {
+  const errors = [];
+
+  function validate(current, currentSchema, path) {
+    if (currentSchema.$ref) {
+      const refPath = currentSchema.$ref.replace(/^#\//, '').split('/');
+      const resolved = refPath.reduce((node, key) => node?.[key], root);
+      if (!resolved) {
+        errors.push(`${path}: unresolved schema ref ${currentSchema.$ref}`);
+        return;
+      }
+      validate(current, resolved, path);
+      return;
+    }
+
+    if (currentSchema.anyOf) {
+      const nested = currentSchema.anyOf.map(option => {
+        const before = errors.length;
+        validate(current, option, path);
+        return errors.splice(before);
+      });
+      if (!nested.some(group => group.length === 0)) {
+        errors.push(`${path}: did not match any allowed schema`);
+      }
+      return;
+    }
+
+    if (currentSchema.const !== undefined && current !== currentSchema.const) {
+      errors.push(`${path}: expected constant ${currentSchema.const}`);
+    }
+    if (currentSchema.enum && !currentSchema.enum.includes(current)) {
+      errors.push(`${path}: expected one of ${currentSchema.enum.join(', ')}`);
+    }
+    if (currentSchema.type === 'integer') {
+      if (typeof current !== 'number' || !Number.isInteger(current)) {
+        errors.push(`${path}: expected integer, got ${typeOf(current)}`);
+        return;
+      }
+    } else if (currentSchema.type) {
+      const actual = typeOf(current);
+      if (actual !== currentSchema.type) {
+        errors.push(`${path}: expected ${currentSchema.type}, got ${actual}`);
+        return;
+      }
+    }
+    if (currentSchema.minLength != null && String(current).length < currentSchema.minLength) {
+      errors.push(`${path}: shorter than minLength ${currentSchema.minLength}`);
+    }
+    if (currentSchema.pattern && typeof current === 'string' && !(new RegExp(currentSchema.pattern).test(current))) {
+      errors.push(`${path}: does not match ${currentSchema.pattern}`);
+    }
+    if (currentSchema.minimum != null && typeof current === 'number' && current < currentSchema.minimum) {
+      errors.push(`${path}: below minimum ${currentSchema.minimum}`);
+    }
+    if (currentSchema.maximum != null && typeof current === 'number' && current > currentSchema.maximum) {
+      errors.push(`${path}: above maximum ${currentSchema.maximum}`);
+    }
+
+    if (currentSchema.type === 'array') {
+      if (currentSchema.minItems != null && current.length < currentSchema.minItems) {
+        errors.push(`${path}: expected at least ${currentSchema.minItems} items`);
+      }
+      if (currentSchema.items) {
+        current.forEach((item, index) => validate(item, currentSchema.items, `${path}[${index}]`));
+      }
+    }
+
+    if (currentSchema.type === 'object') {
+      for (const required of currentSchema.required ?? []) {
+        if (!Object.hasOwn(current, required)) errors.push(`${path}: missing required property ${required}`);
+      }
+      if (currentSchema.additionalProperties === false) {
+        for (const key of Object.keys(current)) {
+          if (!Object.hasOwn(currentSchema.properties ?? {}, key)) {
+            errors.push(`${path}: unexpected property ${key}`);
+          }
+        }
+      }
+      for (const [key, propertySchema] of Object.entries(currentSchema.properties ?? {})) {
+        if (Object.hasOwn(current, key)) validate(current[key], propertySchema, `${path}.${key}`);
+      }
+    }
+  }
+
+  validate(value, schema, label);
+  return errors;
+}
+
+function stableJson(value) {
+  if (Array.isArray(value)) return `[${value.map(stableJson).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function assertSameJson(actual, expected, label, failures) {
+  if (stableJson(actual) !== stableJson(expected)) {
+    failures.push(`${label}: cross-artifact mismatch`);
+  }
+}
+
+export function validateGuardBenchArtifacts(options = {}) {
+  const dir = resolve(options.dir ?? DEFAULT_DIR);
+  const schemasDir = resolve(options.schemasDir ?? 'benchmarks/schemas');
+  const seededSecrets = options.seededSecrets ?? [DEFAULT_SEEDED_SECRET];
+  const failures = [];
+  const artifacts = {};
+  const schemas = {};
+  const artifactPaths = {};
+  const optionalArtifacts = {};
+
+  for (const [key, file] of Object.entries(ARTIFACT_FILES)) {
+    artifactPaths[key] = join(dir, file);
+    try {
+      artifacts[key] = readJson(artifactPaths[key]);
+    } catch (error) {
+      failures.push(error.message);
+    }
+  }
+
+  for (const [key, file] of Object.entries(SCHEMA_FILES)) {
+    try {
+      schemas[key] = readJson(join(schemasDir, file));
+    } catch (error) {
+      failures.push(error.message);
+    }
+  }
+
+  if (failures.length === 0) {
+    for (const key of Object.keys(ARTIFACT_FILES)) {
+      for (const error of validateSchema(artifacts[key], schemas[key], `guardbench-${key}`)) {
+        failures.push(`${basename(artifactPaths[key])}: ${error}`);
+      }
+    }
+    for (const [key, file] of Object.entries(OPTIONAL_ARTIFACT_FILES)) {
+      const path = join(dir, file);
+      if (!existsSync(path)) continue;
+      artifactPaths[key] = path;
+      try {
+        optionalArtifacts[key] = readJson(path);
+      } catch (error) {
+        failures.push(error.message);
+        continue;
+      }
+      for (const error of validateSchema(optionalArtifacts[key], schemas[key], `guardbench-${key}`)) {
+        failures.push(`${basename(path)}: ${error}`);
+      }
+    }
+
+    const externalRun = optionalArtifacts.externalRun;
+    if (externalRun?.artifactHashes) {
+      const currentHashes = computeGuardBenchArtifactHashes(dir);
+      for (const [file, expectedHash] of Object.entries(externalRun.artifactHashes)) {
+        if (!Object.hasOwn(currentHashes, file)) {
+          failures.push(`external-run-metadata.json: artifactHashes includes unknown file ${file}`);
+        } else if (currentHashes[file] !== expectedHash) {
+          failures.push(`external-run-metadata.json: artifactHashes.${file} does not match current artifact`);
+        }
+      }
+      for (const file of Object.values(ARTIFACT_FILES)) {
+        if (!Object.hasOwn(externalRun.artifactHashes, file)) {
+          failures.push(`external-run-metadata.json: artifactHashes missing ${file}`);
+        }
+      }
+    }
+    const conformanceCard = optionalArtifacts.conformanceCard;
+    if (conformanceCard) {
+      const currentHashes = computeGuardBenchArtifactHashes(dir);
+      for (const [file, expectedHash] of Object.entries(conformanceCard.integrity?.artifactHashes ?? {})) {
+        if (!Object.hasOwn(currentHashes, file)) {
+          failures.push(`guardbench-conformance-card.json: integrity.artifactHashes includes unknown file ${file}`);
+        } else if (currentHashes[file] !== expectedHash) {
+          failures.push(`guardbench-conformance-card.json: integrity.artifactHashes.${file} does not match current artifact`);
+        }
+      }
+      if (conformanceCard.manifestVersion !== artifacts.manifest.manifestVersion) {
+        failures.push('guardbench-conformance-card.json: manifestVersion does not match guardbench-manifest.json');
+      }
+      if (conformanceCard.suiteId !== artifacts.manifest.suiteId) {
+        failures.push('guardbench-conformance-card.json: suiteId does not match guardbench-manifest.json');
+      }
+      if (!artifacts.summary.systemSummaries?.some(row => row.system === conformanceCard.subject?.name)) {
+        failures.push('guardbench-conformance-card.json: subject.name is not present in guardbench-summary.json');
+      }
+    }
+
+    assertSameJson(artifacts.summary.manifest, artifacts.manifest, 'summary.manifest vs guardbench-manifest.json', failures);
+    assertSameJson(artifacts.summary.cases, artifacts.raw.cases, 'summary.cases vs raw.cases', failures);
+    assertSameJson(artifacts.summary.provenance, artifacts.raw.provenance, 'summary.provenance vs raw.provenance', failures);
+    if (artifacts.summary.generatedAt !== artifacts.raw.generatedAt) {
+      failures.push('summary.generatedAt vs raw.generatedAt: cross-artifact mismatch');
+    }
+    if (artifacts.manifest.manifestVersion !== artifacts.raw.manifestVersion) {
+      failures.push('manifest.manifestVersion vs raw.manifestVersion: cross-artifact mismatch');
+    }
+
+    if (artifacts.summary.artifactRedactionSweep?.passed !== true) {
+      failures.push('guardbench-summary.json: artifactRedactionSweep did not pass');
+    }
+    if (artifacts.raw.artifactRedactionSweep?.passed !== true) {
+      failures.push('guardbench-raw.json: artifactRedactionSweep did not pass');
+    }
+
+    const artifactText = Object.values(artifacts).map(value => JSON.stringify(value)).join('\n');
+    for (const secret of seededSecrets) {
+      if (secret && artifactText.includes(secret)) {
+        failures.push(`raw seeded secret leaked into GuardBench artifacts: ${secret}`);
+      }
+    }
+    const manifestText = JSON.stringify(artifacts.manifest);
+    if (!manifestText.includes('seededSecretRefs')) {
+      failures.push('guardbench-manifest.json: missing seededSecretRefs');
+    }
+    if (manifestText.includes('"seededSecrets"')) {
+      failures.push('guardbench-manifest.json: contains seededSecrets');
+    }
+  }
+
+  return {
+    ok: failures.length === 0,
+    dir: publicPath(dir),
+    schemasDir: publicPath(schemasDir),
+    files: Object.values(ARTIFACT_FILES),
+    optionalFiles: Object.values(OPTIONAL_ARTIFACT_FILES).filter(file => existsSync(join(dir, file))),
+    failures,
+  };
+}
+
+async function main() {
+  const args = parseArgs();
+  if (args.help) {
+    console.log(usage());
+    return;
+  }
+
+  const report = validateGuardBenchArtifacts(args);
+  if (args.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else if (report.ok) {
+    console.log(`GuardBench artifact validation passed: ${report.dir}`);
+  } else {
+    console.error('GuardBench artifact validation failed:');
+    for (const failure of report.failures) console.error(`- ${failure}`);
+  }
+
+  if (!report.ok) process.exit(1);
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch(error => {
+    console.error(error.stack ?? error.message);
+    process.exit(1);
+  });
+}

package/benchmarks/verify-external-evidence.mjs

@@ -0,0 +1,296 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { validateAdapterRegistry } from './validate-adapter-registry.mjs';
+import { validateGuardBenchArtifacts, validateSchema } from './validate-guardbench-artifacts.mjs';
+import { publicPath } from './public-paths.mjs';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const DEFAULT_REGISTRY = 'benchmarks/adapters/registry.json';
+const DEFAULT_REGISTRY_SCHEMA = 'benchmarks/schemas/guardbench-adapter-registry.schema.json';
+const DEFAULT_EXTERNAL_RUN_SCHEMA = 'benchmarks/schemas/guardbench-external-run.schema.json';
+const DEFAULT_EVIDENCE_SCHEMA = 'benchmarks/schemas/guardbench-external-evidence.schema.json';
+const DEFAULT_OUT_ROOT = 'benchmarks/output/external';
+const DEFAULT_REPORT = 'benchmarks/output/external/guardbench-external-evidence.json';
+const PENDING_METADATA_STATUSES = new Set(['blocked', 'dry-run-missing-env', 'dry-run-ready']);
+
+function fromRoot(path) {
+  return resolve(ROOT, path);
+}
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, 'utf-8'));
+}
+
+function writeJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, 'utf-8');
+}
+
+export function parseExternalEvidenceArgs(argv = process.argv.slice(2)) {
+  const args = {
+    registry: DEFAULT_REGISTRY,
+    registrySchema: DEFAULT_REGISTRY_SCHEMA,
+    externalRunSchema: DEFAULT_EXTERNAL_RUN_SCHEMA,
+    evidenceSchema: DEFAULT_EVIDENCE_SCHEMA,
+    outRoot: DEFAULT_OUT_ROOT,
+    report: DEFAULT_REPORT,
+    adapters: [],
+    allowPending: false,
+    json: false,
+    write: true,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const token = argv[i];
+    if (token === '--registry' && argv[i + 1]) args.registry = argv[++i];
+    else if (token === '--registry-schema' && argv[i + 1]) args.registrySchema = argv[++i];
+    else if (token === '--external-run-schema' && argv[i + 1]) args.externalRunSchema = argv[++i];
+    else if (token === '--evidence-schema' && argv[i + 1]) args.evidenceSchema = argv[++i];
+    else if (token === '--out-root' && argv[i + 1]) args.outRoot = argv[++i];
+    else if (token === '--report' && argv[i + 1]) args.report = argv[++i];
+    else if (token === '--adapter' && argv[i + 1]) args.adapters.push(argv[++i]);
+    else if (token === '--allow-pending') args.allowPending = true;
+    else if (token === '--json') args.json = true;
+    else if (token === '--no-write') args.write = false;
+    else if (token === '--help' || token === '-h') args.help = true;
+    else throw new Error(`Unknown argument: ${token}`);
+  }
+
+  return args;
+}
+
+function usage() {
+  return `Usage: node benchmarks/verify-external-evidence.mjs [options]
+
+Options:
+  --registry <path>             GuardBench adapter registry. Default: ${DEFAULT_REGISTRY}.
+  --out-root <path>             External evidence root. Default: ${DEFAULT_OUT_ROOT}.
+  --report <path>               Output report path. Default: ${DEFAULT_REPORT}.
+  --adapter <id>                Limit verification to one adapter id. May repeat.
+  --allow-pending               Treat missing, blocked, or dry-run-only evidence as pending.
+  --json                        Print the machine-readable evidence report.
+  --no-write                    Do not write the evidence report.
+`;
+}
+
+function credentialLeaks(text, requiredEnv, env) {
+  const leaks = [];
+  for (const name of requiredEnv) {
+    const value = env[name];
+    if (typeof value === 'string' && value.length >= 8 && text.includes(value)) {
+      leaks.push(name);
+    }
+  }
+  return leaks;
+}
+
+function pendingRow(target, outDir, metadataPath, allowPending, reason, metadata = null, extraFailures = [], secretLeakCount = 0) {
+  return {
+    id: target.id,
+    name: target.name,
+    path: target.path,
+    credentialMode: target.credentialMode,
+    requiredEnv: target.requiredEnv,
+    outDir: publicPath(outDir),
+    metadataPath: publicPath(metadataPath),
+    status: 'pending',
+    evidenceKind: metadata?.dryRun ? 'dry-run' : reason === 'missing' ? 'missing' : 'blocked',
+    metadataStatus: metadata?.status ?? null,
+    dryRun: metadata?.dryRun ?? null,
+    missingEnv: metadata?.missingEnv ?? target.requiredEnv,
+    artifactValidationOk: null,
+    adapterConformanceOk: null,
+    secretLeakCount,
+    failures: allowPending ? extraFailures : [
+      ...extraFailures,
+      reason === 'missing'
+        ? `Missing external run metadata: ${metadataPath}`
+        : `External evidence is pending for ${target.id}: ${metadata?.status ?? reason}`,
+    ],
+  };
+}
+
+function verifyLiveMetadata(target, outDir, metadataPath, metadata, metadataText, schemas, env) {
+  const failures = [];
+  const schemaErrors = validateSchema(metadata, schemas.externalRun, 'guardbench-externalRun');
+  failures.push(...schemaErrors);
+
+  const artifactValidation = validateGuardBenchArtifacts({ dir: outDir });
+  if (!artifactValidation.ok) {
+    failures.push(...artifactValidation.failures.map(failure => `artifact validation: ${failure}`));
+  }
+
+  if (metadata.adapter !== target.id) failures.push(`metadata adapter ${metadata.adapter} does not match registry id ${target.id}`);
+  if (metadata.dryRun !== false) failures.push('metadata must come from a live run, not a dry run');
+  if (metadata.status !== 'passed') failures.push(`metadata status must be passed, got ${metadata.status}`);
+  if (metadata.exitCode !== 0) failures.push(`metadata exitCode must be 0, got ${metadata.exitCode}`);
+  if ((metadata.missingEnv ?? []).length !== 0) failures.push(`metadata still reports missing runtime env: ${(metadata.missingEnv ?? []).join(', ')}`);
+  for (const name of target.requiredEnv) {
+    if (!(metadata.requiredEnv ?? []).includes(name)) failures.push(`metadata requiredEnv missing ${name}`);
+  }
+  if (metadata.artifactValidation?.ok !== true) failures.push('metadata artifactValidation.ok must be true');
+  if (metadata.adapterConformance?.ok !== true) failures.push('metadata adapterConformance.ok must be true');
+  if (!metadata.artifactHashes) failures.push('metadata missing artifactHashes');
+
+  const leakedEnv = credentialLeaks(metadataText, target.requiredEnv, env);
+  failures.push(...leakedEnv.map(name => `metadata leaks runtime credential value for ${name}`));
+
+  return {
+    id: target.id,
+    name: target.name,
+    path: target.path,
+    credentialMode: target.credentialMode,
+    requiredEnv: target.requiredEnv,
+    outDir: publicPath(outDir),
+    metadataPath: publicPath(metadataPath),
+    status: failures.length === 0 ? 'verified' : 'failed',
+    evidenceKind: 'live',
+    metadataStatus: metadata.status ?? null,
+    dryRun: metadata.dryRun ?? null,
+    missingEnv: metadata.missingEnv ?? [],
+    artifactValidationOk: artifactValidation.ok,
+    adapterConformanceOk: metadata.adapterConformance?.ok ?? null,
+    secretLeakCount: leakedEnv.length,
+    failures,
+  };
+}
+
+function verifyTarget(target, options, schemas) {
+  const outDir = resolve(options.outRoot, target.id);
+  const metadataPath = join(outDir, 'external-run-metadata.json');
+
+  if (!existsSync(metadataPath)) {
+    return pendingRow(target, outDir, metadataPath, options.allowPending, 'missing');
+  }
+
+  let metadata = null;
+  let metadataText = '';
+  const parseFailures = [];
+  try {
+    metadataText = readFileSync(metadataPath, 'utf-8');
+    metadata = JSON.parse(metadataText);
+  } catch (error) {
+    parseFailures.push(error.message);
+  }
+
+  if (!metadata) {
+    return {
+      id: target.id,
+      name: target.name,
+    path: target.path,
+    credentialMode: target.credentialMode,
+    requiredEnv: target.requiredEnv,
+    outDir: publicPath(outDir),
+    metadataPath: publicPath(metadataPath),
+      status: 'failed',
+      evidenceKind: 'missing',
+      metadataStatus: null,
+      dryRun: null,
+      missingEnv: target.requiredEnv,
+      artifactValidationOk: null,
+      adapterConformanceOk: null,
+      secretLeakCount: 0,
+      failures: parseFailures,
+    };
+  }
+
+  const metadataSchemaFailures = validateSchema(metadata, schemas.externalRun, 'guardbench-externalRun');
+  const leakedEnv = credentialLeaks(metadataText, target.requiredEnv, options.env);
+  const metadataFailures = [
+    ...metadataSchemaFailures,
+    ...leakedEnv.map(name => `metadata leaks runtime credential value for ${name}`),
+  ];
+
+  if (metadata.dryRun === true || PENDING_METADATA_STATUSES.has(metadata.status)) {
+    return pendingRow(target, outDir, metadataPath, options.allowPending, metadata.status ?? 'pending', metadata, metadataFailures, leakedEnv.length);
+  }
+
+  return verifyLiveMetadata(target, outDir, metadataPath, metadata, metadataText, schemas, options.env);
+}
+
+function externalTargetsFromRegistry(registry, adapterIds) {
+  const selected = new Set(adapterIds ?? []);
+  return (registry.adapters ?? [])
+    .filter(adapter => adapter.credentialMode === 'runtime-env')
+    .filter(adapter => selected.size === 0 || selected.has(adapter.id));
+}
+
+export function validateExternalEvidenceReport(report, options = {}) {
+  const schema = readJson(fromRoot(options.schema ?? DEFAULT_EVIDENCE_SCHEMA));
+  return validateSchema(report, schema, 'guardbench-external-evidence');
+}
+
+export async function verifyExternalGuardBenchEvidence(options = {}) {
+  const registryPath = fromRoot(options.registry ?? DEFAULT_REGISTRY);
+  const registrySchemaPath = fromRoot(options.registrySchema ?? DEFAULT_REGISTRY_SCHEMA);
+  const outRoot = fromRoot(options.outRoot ?? DEFAULT_OUT_ROOT);
+  const allowPending = options.allowPending === true;
+  const registry = options.targets ? null : readJson(registryPath);
+  const registryValidation = options.targets
+    ? { ok: true, failures: [] }
+    : await validateAdapterRegistry({ registry: registryPath, schema: registrySchemaPath });
+  const targets = options.targets ?? externalTargetsFromRegistry(registry, options.adapters);
+  const schemas = {
+    externalRun: readJson(fromRoot(options.externalRunSchema ?? DEFAULT_EXTERNAL_RUN_SCHEMA)),
+  };
+  const rows = targets.map(target => verifyTarget(target, {
+    outRoot,
+    allowPending,
+    env: options.env ?? process.env,
+  }, schemas));
+  const unknownAdapters = (options.adapters ?? []).filter(id => !targets.some(target => target.id === id));
+  const failures = [
+    ...registryValidation.failures.map(failure => `registry: ${failure}`),
+    ...unknownAdapters.map(id => `Unknown runtime-env adapter id: ${id}`),
+    ...rows.flatMap(row => row.failures.map(failure => `${row.id}: ${failure}`)),
+  ];
+  const report = {
+    schemaVersion: '1.0.0',
+    suite: 'GuardBench external evidence verification',
+    generatedAt: new Date().toISOString(),
+    ok: failures.length === 0,
+    allowPending,
+    registry: options.targets ? 'inline-targets' : publicPath(registryPath),
+    outRoot: publicPath(outRoot),
+    adapters: rows,
+    failures,
+  };
+  const schemaFailures = validateExternalEvidenceReport(report, { schema: options.evidenceSchema ?? DEFAULT_EVIDENCE_SCHEMA });
+  if (schemaFailures.length > 0) {
+    throw new Error(`GuardBench external evidence schema validation failed: ${schemaFailures.join('; ')}`);
+  }
+  if (options.write !== false) {
+    writeJson(fromRoot(options.report ?? DEFAULT_REPORT), report);
+  }
+  return report;
+}
+
+async function main() {
+  const args = parseExternalEvidenceArgs();
+  if (args.help) {
+    console.log(usage());
+    return;
+  }
+
+  const report = await verifyExternalGuardBenchEvidence(args);
+  if (args.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else if (report.ok) {
+    const verified = report.adapters.filter(adapter => adapter.status === 'verified').length;
+    const pending = report.adapters.filter(adapter => adapter.status === 'pending').length;
+    console.log(`GuardBench external evidence verification passed: ${verified} verified, ${pending} pending`);
+  } else {
+    console.error('GuardBench external evidence verification failed:');
+    for (const failure of report.failures) console.error(`- ${failure}`);
+  }
+
+  if (!report.ok) process.exit(1);
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  main().catch(error => {
+    console.error(error.stack ?? error.message);
+    process.exit(1);
+  });
+}