@thomasminh1995/depverdict 0.6.0-alpha.1

package/src/installed-version-baseline.js

@@ -0,0 +1,196 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  createDefaultEcosystemVersionAdapterRegistry,
+  getEcosystemVersionAdapter
+} from './ecosystem-version-adapter.js';
+import { toPosixPath } from './files.js';
+
+const SUPPORTED_NPM_LOCKFILE_VERSIONS = new Set([1, 2, 3]);
+const NON_REGISTRY_DECLARATION =
+  /^(?:workspace:|file:|link:|git\+|git:|https?:|ssh:|github:|gitlab:|bitbucket:|\.{1,2}[\\/]|[\\/]|~[\\/])/i;
+
+function unresolved(reason) {
+  return {
+    installedVersion: null,
+    installedVersionStatus: 'unresolved',
+    installedVersionSource: null,
+    installedVersionReason: reason
+  };
+}
+
+function resolved(version, source) {
+  return {
+    installedVersion: version,
+    installedVersionStatus: 'resolved',
+    installedVersionSource: source,
+    installedVersionReason: null
+  };
+}
+
+function repositoryPath(...parts) {
+  const joined = path.posix.join(...parts.filter((part) => part && part !== '.'));
+  return joined || '.';
+}
+
+function lockfileRoots(project) {
+  if (project.workspace?.role === 'member') return [project.workspace.root];
+  return [project.path];
+}
+
+async function loadNpmLockfile(repositoryRoot, lockfileRoot, cache) {
+  const portablePath = repositoryPath(lockfileRoot, 'package-lock.json');
+  if (!cache.has(portablePath)) {
+    cache.set(portablePath, (async () => {
+      let bytes;
+      try {
+        bytes = await readFile(path.resolve(repositoryRoot, portablePath));
+      } catch (error) {
+        if (error?.code === 'ENOENT') return { status: 'missing', path: portablePath };
+        return { status: 'invalid', path: portablePath };
+      }
+
+      let lockfile;
+      try {
+        lockfile = JSON.parse(bytes.toString('utf8'));
+      } catch {
+        return { status: 'invalid', path: portablePath };
+      }
+
+      const lockfileVersion = lockfile?.lockfileVersion;
+      if (!Number.isInteger(lockfileVersion) || !SUPPORTED_NPM_LOCKFILE_VERSIONS.has(lockfileVersion)) {
+        return { status: 'unsupported', path: portablePath, lockfileVersion };
+      }
+      if (lockfileVersion === 1) {
+        if (!lockfile.dependencies || typeof lockfile.dependencies !== 'object' || Array.isArray(lockfile.dependencies)) {
+          return { status: 'invalid', path: portablePath, lockfileVersion };
+        }
+      } else if (!lockfile.packages || typeof lockfile.packages !== 'object' || Array.isArray(lockfile.packages)) {
+        return { status: 'invalid', path: portablePath, lockfileVersion };
+      }
+      return { status: 'loaded', path: portablePath, lockfileVersion, lockfile };
+    })());
+  }
+  return cache.get(portablePath);
+}
+
+function lockfileRelativeProjectPath(project, lockfileRoot) {
+  const root = lockfileRoot === '.' ? '' : lockfileRoot;
+  const projectPath = project.path === '.' ? '' : project.path;
+  return toPosixPath(path.posix.relative(root, projectPath));
+}
+
+function packageEntryCandidates(project, lockfileRoot, dependencyName) {
+  const relativeProject = lockfileRelativeProjectPath(project, lockfileRoot);
+  return [...new Set([
+    repositoryPath(relativeProject, 'node_modules', dependencyName),
+    repositoryPath('node_modules', dependencyName)
+  ])];
+}
+
+function ambiguousWorkspaceResolution(lockfile, project, dependencyName, candidates) {
+  if (project.workspace?.role !== 'member') return false;
+  const expected = new Set(candidates);
+  const suffix = `/node_modules/${dependencyName}`;
+  const otherMatches = Object.keys(lockfile.packages)
+    .filter((entryPath) => !expected.has(entryPath) && entryPath.endsWith(suffix));
+  return otherMatches.length > 1;
+}
+
+function exactInstalledVersion(adapter, value) {
+  if (typeof value !== 'string' || value.length === 0) return null;
+  const normalized = adapter.normalizeVersion(value);
+  return normalized.ok ? normalized.value : null;
+}
+
+function resolveFromV1(lockfileRecord, project, dependency, adapter, lockfileRoot) {
+  if (project.path !== lockfileRoot || project.workspace?.role === 'member') {
+    return unresolved('LOCKFILE_UNSUPPORTED');
+  }
+  const entry = lockfileRecord.lockfile.dependencies[dependency.name];
+  if (!entry) return unresolved('PACKAGE_NOT_RESOLVED');
+  const version = exactInstalledVersion(adapter, entry.version);
+  if (version === null) return unresolved('RESOLVED_VERSION_UNAVAILABLE');
+  return resolved(version, {
+    type: 'package-lock',
+    path: lockfileRecord.path,
+    lockfileVersion: lockfileRecord.lockfileVersion,
+    packagePath: repositoryPath(lockfileRoot, 'node_modules', dependency.name)
+  });
+}
+
+function resolveFromPackages(lockfileRecord, project, dependency, adapter, lockfileRoot) {
+  const candidates = packageEntryCandidates(project, lockfileRoot, dependency.name);
+  for (const candidate of candidates) {
+    const entry = lockfileRecord.lockfile.packages[candidate];
+    if (!entry) continue;
+    const version = exactInstalledVersion(adapter, entry.version);
+    if (version === null) return unresolved('RESOLVED_VERSION_UNAVAILABLE');
+    return resolved(version, {
+      type: 'package-lock',
+      path: lockfileRecord.path,
+      lockfileVersion: lockfileRecord.lockfileVersion,
+      packagePath: repositoryPath(lockfileRoot, candidate)
+    });
+  }
+  if (ambiguousWorkspaceResolution(lockfileRecord.lockfile, project, dependency.name, candidates)) {
+    return unresolved('WORKSPACE_RESOLUTION_AMBIGUOUS');
+  }
+  return unresolved('PACKAGE_NOT_RESOLVED');
+}
+
+async function resolveNpmDependency(repositoryRoot, project, dependency, adapter, cache) {
+  if (NON_REGISTRY_DECLARATION.test(dependency.declaredVersion ?? '')) {
+    return unresolved('NON_REGISTRY_DEPENDENCY');
+  }
+
+  for (const lockfileRoot of lockfileRoots(project)) {
+    const lockfileRecord = await loadNpmLockfile(repositoryRoot, lockfileRoot, cache);
+    if (lockfileRecord.status === 'missing') continue;
+    if (lockfileRecord.status === 'invalid') return unresolved('INVALID_LOCKFILE');
+    if (lockfileRecord.status === 'unsupported') return unresolved('LOCKFILE_UNSUPPORTED');
+    if (lockfileRecord.lockfileVersion === 1) {
+      return resolveFromV1(lockfileRecord, project, dependency, adapter, lockfileRoot);
+    }
+    return resolveFromPackages(lockfileRecord, project, dependency, adapter, lockfileRoot);
+  }
+  return unresolved('LOCKFILE_NOT_FOUND');
+}
+
+/**
+ * Attach deterministic installed-version facts after project/workspace
+ * ownership has been established. Dependency array identity and ordering are
+ * preserved; only additive baseline fields are written.
+ */
+export async function attachInstalledVersionBaselines(repositoryRoot, projects, options = {}) {
+  const registry = options.adapterRegistry ?? createDefaultEcosystemVersionAdapterRegistry();
+  const npmAdapter = getEcosystemVersionAdapter('node', registry);
+  const lockfileCache = new Map();
+  const cooperativeScheduler = options.cooperativeScheduler;
+
+  for (const project of projects) {
+    for (const dependency of project.dependencies) {
+      try {
+        let baseline;
+        if (project.ecosystem !== 'node') {
+          baseline = unresolved('RESOLVED_VERSION_UNAVAILABLE');
+        } else if (project.packageManager?.name && project.packageManager.name !== 'npm') {
+          baseline = unresolved('LOCKFILE_UNSUPPORTED');
+        } else {
+          baseline = await resolveNpmDependency(
+            repositoryRoot,
+            project,
+            dependency,
+            npmAdapter,
+            lockfileCache
+          );
+        }
+        Object.assign(dependency, baseline);
+      } finally {
+        await cooperativeScheduler?.boundary();
+      }
+    }
+  }
+  return projects;
+}

package/src/knowledge-cache.js

@@ -0,0 +1,324 @@
+import { createHash } from 'node:crypto';
+import { mkdir, open, readFile, rename, rm } from 'node:fs/promises';
+import path from 'node:path';
+
+import { canonicalJson, canonicalJsonBytes } from './canonical-json.js';
+import { DEFAULT_OUTPUT_DIRECTORY } from './constants.js';
+import { compareText } from './portable.js';
+
+export const DEFAULT_KNOWLEDGE_CACHE_DIRECTORY =
+  `${DEFAULT_OUTPUT_DIRECTORY}/cache/knowledge/v1`;
+
+const ENVELOPE_VERSION = '1';
+const IDENTITY_FIELDS = [
+  'adapter',
+  'resourceKind',
+  'packageId',
+  'resourceVariant',
+  'adapterVersion'
+];
+const ENVELOPE_FIELDS = [
+  'envelopeVersion',
+  'identity',
+  'storedAt',
+  'expiresAt',
+  'bodyDigest',
+  'body'
+];
+const ISO_UTC_MILLISECONDS = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/;
+const DIGEST = /^sha256:[a-f0-9]{64}$/;
+const FORBIDDEN_BODY_KEYS = new Set([
+  'authorization',
+  'proxyauthorization',
+  'cookie',
+  'setcookie',
+  'etag',
+  'lastmodified',
+  'headers',
+  'cachekey',
+  'stack',
+  'password',
+  'credential',
+  'credentials',
+  'secret',
+  'token',
+  'accesstoken',
+  'apikey',
+  'clientsecret',
+  'privatekey'
+]);
+
+const defaultFileSystem = { mkdir, open, readFile, rename, rm };
+
+export class KnowledgeCacheError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = 'KnowledgeCacheError';
+    this.code = code;
+  }
+}
+
+function sameFields(value, fields) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return false;
+  const keys = Object.keys(value).sort(compareText);
+  return keys.length === fields.length && keys.every((key, index) => key === [...fields].sort(compareText)[index]);
+}
+
+function isUnsafeIdentityValue(value) {
+  return typeof value !== 'string'
+    || value.length === 0
+    || value.trim() !== value
+    || /[\u0000-\u001f\u007f\\\s]/.test(value)
+    || value.startsWith('/')
+    || /^[A-Za-z]:/.test(value)
+    || value.includes('..')
+    || /[a-z][a-z0-9+.-]*:\/\/[^/?#]*@/i.test(value);
+}
+
+function identityError(message) {
+  throw new KnowledgeCacheError('KNOWLEDGE_CACHE_INVALID_IDENTITY', message);
+}
+
+/**
+ * Create the canonical logical identity used for a single cached resource.
+ * The filesystem key is derived internally and is never written to envelopes.
+ */
+export function createCacheIdentity(input) {
+  if (!sameFields(input, IDENTITY_FIELDS)) {
+    identityError('Cache identity must contain exactly the required fields.');
+  }
+  for (const field of IDENTITY_FIELDS) {
+    if (isUnsafeIdentityValue(input[field])) {
+      identityError(`Cache identity field ${field} must be a portable non-empty string.`);
+    }
+  }
+  return Object.freeze(Object.fromEntries(IDENTITY_FIELDS.map((field) => [field, input[field]])));
+}
+
+function identityKey(identity) {
+  return createHash('sha256').update(canonicalJson(identity), 'utf8').digest('hex');
+}
+
+function bodyDigest(body) {
+  return `sha256:${createHash('sha256').update(canonicalJsonBytes(body)).digest('hex')}`;
+}
+
+function normalizedForbiddenKey(key) {
+  return key.toLowerCase().replace(/[-_]/g, '');
+}
+
+function inspectBodyPrivacy(value, currentPath = '$', ancestors = new Set()) {
+  if (typeof value === 'string') {
+    if (value.startsWith('/') || /^[A-Za-z]:[\\/]/.test(value)) {
+      return `${currentPath} contains an absolute path.`;
+    }
+    if (/[a-z][a-z0-9+.-]*:\/\/[^/?#]*@/i.test(value)) {
+      return `${currentPath} contains URL credentials.`;
+    }
+    return null;
+  }
+  if (!value || typeof value !== 'object') return null;
+  if (ancestors.has(value)) return null;
+  ancestors.add(value);
+  try {
+    if (Array.isArray(value)) {
+      for (let index = 0; index < value.length; index += 1) {
+        const result = inspectBodyPrivacy(value[index], `${currentPath}[${index}]`, ancestors);
+        if (result) return result;
+      }
+      return null;
+    }
+    for (const key of Object.keys(value)) {
+      if (FORBIDDEN_BODY_KEYS.has(normalizedForbiddenKey(key))) {
+        return `${currentPath}.${key} is not permitted in a cache body.`;
+      }
+      const result = inspectBodyPrivacy(value[key], `${currentPath}.${key}`, ancestors);
+      if (result) return result;
+    }
+    return null;
+  } finally {
+    ancestors.delete(value);
+  }
+}
+
+function sanitizeBody(body) {
+  let canonical;
+  try {
+    canonical = canonicalJson(body);
+  } catch {
+    throw new KnowledgeCacheError('KNOWLEDGE_CACHE_INVALID_BODY', 'Cache body must be JSON-compatible.');
+  }
+  const privacyError = inspectBodyPrivacy(body);
+  if (privacyError) {
+    throw new KnowledgeCacheError('KNOWLEDGE_CACHE_INVALID_BODY', `Cache body is not portable: ${privacyError}`);
+  }
+  return JSON.parse(canonical);
+}
+
+function validUtcDate(value) {
+  if (typeof value !== 'string' || !ISO_UTC_MILLISECONDS.test(value)) return null;
+  const date = new Date(value);
+  return Number.isNaN(date.getTime()) || date.toISOString() !== value ? null : date;
+}
+
+function resultForEnvelope(envelope, now) {
+  const expiresAt = new Date(envelope.expiresAt);
+  return {
+    status: now.getTime() < expiresAt.getTime() ? 'fresh' : 'expired',
+    body: envelope.body,
+    storedAt: envelope.storedAt,
+    expiresAt: envelope.expiresAt,
+    bodyDigest: envelope.bodyDigest
+  };
+}
+
+function validateEnvelope(envelope, expectedIdentity) {
+  if (!sameFields(envelope, ENVELOPE_FIELDS)) return { valid: false, reason: 'unexpected-envelope-fields' };
+  if (envelope.envelopeVersion !== ENVELOPE_VERSION) return { valid: false, reason: 'unsupported-envelope-version' };
+
+  let identity;
+  try {
+    identity = createCacheIdentity(envelope.identity);
+  } catch {
+    return { valid: false, reason: 'invalid-identity' };
+  }
+  if (canonicalJson(identity) !== canonicalJson(expectedIdentity)) {
+    return { valid: false, reason: 'identity-mismatch' };
+  }
+  const storedAt = validUtcDate(envelope.storedAt);
+  const expiresAt = validUtcDate(envelope.expiresAt);
+  if (!storedAt || !expiresAt || expiresAt.getTime() < storedAt.getTime()) {
+    return { valid: false, reason: 'invalid-timestamps' };
+  }
+  if (typeof envelope.bodyDigest !== 'string' || !DIGEST.test(envelope.bodyDigest)) {
+    return { valid: false, reason: 'invalid-body-digest' };
+  }
+  try {
+    const normalizedBody = sanitizeBody(envelope.body);
+    if (bodyDigest(normalizedBody) !== envelope.bodyDigest) {
+      return { valid: false, reason: 'body-digest-mismatch' };
+    }
+  } catch {
+    return { valid: false, reason: 'invalid-body' };
+  }
+  return { valid: true };
+}
+
+function currentDate(clock) {
+  const value = clock();
+  const date = value instanceof Date ? new Date(value.getTime()) : new Date(value);
+  if (Number.isNaN(date.getTime())) {
+    throw new KnowledgeCacheError('KNOWLEDGE_CACHE_INVALID_CLOCK', 'Knowledge Store clock returned an invalid time.');
+  }
+  return date;
+}
+
+function ttlDate(storedAt, ttlMs) {
+  if (!Number.isSafeInteger(ttlMs) || ttlMs < 0) {
+    throw new KnowledgeCacheError('KNOWLEDGE_CACHE_INVALID_TTL', 'Cache TTL must be a non-negative integer number of milliseconds.');
+  }
+  const expiresAt = new Date(storedAt.getTime() + ttlMs);
+  if (Number.isNaN(expiresAt.getTime())) {
+    throw new KnowledgeCacheError('KNOWLEDGE_CACHE_INVALID_TTL', 'Cache TTL produces an invalid expiry time.');
+  }
+  return expiresAt;
+}
+
+function operationalError(code, message) {
+  return new KnowledgeCacheError(code, message);
+}
+
+/**
+ * Construct the small private filesystem cache used by future registry
+ * adapters. Its root and storage layout are intentionally absent from the
+ * Knowledge Manifest contract.
+ */
+export function createKnowledgeCache({
+  rootDirectory = DEFAULT_KNOWLEDGE_CACHE_DIRECTORY,
+  clock = () => new Date(),
+  fileSystem = defaultFileSystem
+} = {}) {
+  if (typeof rootDirectory !== 'string' || rootDirectory.length === 0) {
+    throw new KnowledgeCacheError('KNOWLEDGE_CACHE_INVALID_ROOT', 'Knowledge Store root directory must be a non-empty string.');
+  }
+  if (typeof clock !== 'function') {
+    throw new KnowledgeCacheError('KNOWLEDGE_CACHE_INVALID_CLOCK', 'Knowledge Store clock must be a function.');
+  }
+  for (const method of ['mkdir', 'open', 'readFile', 'rename', 'rm']) {
+    if (typeof fileSystem?.[method] !== 'function') {
+      throw new KnowledgeCacheError('KNOWLEDGE_CACHE_INVALID_FILESYSTEM', 'Knowledge Store filesystem adapter is incomplete.');
+    }
+  }
+
+  let temporarySequence = 0;
+  const entryPath = (identity) => path.join(rootDirectory, `${identityKey(createCacheIdentity(identity))}.json`);
+
+  return {
+    async read(identity) {
+      const expectedIdentity = createCacheIdentity(identity);
+      let text;
+      try {
+        text = await fileSystem.readFile(entryPath(expectedIdentity), 'utf8');
+      } catch (error) {
+        if (error?.code === 'ENOENT') return { status: 'missing' };
+        throw operationalError('KNOWLEDGE_CACHE_READ_FAILED', 'Unable to read Knowledge Store entry.');
+      }
+
+      let envelope;
+      try {
+        envelope = JSON.parse(text);
+      } catch {
+        return { status: 'corrupted', reason: 'invalid-json' };
+      }
+      const validation = validateEnvelope(envelope, expectedIdentity);
+      if (!validation.valid) return { status: 'corrupted', reason: validation.reason };
+      return resultForEnvelope(envelope, currentDate(clock));
+    },
+
+    async write(identity, body, { ttlMs } = {}) {
+      const normalizedIdentity = createCacheIdentity(identity);
+      const normalizedBody = sanitizeBody(body);
+      const storedAtDate = currentDate(clock);
+      const expiresAtDate = ttlDate(storedAtDate, ttlMs);
+      const envelope = {
+        envelopeVersion: ENVELOPE_VERSION,
+        identity: normalizedIdentity,
+        storedAt: storedAtDate.toISOString(),
+        expiresAt: expiresAtDate.toISOString(),
+        bodyDigest: bodyDigest(normalizedBody),
+        body: normalizedBody
+      };
+      const finalPath = entryPath(normalizedIdentity);
+      const temporaryPath = `${finalPath}.${process.pid}.${temporarySequence += 1}.tmp`;
+      const serialized = `${JSON.stringify(envelope, null, 2)}\n`;
+      let handle;
+      try {
+        await fileSystem.mkdir(path.dirname(finalPath), { recursive: true });
+        handle = await fileSystem.open(temporaryPath, 'w', 0o600);
+        await handle.writeFile(serialized, 'utf8');
+        await handle.sync();
+        await handle.close();
+        handle = undefined;
+        await fileSystem.rename(temporaryPath, finalPath);
+      } catch {
+        try {
+          if (handle) await handle.close();
+        } catch {
+          // Closing is best effort after an already-failed write.
+        }
+        try {
+          await fileSystem.rm(temporaryPath, { force: true });
+        } catch {
+          // Cleanup is best effort; the final entry remains protected by rename.
+        }
+        throw operationalError('KNOWLEDGE_CACHE_WRITE_FAILED', 'Unable to write Knowledge Store entry.');
+      }
+      return {
+        status: 'written',
+        storedAt: envelope.storedAt,
+        expiresAt: envelope.expiresAt,
+        bodyDigest: envelope.bodyDigest
+      };
+    }
+  };
+}

package/src/knowledge-evidence-bundle.js

@@ -0,0 +1,101 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+
+import Ajv2020 from 'ajv/dist/2020.js';
+import addFormats from 'ajv-formats';
+
+import { compareText, isSorted } from './portable.js';
+
+export const KNOWLEDGE_EVIDENCE_BUNDLE_SCHEMA_VERSION = '1.0.0';
+
+const schema = JSON.parse(await readFile(
+  new URL('../schemas/knowledge-evidence-bundle.schema.json', import.meta.url),
+  'utf8'
+));
+const ajv = new Ajv2020({ allErrors: true, strict: true, strictRequired: false });
+addFormats(ajv);
+const validateSchema = ajv.compile(schema);
+
+const compareEvidence = (left, right) => compareText(left.id, right.id);
+const compareWarnings = (left, right) => {
+  const fields = ['packageId', 'sourceId', 'code', 'message'];
+  for (const field of fields) {
+    const result = compareText(left[field] ?? '', right[field] ?? '');
+    if (result !== 0) return result;
+  }
+  return 0;
+};
+
+function digestText(value) {
+  return `sha256:${createHash('sha256').update(value, 'utf8').digest('hex')}`;
+}
+
+function duplicateValues(values) {
+  const seen = new Set();
+  const duplicates = new Set();
+  for (const value of values) {
+    if (seen.has(value)) duplicates.add(value);
+    seen.add(value);
+  }
+  return [...duplicates].sort(compareText);
+}
+
+function addMismatch(errors, field, actual, expected) {
+  if (actual !== expected) errors.push(`${field} is ${actual}; expected ${expected}.`);
+}
+
+/**
+ * Validate Knowledge Evidence Bundle relationships that JSON Schema cannot
+ * express. Cross-artifact source/package checks happen in the VA-02 loader.
+ */
+export function validateKnowledgeEvidenceBundleInvariants(bundle) {
+  const errors = [];
+  const evidence = bundle.evidence ?? [];
+  const warnings = bundle.warnings ?? [];
+
+  if (!isSorted(evidence, compareEvidence)) errors.push('evidence must be sorted by id.');
+  if (!isSorted(warnings, compareWarnings)) {
+    errors.push('warnings must be sorted by packageId, sourceId, code, and message.');
+  }
+
+  for (const duplicate of duplicateValues(evidence.map((item) => item.id))) {
+    errors.push(`Duplicate evidence id ${duplicate}.`);
+  }
+
+  const packageIds = new Set();
+  const sourceIds = new Set();
+  for (const item of evidence) {
+    packageIds.add(item.packageId);
+    sourceIds.add(item.sourceId);
+    if (!isSorted(item.releaseVersions, compareText)) {
+      errors.push(`Evidence ${item.id} releaseVersions must be sorted lexically.`);
+    }
+    const actualDigest = digestText(item.content);
+    if (item.contentDigest !== actualDigest) {
+      errors.push(`Evidence ${item.id} contentDigest is ${item.contentDigest}; expected ${actualDigest}.`);
+    }
+  }
+
+  addMismatch(errors, 'summary.evidenceCount', bundle.summary?.evidenceCount, evidence.length);
+  addMismatch(errors, 'summary.packageCount', bundle.summary?.packageCount, packageIds.size);
+  addMismatch(errors, 'summary.sourceCount', bundle.summary?.sourceCount, sourceIds.size);
+  addMismatch(errors, 'summary.warningCount', bundle.summary?.warningCount, warnings.length);
+
+  return errors.sort(compareText);
+}
+
+export function validateKnowledgeEvidenceBundle(bundle) {
+  if (bundle?.schemaVersion !== KNOWLEDGE_EVIDENCE_BUNDLE_SCHEMA_VERSION) {
+    throw new Error(
+      `Knowledge Evidence Bundle schema validation failed: unsupported schema version; expected ${KNOWLEDGE_EVIDENCE_BUNDLE_SCHEMA_VERSION}.`
+    );
+  }
+  if (!validateSchema(bundle)) {
+    throw new Error(`Knowledge Evidence Bundle schema validation failed: ${ajv.errorsText(validateSchema.errors, { separator: '; ' })}`);
+  }
+  const invariantErrors = validateKnowledgeEvidenceBundleInvariants(bundle);
+  if (invariantErrors.length > 0) {
+    throw new Error(`Knowledge Evidence Bundle runtime invariants failed: ${invariantErrors.join(' ')}`);
+  }
+  return bundle;
+}