@tiangong-lca/pcr 0.0.0-stage → 0.1.2

package/packages/pcr-core/src/index.mjs

@@ -0,0 +1,2101 @@
+import { pcrSource } from "./source-context.mjs";
+import { createHash } from "node:crypto";
+import {
+  closeSync,
+  constants as fsConstants,
+  fstatSync,
+  lstatSync,
+  openSync,
+  readFileSync,
+  realpathSync,
+  readdirSync,
+} from "node:fs";
+import path from "node:path";
+import { TextDecoder } from "node:util";
+
+import {
+  PcrClassificationCodeUnknownError,
+  PcrClassificationCoverageSemanticError,
+  readClassificationCoverage,
+  readClassificationCoverageSnapshot,
+} from "./classification-coverage.mjs";
+import { assertCoreContract, validateCoreContract } from "./contracts.mjs";
+import {
+  inspectProjectionIntegrity,
+  projectionNotRequiredState,
+} from "./projection-integrity.mjs";
+import {
+  hasDeclaredUnresolvedReferenceProductFlow,
+  materialProjectionCompletenessIssues,
+} from "./projection-completeness.mjs";
+import { findPcrIdAlias as findRepositoryPcrIdAlias } from "./pcr-id-aliases.mjs";
+import {
+  assertPcrReadContextFresh,
+  createPcrReadContext,
+  getPcrReadContextCatalog,
+  observePcrReadContextArtifactRead,
+  pcrReadContextAliasInputFingerprint,
+  withPcrReadContextSession,
+} from "./read-context.mjs";
+import { parseYaml } from "./yaml-lite.mjs";
+import {
+  declaredPcrLanguages,
+  expectedPcrArtifactHashes,
+  LEGACY_PCR_ARTIFACT_HASH_FIELDS,
+  pcrArtifactFiles,
+} from "./languages.mjs";
+import {
+  CLASSIFICATION_MAPPING_RELATION_VALUES,
+  CONTENT_MATURITY_VALUES,
+  FEEDBACK_TYPE_VALUES,
+  PCR_STATUS_VALUES,
+} from "./generated/controlled-vocabulary.mjs";
+
+export const FEEDBACK_TYPES = FEEDBACK_TYPE_VALUES;
+export { createPcrReadContext, pcrReadContextAliasInputFingerprint, withPcrReadContextSession };
+export {
+  CLASSIFICATION_COVERAGE_STATUSES,
+  PcrClassificationCodeUnknownError,
+  PcrClassificationCoverageNotFoundError,
+  PcrClassificationCoverageSemanticError,
+  PcrClassificationCoverageStatusError,
+  classificationCoveragePath,
+  findClassificationCoverageEntry,
+  getClassificationCoverageSummary,
+  hasClassificationCoverage,
+  listClassificationCoverage,
+  readClassificationCoverage,
+  readClassificationCoverageSnapshot,
+} from "./classification-coverage.mjs";
+export const PCR_CATALOG_SCOPES = Object.freeze(["all", "material", "legacy"]);
+export const PCR_RECORD_KINDS = Object.freeze([
+  "methodology",
+  "legacy_scaffold_reference",
+  "invalid_lifecycle_state",
+]);
+const CLASSIFICATION_MAPPING_RELATIONS = new Set(CLASSIFICATION_MAPPING_RELATION_VALUES);
+const PCR_CATALOG_SCOPE_SET = new Set(PCR_CATALOG_SCOPES);
+const METHODOLOGY_LIFECYCLE_STATUSES = new Set(
+  PCR_STATUS_VALUES.filter((value) => value !== "scaffold"),
+);
+const METHODOLOGY_MATURITIES = new Set(
+  CONTENT_MATURITY_VALUES.filter((value) => value !== "empty_scaffold"),
+);
+
+const CURRENT_SNAPSHOT_MAX_ATTEMPTS = 3;
+const pcrCatalogCache = new Map();
+const RELEASE_ARTIFACTS = LEGACY_PCR_ARTIFACT_HASH_FIELDS;
+const GUIDANCE_MATURITIES = new Set([
+  "authored_methodology",
+  "reviewed_methodology",
+  "published_methodology",
+]);
+const REVIEWED_MATURITIES = new Set(["reviewed_methodology", "published_methodology"]);
+const USABLE_LIFECYCLE_STATES = new Map([
+  ["candidate", new Set(["authored_methodology"])],
+  ["active", new Set(["reviewed_methodology"])],
+  ["published", new Set(["published_methodology"])],
+]);
+const GUIDANCE_LIFECYCLE_STATUSES = new Set(["candidate", "active", "published"]);
+
+export class PcrUsabilityError extends Error {
+  constructor({ pcrId, operation, readiness }) {
+    const blockers = readiness.blockers.map((blocker) => blocker.code).join(", ");
+    super(
+      `PCR ${pcrId} is not usable for ${operation}: content_maturity=${readiness.methodology_status}; blockers=${blockers || "unknown"}`,
+    );
+    this.name = "PcrUsabilityError";
+    this.code = `PCR_NOT_USABLE_FOR_${operation.toUpperCase()}`;
+    this.readiness = structuredClone(readiness);
+  }
+}
+
+export class PcrClassificationMappingError extends Error {
+  constructor({ system, version, code, mappingType, issue = null }) {
+    super(issue
+      ? `Classification mapping ${system}:${version}:${code} is not an accepted current mapping: ${issue}.`
+      : `Classification mapping ${system}:${version}:${code} uses unsupported mapping_type ${String(mappingType)}.`);
+    this.name = "PcrClassificationMappingError";
+    this.code = "PCR_INVALID_CLASSIFICATION_MAPPING";
+    this.details = {
+      classification: `${system}:${version}:${code}`,
+      mapping_type: mappingType ?? null,
+      allowed_mapping_types: [...CLASSIFICATION_MAPPING_RELATION_VALUES],
+      issue,
+    };
+  }
+}
+
+export class PcrLegacyIdRedirectError extends Error {
+  constructor(alias) {
+    const redirect = legacyPcrIdRedirect(alias);
+    super(
+      `PCR id ${redirect.source_pcr_id} is a retired legacy identity. ` +
+        `Use the redirect target with: ${redirect.next_command}`,
+    );
+    this.name = "PcrLegacyIdRedirectError";
+    this.code = "PCR_LEGACY_ID_REDIRECT";
+    this.details = redirect;
+  }
+}
+
+export class PcrClassificationTargetStateError extends Error {
+  constructor({ system, version, code, pcr }) {
+    super(
+      `Classification mapping ${system}:${version}:${code} points to PCR ${pcr.id} with invalid ` +
+        `lifecycle identity ${pcr.status}/${pcr.content_maturity}.`,
+    );
+    this.name = "PcrClassificationTargetStateError";
+    this.code = "PCR_INVALID_CLASSIFICATION_TARGET";
+    this.details = {
+      classification: `${system}:${version}:${code}`,
+      pcr_id: pcr.id,
+      status: pcr.status,
+      content_maturity: pcr.content_maturity,
+      record_kind: pcr.record_kind,
+    };
+  }
+}
+
+export class PcrCurrentSnapshotInconsistentError extends Error {
+  constructor({ pcrId, pcrPath, attempts, lastFailure }) {
+    super(
+      `PCR ${pcrId} current snapshot could not be read consistently after ${attempts} attempts.`,
+    );
+    this.name = "PcrCurrentSnapshotInconsistentError";
+    this.code = "PCR_CURRENT_SNAPSHOT_INCONSISTENT";
+    this.details = {
+      pcr_id: pcrId,
+      pcr_path: pcrPath,
+      attempts,
+      last_failure: lastFailure,
+    };
+  }
+}
+
+export class PcrDuplicateIdError extends Error {
+  constructor({ pcrId, paths }) {
+    super(`Duplicate canonical PCR id ${pcrId}: ${paths.join(", ")}`);
+    this.name = "PcrDuplicateIdError";
+    this.code = "PCR_DUPLICATE_ID";
+    this.details = { pcr_id: pcrId, paths: [...paths] };
+  }
+}
+
+export class PcrCatalogScopeError extends Error {
+  constructor(scope) {
+    super(`Unsupported PCR catalog scope ${String(scope)}. Expected one of: ${PCR_CATALOG_SCOPES.join(", ")}.`);
+    this.name = "PcrCatalogScopeError";
+    this.code = "PCR_INVALID_CATALOG_SCOPE";
+    this.details = {
+      scope: String(scope),
+      allowed_scopes: [...PCR_CATALOG_SCOPES],
+    };
+  }
+}
+
+function findPcrIdAlias(options) {
+  const source = pcrSource(options.root);
+  return source ? source.findAlias(options.pcrId) : findRepositoryPcrIdAlias(options);
+}
+
+export function listPcrs({ root, refresh = false, scope = "all" }) {
+  if (pcrSource(root)) return pcrSource(root).listPcrs(normalizeCatalogScope(scope));
+  const normalizedScope = normalizeCatalogScope(scope);
+  const normalizedRoot = path.resolve(root);
+  const catalog = getPcrCatalog({ root: normalizedRoot, refresh });
+  const candidates = normalizedScope === "all"
+    ? catalog
+    : catalog.filter((entry) => currentCatalogEntryMatchesScope(normalizedRoot, entry, normalizedScope));
+  return candidates
+    .map((entry) => currentPcrEntry(normalizedRoot, entry))
+    .filter((entry) => recordMatchesScope(entry, normalizedScope));
+}
+
+function getPcrCatalog({ root, refresh = false }) {
+  const normalizedRoot = path.resolve(root);
+  if (refresh || !pcrCatalogCache.has(normalizedRoot)) {
+    pcrCatalogCache.set(normalizedRoot, readPcrCatalog(normalizedRoot));
+  }
+  return pcrCatalogCache.get(normalizedRoot);
+}
+
+function readPcrCatalog(root) {
+  const pcrRoot = path.join(root, "library/pcrs");
+  if (!isCanonicalDirectory(pcrRoot)) {
+    throw new Error(`PCR catalog root not found: ${toPosix(path.relative(root, pcrRoot))}`);
+  }
+  const catalog = findManifestFiles(pcrRoot)
+    .map((manifestPath) => {
+      const manifest = parseYaml(readCanonicalFileBytes(manifestPath).toString("utf8"));
+      const pcrDir = path.dirname(manifestPath);
+      return {
+        id: manifest.id,
+        path: toPosix(path.relative(root, pcrDir)),
+        manifestPath,
+      };
+    })
+    .filter((entry) => entry.id);
+  const entriesById = new Map();
+  for (const entry of catalog) {
+    const existing = entriesById.get(entry.id);
+    if (existing) {
+      throw new PcrDuplicateIdError({
+        pcrId: entry.id,
+        paths: [existing.path, entry.path].sort(),
+      });
+    }
+    entriesById.set(entry.id, entry);
+  }
+  return catalog.sort((left, right) => left.id.localeCompare(right.id));
+}
+
+export function buildPcrTree({ root, depth = Infinity, scope = "all" }) {
+  const tree = {};
+  for (const pcr of listPcrs({ root, scope })) {
+    const segments = pcr.path.replace(/^library\/pcrs\//u, "").split("/");
+    let node = tree;
+    for (const [index, segment] of segments.entries()) {
+      if (index >= depth) {
+        break;
+      }
+      node[segment] ??= { children: {}, pcrs: [] };
+      if (index === segments.length - 1) {
+        node[segment].pcrs.push(pcr);
+      }
+      node = node[segment].children;
+    }
+  }
+  return tree;
+}
+
+export function resolveClassification({ root, system, version, code, context = null }) {
+  const normalizedSystem = String(system).toLowerCase();
+  const normalizedVersion = String(version);
+  const normalizedCode = String(code);
+  const coverageIndex = readClassificationCoverage({
+    root,
+    system: normalizedSystem,
+    version: normalizedVersion,
+  });
+  return resolveClassificationWithCoverage({
+    root,
+    system: normalizedSystem,
+    version: normalizedVersion,
+    code: normalizedCode,
+    coverageIndex,
+    context,
+  });
+}
+
+export function verifyDistributionCoverage({ root, snapshot, context }) {
+  const coverageIndex = snapshot.document;
+  for (const entry of coverageIndex.entries) {
+    if (entry.coverage_status === "mapped" || entry.legacy_reference) {
+      resolveClassificationWithCoverage({ root, system: String(coverageIndex.classification_system).toLowerCase(),
+        version: String(coverageIndex.classification_version), code: String(entry.code), coverageIndex, context });
+    }
+  }
+}
+
+function resolveClassificationWithCoverage({ root, system, version, code, coverageIndex, context = null }) {
+  const coverage = coverageIndex.entries.find(
+    (candidate) => String(candidate.code) === String(code),
+  );
+  if (!coverage) {
+    throw new PcrClassificationCodeUnknownError({ system, version, code });
+  }
+  if (coverage.coverage_status === "mapped") {
+    const canonical = readCanonicalClassificationMapping({
+      root,
+      system,
+      version,
+      code,
+    });
+    assertCoverageMappingMatchesCanonical({ coverage, canonical, system, version, code });
+    const pcr = getPcrById({ root, pcrId: canonical.mapping.pcr_id, context });
+    if (pcr.record_kind !== "methodology") {
+      throw invalidCoverageResolution({
+        system,
+        version,
+        code,
+        issue: `mapped coverage points to non-material PCR ${pcr.id}`,
+      });
+    }
+    return {
+      classification_system: canonical.mappingFile.classification_system,
+      classification_version: canonical.mappingFile.classification_version,
+      mapping: canonical.mapping,
+      pcr,
+      resolution_status: "mapped",
+      coverage_status: coverage.coverage_status,
+      coverage,
+    };
+  }
+
+  if (coverage.legacy_reference) {
+    const canonical = readCanonicalClassificationMapping({
+      root,
+      system,
+      version,
+      code,
+    });
+    if (canonical.mapping.pcr_id !== coverage.legacy_reference.pcr_id) {
+      throw invalidCoverageResolution({
+        system,
+        version,
+        code,
+        issue: `legacy reference ${coverage.legacy_reference.pcr_id} does not match canonical mapping ${canonical.mapping.pcr_id}`,
+      });
+    }
+    const pcr = getPcrById({ root, pcrId: canonical.mapping.pcr_id, context });
+    if (pcr.record_kind !== "legacy_scaffold_reference") {
+      throw invalidCoverageResolution({
+        system,
+        version,
+        code,
+        issue: `legacy reference points to material PCR ${pcr.id}`,
+      });
+    }
+    return {
+      classification_system: canonical.mappingFile.classification_system,
+      classification_version: canonical.mappingFile.classification_version,
+      mapping: canonical.mapping,
+      pcr,
+      resolution_status: "legacy_scaffold_compatibility",
+      coverage_status: coverage.coverage_status,
+      coverage,
+    };
+  }
+
+  return {
+    classification_system: String(coverageIndex.classification_system),
+    classification_version: String(coverageIndex.classification_version),
+    mapping: null,
+    pcr: null,
+    resolution_status: "unmapped",
+    coverage_status: coverage.coverage_status,
+    coverage,
+    review_candidate:
+      ["manual_review", "unknown"].includes(coverage.coverage_status) && coverage.mapping
+        ? structuredClone(coverage.mapping)
+        : null,
+  };
+}
+
+function readCanonicalClassificationMapping({ root, system, version, code }) {
+  const normalizedRoot = path.resolve(root);
+  const mappingPath = path.join(
+    normalizedRoot,
+    "classifications/mappings",
+    `${system}-${version}-to-pcr.yaml`,
+  );
+  const mappingRelativePath = toPosix(path.relative(normalizedRoot, mappingPath));
+  let mappingFile;
+  try {
+    const mappingBytes = pcrSource(root)?.readFile(mappingRelativePath) ?? readControlledRepositoryFileBytes({
+      root: normalizedRoot,
+      filePath: mappingPath,
+      relativePath: mappingRelativePath,
+      label: "classification mapping",
+    });
+    mappingFile = parseYaml(new TextDecoder("utf-8", { fatal: true }).decode(mappingBytes));
+  } catch (error) {
+    if (error instanceof PcrClassificationMappingError) {
+      throw error;
+    }
+    throw new PcrClassificationMappingError({
+      system,
+      version,
+      code,
+      issue:
+        `canonical mapping source ${mappingRelativePath} could not be read safely ` +
+        `(${error instanceof Error ? error.message : String(error)})`,
+    });
+  }
+  assertCurrentAcceptedMappingDocument({ mappingFile, system, version, code });
+  const matches = (mappingFile.mappings ?? []).filter(
+    (entry) => String(entry.code) === String(code),
+  );
+  if (matches.length === 0) {
+    throw new Error(`No PCR mapping found for ${system}:${version}:${code}`);
+  }
+  if (matches.length !== 1) {
+    throw new PcrClassificationMappingError({
+      system,
+      version,
+      code,
+      issue: `expected one selected edge, found ${matches.length}`,
+    });
+  }
+  const mapping = matches[0];
+  if (
+    !CLASSIFICATION_MAPPING_RELATIONS.has(mapping.mapping_type)
+    || mapping.mapping_type === "manual_review"
+  ) {
+    throw new PcrClassificationMappingError({
+      system,
+      version,
+      code,
+      mappingType: mapping.mapping_type,
+    });
+  }
+  assertAcceptedMappingDecision({ mapping, system, version, code });
+  return { mappingFile, mapping };
+}
+
+function assertCurrentAcceptedMappingDocument({ mappingFile, system, version, code }) {
+  if (mappingFile?.schema_version !== 2 || mappingFile?.status !== "current") {
+    throw new PcrClassificationMappingError({
+      system,
+      version,
+      code,
+      issue:
+        `expected schema_version 2 with status current, found ` +
+        `${String(mappingFile?.schema_version)}/${String(mappingFile?.status)}`,
+    });
+  }
+  if (
+    String(mappingFile.classification_system).toLowerCase() !== String(system).toLowerCase()
+    || String(mappingFile.classification_version) !== String(version)
+    || !Array.isArray(mappingFile.mappings)
+  ) {
+    throw new PcrClassificationMappingError({
+      system,
+      version,
+      code,
+      issue: "mapping document coordinate or mappings array does not match the requested classification",
+    });
+  }
+}
+
+function assertAcceptedMappingDecision({ mapping, system, version, code }) {
+  const acceptance = mapping?.acceptance;
+  if (
+    acceptance?.status !== "accepted"
+    || typeof acceptance?.decided_by !== "string"
+    || acceptance.decided_by.trim().length === 0
+    || !isRealCanonicalUtcTimestamp(acceptance?.decided_at_utc)
+    || typeof acceptance?.decision_ref !== "string"
+    || !/^(?:docs|classifications\/migrations)\/[A-Za-z0-9][A-Za-z0-9._/-]*\.(?:md|ya?ml|json)(?:#[A-Za-z0-9][A-Za-z0-9._-]*)?$/u.test(
+      acceptance.decision_ref,
+    )
+  ) {
+    throw new PcrClassificationMappingError({
+      system,
+      version,
+      code,
+      mappingType: mapping?.mapping_type,
+      issue:
+        "selected edge requires acceptance.status=accepted, decided_by, strict decided_at_utc, and decision_ref",
+    });
+  }
+}
+
+function isRealCanonicalUtcTimestamp(value) {
+  const match = typeof value === "string"
+    ? /^([0-9]{4})-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9])(?:\.[0-9]+)?Z$/u.exec(value)
+    : null;
+  if (!match) {
+    return false;
+  }
+  const [, year, month, day, hour, minute, second] = match.map(Number);
+  const parsed = new Date(0);
+  parsed.setUTCFullYear(year, month - 1, day);
+  parsed.setUTCHours(hour, minute, second, 0);
+  return (
+    parsed.getUTCFullYear() === year
+    && parsed.getUTCMonth() === month - 1
+    && parsed.getUTCDate() === day
+    && parsed.getUTCHours() === hour
+    && parsed.getUTCMinutes() === minute
+    && parsed.getUTCSeconds() === second
+  );
+}
+
+function assertCoverageMappingMatchesCanonical({ coverage, canonical, system, version, code }) {
+  const coverageMapping = coverage.mapping;
+  const canonicalMapping = canonical.mapping;
+  for (const field of ["pcr_id", "mapping_type", "confidence"]) {
+    if (String(coverageMapping?.[field]) !== String(canonicalMapping?.[field])) {
+      throw invalidCoverageResolution({
+        system,
+        version,
+        code,
+        issue: `coverage mapping ${field} ${String(coverageMapping?.[field])} does not match canonical mapping ${String(canonicalMapping?.[field])}`,
+      });
+    }
+  }
+  for (const field of ["status", "decided_by", "decided_at_utc", "decision_ref"]) {
+    if (
+      String(coverageMapping?.acceptance?.[field])
+      !== String(canonicalMapping?.acceptance?.[field])
+    ) {
+      throw invalidCoverageResolution({
+        system,
+        version,
+        code,
+        issue:
+          `coverage mapping acceptance.${field} ${String(coverageMapping?.acceptance?.[field])} ` +
+          `does not match canonical mapping ${String(canonicalMapping?.acceptance?.[field])}`,
+      });
+    }
+  }
+}
+
+function invalidCoverageResolution({ system, version, code, issue }) {
+  return new PcrClassificationCoverageSemanticError({
+    system,
+    version,
+    source: `classifications/indexes/${system}-${version}-coverage.json`,
+    issues: [`entry ${code}: ${issue}`],
+  });
+}
+
+/**
+ * Resolve a PCR identity without silently following a retired id. Alias
+ * lookup intentionally happens before catalog lookup, including while the
+ * old scaffold directory still exists during a staged migration.
+ */
+export function resolvePcrIdentity({ root, pcrId, context = null }) {
+  const readRoot = root ?? context?.root;
+  const normalizedPcrId = String(pcrId);
+  const alias = findPcrIdAlias({ root: readRoot, pcrId: normalizedPcrId, context });
+  if (alias) {
+    return {
+      resolution_status: "legacy_id_redirect",
+      requested_pcr_id: normalizedPcrId,
+      redirect: legacyPcrIdRedirect(alias),
+      pcr: null,
+    };
+  }
+  return {
+    resolution_status: "canonical",
+    requested_pcr_id: normalizedPcrId,
+    redirect: null,
+    pcr: getCurrentPcrSnapshotUnchecked({ root: readRoot, pcrId: normalizedPcrId, context }).pcr,
+  };
+}
+
+function legacyPcrIdRedirect(alias) {
+  return {
+    source_pcr_id: alias.source_pcr_id,
+    source_pcr_path: alias.source_pcr_path,
+    target: structuredClone(alias.target),
+    reason: alias.reason,
+    decision_ref: alias.decision_ref,
+    next_command: nextCommandForLegacyPcrAlias(alias.target),
+  };
+}
+
+function nextCommandForLegacyPcrAlias(target) {
+  if (target.kind === "classification_coverage") {
+    return (
+      "npm --silent run tiangong-pcr -- resolve --classification " +
+      `${target.classification_system}:${target.classification_version}:${target.code} --format json`
+    );
+  }
+  return (
+    "npm --silent run tiangong-pcr -- resolve --pcr " +
+    `${target.pcr_id} --format json`
+  );
+}
+
+function throwIfLegacyPcrId({ root, pcrId, context = null }) {
+  const alias = findPcrIdAlias({ root, pcrId: String(pcrId), context });
+  if (alias) {
+    throw new PcrLegacyIdRedirectError(alias);
+  }
+}
+
+export function getPcrById({ root, pcrId, refresh = false, context = null }) {
+  return getCurrentPcrSnapshot({ root: root ?? context?.root, pcrId, refresh, context }).pcr;
+}
+
+export function getPcrReadiness({ root, pcrId, refresh = false, context = null }) {
+  return structuredClone(getPcrById({ root: root ?? context?.root, pcrId, refresh, context }).readiness);
+}
+
+export function readPcrMarkdown({ root, pcrId, language = "en-US", context = null }) {
+  const readRoot = root ?? context?.root;
+  const snapshot = getCurrentPcrSnapshot({ root: readRoot, pcrId, context });
+  if (pcrSource(readRoot) && !pcrSource(readRoot).languages.includes(language)) {
+    throw Object.assign(new Error(`Offline library contains English only; requested ${language}. Use --lang en-US.`), { code: "PCR_LIBRARY_LANGUAGE_UNAVAILABLE" });
+  }
+  const markdownName = `pcr.${language}.md`;
+  const markdownPath = path.join(readRoot, snapshot.pcr.path, markdownName);
+  const artifact = snapshot.artifacts[markdownName];
+  if (!artifact?.bytes) {
+    throw new Error(`PCR Markdown not found: ${toPosix(path.relative(readRoot, markdownPath))}`);
+  }
+  return artifact.bytes.toString("utf8");
+}
+
+/** A complete current document, read once through the same integrity boundary as guidance. */
+export function readPcrDocumentBundle({ root, pcrId, context = null }) {
+  root = root ?? context?.root;
+  const snapshot = getCurrentPcrSnapshot({ root, pcrId, context });
+  const { pcr, manifest, manifestBytes, structured } = snapshot;
+  assertPcrUsable({ pcr, operation: "guidance" });
+  const languages = pcrSource(root)?.languages ?? declaredPcrLanguages(manifest);
+  if (![1, 2].includes(manifest.schema_version)) throw new Error(`Unsupported document manifest schema: ${manifest.schema_version}`);
+  for (const language of languages) if (typeof manifest.title?.[language] !== "string" || !manifest.title[language].trim()) throw new Error(`Document requires a nonempty ${language} title.`);
+  const artifacts = {};
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  for (const name of ["manifest.yaml", ...(pcrSource(root) ? [...languages.map((language) => `pcr.${language}.md`), "structured.yaml"] : pcrArtifactFiles(manifest))]) {
+    const bytes = name === "manifest.yaml" ? manifestBytes : snapshot.artifacts[name]?.bytes;
+    if (!bytes) throw new Error(`PCR document artifact is unavailable: ${pcr.path}/${name}`);
+    // A copy prevents consumers from changing a cached snapshot through Buffer aliasing.
+    const copy = Buffer.from(bytes);
+    const text = decoder.decode(copy);
+    if (!text.trim()) throw new Error(`PCR document artifact is empty: ${pcr.path}/${name}`);
+    artifacts[name] = {
+      path: `${pcr.path}/${name}`,
+      bytes: copy,
+      text,
+      sha256: exactByteSha256(copy),
+    };
+  }
+  return {
+    schema_version: 1,
+    workspace: "current",
+    pcr: structuredClone(pcr),
+    manifest: structuredClone(manifest),
+    structured: structuredClone(structured),
+    languages,
+    artifacts,
+  };
+}
+
+/** Complete referenced legacy module source; scaffold status remains explicit. */
+export function readPcrModuleDocumentBundle({ root, group, moduleId }) {
+  for (const value of [group, moduleId]) if (typeof value !== "string" || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/u.test(value)) throw new Error("Invalid PCR module identity.");
+  const relativePath = `library/modules/${group}/${moduleId}.md`;
+  const filePath = path.join(root, relativePath);
+  const read = () => pcrSource(root)?.readFile(relativePath) ?? readControlledRepositoryFileBytes({ root, filePath, relativePath, label: "PCR module" });
+  const bytes = read();
+  const text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  const envelope = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/u.exec(text);
+  if (!envelope) throw new Error(`Module requires frontmatter: ${relativePath}`);
+  const frontmatter = parseYaml(envelope[1]);
+  if (frontmatter.id !== `module.${group}.${moduleId}` || frontmatter.module_type !== group) throw new Error(`Module identity mismatch: ${relativePath}`);
+  if (!text.slice(envelope[0].length).trim()) throw new Error(`Module body is empty: ${relativePath}`);
+  if (!bytes.equals(read())) throw new Error(`Module changed during read: ${relativePath}`);
+  return { frontmatter, language: frontmatter.language ?? "en-US", artifact: { path: relativePath, bytes: Buffer.from(bytes), text, sha256: exactByteSha256(bytes) } };
+}
+
+export function buildGuidance({ root, pcrId, context = null }) {
+  return buildGuidanceForOperation({ root: root ?? context?.root, pcrId, operation: "guidance", context });
+}
+
+export function getVerifiedPcrProjection({ root, pcrId, context = null }) {
+  root = root ?? context?.root;
+  const snapshot = getCurrentPcrSnapshot({ root, pcrId, context });
+  const { pcr, structured, structuredPath } = snapshot;
+  assertPcrUsable({ pcr, operation: "guidance" });
+  if (!structured) {
+    throw new Error(
+      `PCR ${pcrId} passed readiness without a verified structured projection.`,
+    );
+  }
+  return {
+    pcr: structuredClone(pcr),
+    readiness: structuredClone(pcr.readiness),
+    source_structured: toPosix(path.relative(root, structuredPath)),
+    structured: structuredClone(structured),
+  };
+}
+
+function buildGuidanceForOperation({ root, pcrId, operation, context = null }) {
+  const snapshot = getCurrentPcrSnapshot({ root, pcrId, context });
+  const { pcr, structured, structuredPath } = snapshot;
+  assertPcrUsable({ pcr, operation });
+  if (!structured) {
+    throw new Error(
+      `PCR ${pcrId} passed readiness without a verified structured projection.`,
+    );
+  }
+  const guidance = {
+    schema_version: 1,
+    guidance_kind: "tiangong-pcr-agent-guidance",
+    pcr,
+    readiness: structuredClone(pcr.readiness),
+    source_structured: toPosix(path.relative(root, structuredPath)),
+    system_boundary: structured.system_boundary ?? {},
+    reference_flow: structured.reference_flow_definition ?? {},
+    boundary_abstraction: structured.boundary_abstraction ?? {},
+    measurement_rules: structured.measurement_rules ?? structured.unit_conventions ?? [],
+    process_map: structured.process_map ?? [],
+    process_inventory: structured.process_inventory ?? [],
+    production_guidance: {
+      collection_protocols: structured.dataset_production?.collection_protocols ?? [],
+      calculation_rules: structured.dataset_production?.calculation_rules ?? [],
+      data_quality_requirements: structured.dataset_production?.data_quality_requirements ?? [],
+    },
+    published_dataset_profile: structured.published_dataset_profile ?? {},
+    allocation_rules: structured.allocation_rules ?? [],
+    data_quality_rules: structured.data_quality_rules ?? [],
+    validation_rules: structured.validation_rules ?? [],
+    data_sources: structured.data_sources ?? [],
+    validation_notes: [
+      "Use this guidance as the source of Tiangong foreground data collection package requirements.",
+      "Preserve Tiangong UUIDs exactly and keep PCR-derived UUID references version-free.",
+      "Run tiangong-pcr validate-dataset after constructing a foreground data package and draft feedback if PCR guidance is missing or ambiguous.",
+    ],
+  };
+  assertCoreContract("guidance-output.schema.json", guidance, {
+    code: "PCR_INTERNAL_CONTRACT_INVALID",
+    entityKind: "Agent guidance output",
+    source: toPosix(path.relative(root, structuredPath)),
+  });
+  return guidance;
+}
+
+export function createFeedbackDraft({
+  root,
+  pcrId,
+  type,
+  affectedSection = "",
+  processId = "",
+  flowRole = "",
+  summary = "",
+  evidence = "",
+  proposedChange = "",
+  agent = "tiangong-pcr",
+}) {
+  if (!FEEDBACK_TYPES.includes(type)) {
+    throw new Error(`Unsupported feedback type: ${type}`);
+  }
+  const pcr = pcrId ? getPcrById({ root, pcrId }) : null;
+  const title = `PCR feedback: ${type}${pcrId ? ` for ${pcrId}` : ""}`;
+  const body = `## Summary
+
+${summary || "Describe the PCR issue or improvement."}
+
+## Feedback metadata
+
+| Field | Value |
+| --- | --- |
+| PCR id | ${pcrId || ""} |
+| PCR version | ${pcr?.version ?? ""} |
+| Feedback type | ${type} |
+| Affected section | ${affectedSection} |
+| Affected process_id | ${processId} |
+| Affected flow role | ${flowRole} |
+| Generated by | ${agent} |
+
+## Current PCR text or rule excerpt
+
+
+## Proposed change
+
+${proposedChange}
+
+## Evidence sources
+
+${evidence}
+
+## Impact on foreground data package construction
+
+
+## Maintainer intake checklist
+
+- [ ] Classify the feedback as PCR content, classification mapping, UUID identity, translation, source evidence, or CLI/validator behavior.
+- [ ] Verify cited evidence and Tiangong UUID references before changing PCR content.
+- [ ] Update canonical \`pcr.en-US.md\` first when methodology changes.
+- [ ] Align \`pcr.zh-CN.md\` when user-facing text changes.
+- [ ] Run \`npm run pcr:sync-structured -- --pcr <library/pcrs/...>\` when canonical Markdown changes.
+- [ ] Bump or publish the PCR manifest if lifecycle state changes.
+`;
+
+  const draft = { title, body };
+  assertCoreContract("feedback-draft-output.schema.json", draft, {
+    code: "PCR_INTERNAL_CONTRACT_INVALID",
+    entityKind: "PCR feedback issue draft output",
+  });
+  return draft;
+}
+
+export function validateModelAgainstGuidance({ root, pcrId, model }) {
+  const guidance = buildGuidanceForOperation({ root, pcrId, operation: "validation" });
+  const findings = [];
+  const accepted = validateCoreContract("model-validation-input.schema.json", model).valid;
+  const text = typeof model === "string" ? model : accepted ? JSON.stringify(model) : "";
+  const checksPerformed = [];
+  const checksSkipped = [];
+
+  if (!accepted) {
+    findings.push({
+      severity: "error",
+      code: "invalid_model_input",
+      message: "Model input must be text or a JSON object.",
+    });
+  }
+
+  const requiredQualifiers = asArray(guidance.reference_flow.required_qualifiers);
+  if (accepted && requiredQualifiers.length > 0) {
+    checksPerformed.push(performedCheck(
+      "required_qualifier_presence",
+      "reference_flow.required_qualifiers",
+      requiredQualifiers.length,
+    ));
+    for (const qualifier of requiredQualifiers) {
+      if (!text.toLowerCase().includes(String(qualifier).toLowerCase())) {
+        findings.push({
+          severity: "warning",
+          code: "missing_required_qualifier",
+          message: `Model text does not mention required qualifier: ${qualifier}`,
+        });
+      }
+    }
+  }
+
+  if (accepted) {
+    addSkippedCheck(
+      checksSkipped,
+      "system_boundary_rules",
+      "system_boundary.rules",
+      asArray(guidance.system_boundary?.rules).length,
+    );
+    addSkippedCheck(
+      checksSkipped,
+      "boundary_abstraction",
+      "boundary_abstraction",
+      topLevelRequirementCount(guidance.boundary_abstraction),
+    );
+    addSkippedCheck(
+      checksSkipped,
+      "reference_flow_definition",
+      "reference_flow",
+      topLevelRequirementCount(guidance.reference_flow, ["required_qualifiers"]),
+    );
+    addSkippedCheck(checksSkipped, "measurement_rules", "measurement_rules", asArray(guidance.measurement_rules).length);
+    addSkippedCheck(checksSkipped, "process_map", "process_map", asArray(guidance.process_map).length);
+    addSkippedCheck(checksSkipped, "process_inventory", "process_inventory", countInventoryRows(guidance.process_inventory));
+    addSkippedCheck(
+      checksSkipped,
+      "collection_protocols",
+      "production_guidance.collection_protocols",
+      asArray(guidance.production_guidance.collection_protocols).length,
+    );
+    addSkippedCheck(
+      checksSkipped,
+      "calculation_rules",
+      "production_guidance.calculation_rules",
+      asArray(guidance.production_guidance.calculation_rules).length,
+    );
+    addSkippedCheck(
+      checksSkipped,
+      "data_quality_requirements",
+      "production_guidance.data_quality_requirements",
+      asArray(guidance.production_guidance.data_quality_requirements).length,
+    );
+    addSkippedCheck(checksSkipped, "data_quality_rules", "data_quality_rules", asArray(guidance.data_quality_rules).length);
+    addSkippedCheck(checksSkipped, "allocation_rules", "allocation_rules", asArray(guidance.allocation_rules).length);
+    addSkippedCheck(checksSkipped, "validation_rules", "validation_rules", asArray(guidance.validation_rules).length);
+    addSkippedCheck(
+      checksSkipped,
+      "published_dataset_profile",
+      "published_dataset_profile",
+      topLevelRequirementCount(guidance.published_dataset_profile),
+    );
+  }
+
+  return buildValidationReport({
+    validationKind: "tiangong-pcr-model-validation",
+    guidance,
+    input: {
+      input_kind: "process_or_lifecyclemodel",
+      representation: typeof model === "string" ? "text" : Array.isArray(model) ? "array" : typeof model,
+      accepted,
+    },
+    findings,
+    checksPerformed,
+    checksSkipped,
+  });
+}
+
+export function validateDatasetAgainstGuidance({ root, pcrId, dataset }) {
+  const guidance = buildGuidanceForOperation({ root, pcrId, operation: "validation" });
+  const findings = [];
+  const accepted = validateCoreContract("dataset-validation-input.schema.json", dataset).valid;
+  const checksPerformed = [];
+  const checksSkipped = [];
+  const records = accepted ? collectionRecordArrays(dataset) : [];
+  const requiredProtocolIds = asArray(guidance.production_guidance.collection_protocols)
+    .map((protocol) => protocol.protocol_id)
+    .filter(Boolean);
+  const presentProtocolIds = accepted ? collectCollectionRecordProtocolIds(dataset) : new Set();
+
+  if (!accepted) {
+    findings.push({
+      severity: "error",
+      code: "invalid_dataset_input",
+      message: "Foreground data package input must be a JSON object.",
+    });
+  }
+
+  if (accepted && requiredProtocolIds.length > 0) {
+    checksPerformed.push(performedCheck(
+      "collection_protocol_presence",
+      "production_guidance.collection_protocols",
+      requiredProtocolIds.length,
+    ));
+    for (const protocolId of requiredProtocolIds) {
+      if (!presentProtocolIds.has(String(protocolId))) {
+        findings.push({
+          severity: "error",
+          code: "missing_collection_protocol_record",
+          message: `Foreground data package is missing collection record for protocol_id ${protocolId}`,
+        });
+      }
+    }
+  }
+
+  if (accepted) {
+    addSkippedCheck(
+      checksSkipped,
+      "system_boundary_rules",
+      "system_boundary.rules",
+      asArray(guidance.system_boundary?.rules).length,
+    );
+    addSkippedCheck(
+      checksSkipped,
+      "boundary_abstraction",
+      "boundary_abstraction",
+      topLevelRequirementCount(guidance.boundary_abstraction),
+    );
+    addSkippedCheck(
+      checksSkipped,
+      "reference_flow_rules",
+      "reference_flow",
+      topLevelRequirementCount(guidance.reference_flow, ["required_qualifiers"]) +
+        asArray(guidance.reference_flow?.required_qualifiers).length,
+    );
+    addSkippedCheck(checksSkipped, "measurement_rules", "measurement_rules", asArray(guidance.measurement_rules).length);
+    addSkippedCheck(checksSkipped, "process_map", "process_map", asArray(guidance.process_map).length);
+    addSkippedCheck(checksSkipped, "process_inventory", "process_inventory", countInventoryRows(guidance.process_inventory));
+    addSkippedCheck(
+      checksSkipped,
+      "calculation_rules",
+      "production_guidance.calculation_rules",
+      asArray(guidance.production_guidance.calculation_rules).length,
+    );
+    addSkippedCheck(
+      checksSkipped,
+      "data_quality_requirements",
+      "production_guidance.data_quality_requirements",
+      asArray(guidance.production_guidance.data_quality_requirements).length,
+    );
+    addSkippedCheck(checksSkipped, "data_quality_rules", "data_quality_rules", asArray(guidance.data_quality_rules).length);
+    addSkippedCheck(checksSkipped, "allocation_rules", "allocation_rules", asArray(guidance.allocation_rules).length);
+    addSkippedCheck(checksSkipped, "validation_rules", "validation_rules", asArray(guidance.validation_rules).length);
+    addSkippedCheck(
+      checksSkipped,
+      "published_dataset_profile",
+      "published_dataset_profile",
+      topLevelRequirementCount(guidance.published_dataset_profile),
+    );
+  }
+
+  return buildValidationReport({
+    validationKind: "tiangong-pcr-dataset-validation",
+    guidance,
+    input: {
+      input_kind: "foreground_data_package",
+      representation: Array.isArray(dataset) ? "array" : dataset === null ? "null" : typeof dataset,
+      accepted,
+      collection_record_count: records.length,
+      distinct_protocol_id_count: presentProtocolIds.size,
+    },
+    findings,
+    checksPerformed,
+    checksSkipped,
+  });
+}
+
+function collectCollectionRecordProtocolIds(dataset) {
+  if (typeof dataset === "string") {
+    return new Set();
+  }
+  const ids = new Set();
+  for (const record of collectionRecordArrays(dataset)) {
+    const protocolId = record?.protocol_id ?? record?.collection_protocol_id;
+    if (protocolId) {
+      ids.add(String(protocolId));
+    }
+  }
+  return ids;
+}
+
+function collectionRecordArrays(value) {
+  if (!value || typeof value !== "object") {
+    return [];
+  }
+  const records = [];
+  for (const key of ["collection_records", "foreground_records", "measurement_records"]) {
+    if (Array.isArray(value[key])) {
+      records.push(...value[key]);
+    }
+  }
+  if (value.data && typeof value.data === "object") {
+    records.push(...collectionRecordArrays(value.data));
+  }
+  return records;
+}
+
+function currentPcrEntry(root, entry) {
+  return currentPcrSnapshot(root, entry).pcr;
+}
+
+function getCurrentPcrSnapshot({ root, pcrId, refresh = false, context = null }) {
+  throwIfLegacyPcrId({ root, pcrId, context });
+  return getCurrentPcrSnapshotUnchecked({ root, pcrId, refresh, context });
+}
+
+export function readPcrDistributionCatalog({ root }) {
+  return readPcrCatalog(path.resolve(root));
+}
+
+// Builder-only: preserves legacy catalog records without following alias redirects.
+export function readPcrDistributionSnapshot(options) {
+  return getCurrentPcrSnapshotUnchecked(options);
+}
+
+function getCurrentPcrSnapshotUnchecked({ root, pcrId, refresh = false, context = null }) {
+  if (pcrSource(root)) {
+    const entry = pcrSource(root).entry(pcrId);
+    if (!entry) throw new Error(`PCR not found: ${pcrId}`);
+    return currentPcrSnapshot(root, entry);
+  }
+  const normalizedRoot = path.resolve(root);
+  if (context) {
+    assertPcrReadContextFresh({ context, root: normalizedRoot });
+  }
+  const catalog = context
+    ? getPcrReadContextCatalog({
+      context,
+      root: normalizedRoot,
+      readCatalog: readPcrCatalog,
+    })
+    : getPcrCatalog({ root: normalizedRoot, refresh });
+  const entry = context
+    ? catalog.get(pcrId)
+    : catalog.find((candidate) => candidate.id === pcrId);
+  if (!entry) {
+    throw new Error(`PCR not found: ${pcrId}`);
+  }
+  return currentPcrSnapshot(normalizedRoot, entry, context);
+}
+
+function currentPcrSnapshot(root, entry, context = null) {
+  const snapshotFiles = pcrSource(root)?.snapshotFiles(entry) ?? readConsistentSnapshotFiles({ root, entry, context });
+  const pcr = pcrFromManifest({
+    root,
+    pcrDir: path.dirname(entry.manifestPath),
+    manifest: snapshotFiles.manifest,
+  });
+  let projection;
+  try {
+    projection = inspectPcrProjection({
+      root,
+      pcr,
+      manifest: snapshotFiles.manifest,
+      artifacts: snapshotFiles.artifacts,
+    });
+  } catch (error) {
+    projection = failedProjectionInspection({ root, pcr, error });
+  }
+  pcr.readiness = assessPcrReadiness({
+    pcr,
+    projectionFingerprint: projection.fingerprint,
+    structuredAvailable: projection.structuredAvailable,
+    projectionCompletenessIssues: projection.completenessIssues,
+  });
+  return {
+    pcr,
+    manifest: snapshotFiles.manifest,
+    manifestBytes: snapshotFiles.manifestBytes,
+    artifacts: snapshotFiles.artifacts,
+    ...projection,
+  };
+}
+
+function readConsistentSnapshotFiles({ root, entry, context = null }) {
+  let lastFailure = null;
+  for (let attempt = 1; attempt <= CURRENT_SNAPSHOT_MAX_ATTEMPTS; attempt += 1) {
+    try {
+      const locationA = assertCurrentSnapshotLocation({ root, entry });
+      const manifestABytes = readCanonicalFileBytes(locationA.manifestPath);
+      const manifest = parseYaml(manifestABytes.toString("utf8"));
+      if (manifest.id !== entry.id) {
+        throw snapshotAttemptError(
+          "manifest_identity_changed",
+          `Expected PCR id ${entry.id}, found ${String(manifest.id)}.`,
+          { expected_pcr_id: entry.id, actual_pcr_id: manifest.id ?? null },
+        );
+      }
+
+      const managedMarkersA = currentManagedStateMarkers(locationA.pcrDir);
+      assertManagedSnapshotHashesDeclared({ manifest, managedMarkers: managedMarkersA });
+      const artifacts = Object.fromEntries(
+        pcrArtifactFiles(manifest, { strict: false }).map((filename) => [
+          filename,
+          readObservedPcrArtifact({ root, context, pcrDir: locationA.pcrDir, filename }),
+        ]),
+      );
+      const releaseFailures = releaseArtifactFailures({ manifest, artifacts });
+      const locationB = assertCurrentSnapshotLocation({ root, entry });
+      const managedMarkersB = currentManagedStateMarkers(locationB.pcrDir);
+      if (!sameStrings(managedMarkersA, managedMarkersB)) {
+        throw snapshotAttemptError(
+          "managed_state_changed_during_read",
+          "PCR managed release state changed while its current snapshot was being read.",
+          {
+            managed_markers_before: managedMarkersA,
+            managed_markers_after: managedMarkersB,
+          },
+        );
+      }
+      const manifestBBytes = readCanonicalFileBytes(locationB.manifestPath);
+      if (!manifestABytes.equals(manifestBBytes)) {
+        throw snapshotAttemptError(
+          "manifest_changed_during_read",
+          "manifest.yaml changed while its current artifacts were being read.",
+        );
+      }
+      if (releaseFailures.length > 0) {
+        throw snapshotAttemptError(
+          "release_artifact_hash_mismatch",
+          "Current PCR artifacts do not match manifest.release_artifacts.",
+          { manifest_status: manifest.status ?? null, artifacts: releaseFailures },
+        );
+      }
+      return { manifest, manifestBytes: manifestABytes, artifacts };
+    } catch (error) {
+      lastFailure = snapshotFailureDetails(error);
+    }
+  }
+  throw new PcrCurrentSnapshotInconsistentError({
+    pcrId: entry.id,
+    pcrPath: entry.path,
+    attempts: CURRENT_SNAPSHOT_MAX_ATTEMPTS,
+    lastFailure,
+  });
+}
+
+function readObservedPcrArtifact({ root, context, pcrDir, filename }) {
+  const artifactPath = path.join(pcrDir, filename);
+  if (context) {
+    observePcrReadContextArtifactRead({
+      context,
+      root,
+      relativePath: toPosix(path.relative(root, artifactPath)),
+    });
+  }
+  return readOptionalCanonicalFile(artifactPath);
+}
+
+function releaseArtifactFailures({ manifest, artifacts }) {
+  if (!Object.hasOwn(manifest, "release_artifacts")) {
+    return [];
+  }
+  const expectedHashes = expectedPcrArtifactHashes(manifest);
+  const failures = [];
+  for (const [filename, expected] of Object.entries(expectedHashes)) {
+    const hashField = manifest.schema_version === 2 && filename !== "structured.yaml"
+      ? `markdown_sha256.${filename.slice(4, -3)}`
+      : Object.entries(RELEASE_ARTIFACTS).find(([, file]) => file === filename)?.[0];
+    const artifact = artifacts[filename];
+    if (!artifact?.bytes) {
+      failures.push({
+        artifact: filename,
+        hash_field: hashField,
+        expected: typeof expected === "string" ? expected : null,
+        actual: null,
+        reason: `artifact_unreadable:${errorCode(artifact?.error)}`,
+      });
+      continue;
+    }
+    const actual = exactByteSha256(artifact.bytes);
+    if (typeof expected !== "string" || expected !== actual) {
+      failures.push({
+        artifact: filename,
+        hash_field: hashField,
+        expected: typeof expected === "string" ? expected : null,
+        actual,
+        reason: "sha256_mismatch",
+      });
+    }
+  }
+  return failures;
+}
+
+function assertManagedSnapshotHashesDeclared({ manifest, managedMarkers }) {
+  if (managedMarkers.length === 0 || Object.hasOwn(manifest, "release_artifacts")) {
+    return;
+  }
+  throw snapshotAttemptError(
+    "managed_release_artifacts_missing",
+    "Managed PCR current state requires manifest.release_artifacts and cannot use legacy snapshot semantics.",
+    {
+      manifest_status: manifest.status ?? null,
+      managed_markers: managedMarkers,
+      required_field: "manifest.release_artifacts",
+      required_hash_fields: Object.keys(RELEASE_ARTIFACTS),
+    },
+  );
+}
+
+function currentManagedStateMarkers(pcrDir) {
+  return ["release-history.yaml", "releases"]
+    .filter((name) => pathEntryExists(path.join(pcrDir, name)))
+    .sort((left, right) => left.localeCompare(right));
+}
+
+function pathEntryExists(targetPath) {
+  try {
+    lstatSync(targetPath);
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}
+
+function sameStrings(left, right) {
+  return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+
+function assertCurrentSnapshotLocation({ root, entry }) {
+  const normalizedRoot = path.resolve(root);
+  const pathSegments = String(entry.path).split("/");
+  if (
+    pathSegments.length !== 5 ||
+    pathSegments[0] !== "library" ||
+    pathSegments[1] !== "pcrs" ||
+    pathSegments.slice(2).some((segment) => !segment || segment === "." || segment === "..")
+  ) {
+    throw snapshotAttemptError(
+      "canonical_pcr_path_invalid",
+      "Cached PCR path is not a canonical domain/subdomain/leaf path.",
+      {
+        pcr_path: entry.path,
+        reason: "non_canonical_relative_path",
+      },
+    );
+  }
+
+  const directoryPaths = [normalizedRoot];
+  for (const segment of pathSegments) {
+    directoryPaths.push(path.join(directoryPaths.at(-1), segment));
+  }
+
+  let rootRealPath = null;
+  for (const [index, directoryPath] of directoryPaths.entries()) {
+    const relativePath = toPosix(path.relative(normalizedRoot, directoryPath)) || ".";
+    let stat;
+    try {
+      stat = lstatSync(directoryPath);
+    } catch (error) {
+      throw snapshotAttemptError(
+        "canonical_pcr_path_invalid",
+        `Canonical PCR directory is unavailable: ${relativePath}.`,
+        {
+          path_component: relativePath,
+          reason: `directory_unreadable:${errorCode(error)}`,
+          expected_type: "regular_directory",
+        },
+      );
+    }
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+      throw snapshotAttemptError(
+        "canonical_pcr_path_invalid",
+        `Canonical PCR path component is not a regular directory: ${relativePath}.`,
+        {
+          path_component: relativePath,
+          reason: stat.isSymbolicLink() ? "symbolic_link" : "not_a_directory",
+          expected_type: "regular_directory",
+        },
+      );
+    }
+
+    let realPath;
+    try {
+      realPath = realpathSync(directoryPath);
+    } catch (error) {
+      throw snapshotAttemptError(
+        "canonical_pcr_path_invalid",
+        `Canonical PCR directory cannot be resolved: ${relativePath}.`,
+        {
+          path_component: relativePath,
+          reason: `realpath_unavailable:${errorCode(error)}`,
+          expected_type: "regular_directory",
+        },
+      );
+    }
+    if (index === 0) {
+      rootRealPath = realPath;
+    } else if (!pathIsInside(rootRealPath, realPath)) {
+      throw snapshotAttemptError(
+        "canonical_pcr_path_invalid",
+        `Canonical PCR directory resolves outside the repository root: ${relativePath}.`,
+        {
+          path_component: relativePath,
+          reason: "realpath_outside_root",
+          expected_type: "regular_directory_within_root",
+        },
+      );
+    }
+  }
+
+  const pcrDir = directoryPaths.at(-1);
+  const manifestPath = path.join(pcrDir, "manifest.yaml");
+  if (path.resolve(entry.manifestPath) !== manifestPath) {
+    throw snapshotAttemptError(
+      "canonical_pcr_path_invalid",
+      "Cached manifest path is not the direct manifest.yaml child of its canonical PCR leaf.",
+      {
+        pcr_path: entry.path,
+        reason: "manifest_not_direct_leaf_child",
+      },
+    );
+  }
+  return { manifestPath, pcrDir };
+}
+
+function pathIsInside(rootPath, candidatePath) {
+  const relativePath = path.relative(rootPath, candidatePath);
+  return relativePath === "" || (!path.isAbsolute(relativePath) && relativePath !== ".." && !relativePath.startsWith(`..${path.sep}`));
+}
+
+function exactByteSha256(bytes) {
+  return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+
+function readOptionalCanonicalFile(filePath) {
+  try {
+    return { bytes: readCanonicalFileBytes(filePath), error: null };
+  } catch (error) {
+    return { bytes: null, error };
+  }
+}
+
+function readControlledRepositoryFileBytes({ root, filePath, relativePath, label }) {
+  const normalizedRoot = path.resolve(root);
+  const normalizedFilePath = path.resolve(filePath);
+  const containedPath = path.relative(normalizedRoot, normalizedFilePath);
+  if (
+    containedPath.length === 0
+    || path.isAbsolute(containedPath)
+    || containedPath === ".."
+    || containedPath.startsWith(`..${path.sep}`)
+  ) {
+    throw new Error(`${label} path escapes the repository root: ${relativePath}`);
+  }
+
+  const expectedRelativePath = toPosix(containedPath);
+  if (expectedRelativePath !== relativePath) {
+    throw new Error(`${label} path is not canonical: ${relativePath}`);
+  }
+
+  const before = assertControlledRepositoryPath({
+    root: normalizedRoot,
+    containedPath,
+    relativePath,
+    label,
+  });
+  let descriptor;
+  try {
+    descriptor = openSync(
+      normalizedFilePath,
+      fsConstants.O_RDONLY
+        | (fsConstants.O_NOFOLLOW ?? 0)
+        | (fsConstants.O_NONBLOCK ?? 0),
+    );
+    const opened = fstatSync(descriptor);
+    if (!opened.isFile()) {
+      throw new Error(`${label} is not a regular file: ${relativePath}`);
+    }
+    const after = assertControlledRepositoryPath({
+      root: normalizedRoot,
+      containedPath,
+      relativePath,
+      label,
+    });
+    if (
+      opened.dev !== before.dev
+      || opened.ino !== before.ino
+      || opened.dev !== after.dev
+      || opened.ino !== after.ino
+    ) {
+      throw new Error(`${label} path changed while it was being opened: ${relativePath}`);
+    }
+    return readFileSync(descriptor);
+  } finally {
+    if (descriptor !== undefined) {
+      closeSync(descriptor);
+    }
+  }
+}
+
+function assertControlledRepositoryPath({ root, containedPath, relativePath, label }) {
+  let currentPath = root;
+  let finalStats;
+  const segments = containedPath.split(path.sep);
+  for (const [index, segment] of segments.entries()) {
+    currentPath = path.join(currentPath, segment);
+    const stats = lstatSync(currentPath);
+    if (stats.isSymbolicLink()) {
+      throw new Error(`${label} path contains a symbolic link: ${relativePath}`);
+    }
+    const isLast = index === segments.length - 1;
+    if (isLast ? !stats.isFile() : !stats.isDirectory()) {
+      throw new Error(
+        isLast
+          ? `${label} is not a regular file: ${relativePath}`
+          : `${label} parent is not a directory: ${relativePath}`,
+      );
+    }
+    if (isLast) {
+      finalStats = stats;
+    }
+  }
+
+  const realRoot = realpathSync(root);
+  const realFile = realpathSync(path.join(root, containedPath));
+  if (!pathIsInside(realRoot, realFile) || realRoot === realFile) {
+    throw new Error(`${label} real path escapes the repository root: ${relativePath}`);
+  }
+  return finalStats;
+}
+
+function readCanonicalFileBytes(filePath) {
+  const stat = lstatSync(filePath);
+  if (stat.isSymbolicLink() || !stat.isFile()) {
+    const error = new Error(`Canonical PCR artifact is not a regular file: ${filePath}`);
+    error.code = stat.isSymbolicLink()
+      ? "PCR_CANONICAL_SYMLINK_REJECTED"
+      : "PCR_CANONICAL_FILE_NOT_REGULAR";
+    throw error;
+  }
+  const descriptor = openSync(
+    filePath,
+    fsConstants.O_RDONLY | (fsConstants.O_NOFOLLOW ?? 0),
+  );
+  try {
+    if (!fstatSync(descriptor).isFile()) {
+      const error = new Error(`Canonical PCR artifact is not a regular file: ${filePath}`);
+      error.code = "PCR_CANONICAL_FILE_NOT_REGULAR";
+      throw error;
+    }
+    return readFileSync(descriptor);
+  } finally {
+    closeSync(descriptor);
+  }
+}
+
+function snapshotAttemptError(code, message, details = {}) {
+  const error = new Error(message);
+  error.snapshotCode = code;
+  error.snapshotDetails = details;
+  return error;
+}
+
+function snapshotFailureDetails(error) {
+  return {
+    code: error?.snapshotCode ?? errorCode(error),
+    message: error instanceof Error ? error.message : String(error),
+    ...(isRecord(error?.snapshotDetails) ? error.snapshotDetails : {}),
+  };
+}
+
+function pcrFromManifest({ root, pcrDir, manifest }) {
+  const pcr = {
+    id: manifest.id,
+    path: toPosix(path.relative(root, pcrDir)),
+    title: manifest.title ?? {},
+    status: manifest.status ?? "unknown",
+    version: manifest.version ?? null,
+    content_maturity: manifest.content_maturity ?? null,
+    languages: manifest.languages ?? {},
+    translation_status: manifest.translation_status ?? {},
+    classification_refs: manifest.classification_refs ?? [],
+  };
+  pcr.record_kind = recordKindForPcr(pcr);
+  return pcr;
+}
+
+function inspectPcrProjection({ root, pcr, manifest, artifacts }) {
+  const pcrDir = path.join(root, pcr.path);
+  const structuredPath = path.join(pcrDir, "structured.yaml");
+  const structuredArtifact = artifacts["structured.yaml"];
+  const markdownArtifact = artifacts["pcr.en-US.md"];
+  if (!isMaterialPcr(pcr)) {
+    return {
+      fingerprint: {
+        ...projectionNotRequiredState(),
+        schema_valid: null,
+      },
+      structured: null,
+      structuredPath,
+      structuredAvailable: Boolean(structuredArtifact?.bytes),
+      completenessIssues: [],
+    };
+  }
+
+  if (!structuredArtifact?.bytes && structuredArtifact?.error?.code === "ENOENT") {
+    return unavailableProjectionInspection({
+      structuredPath,
+      structuredAvailable: false,
+      fingerprint: missingProjectionState(
+        "missing",
+        "structured_projection_missing",
+        "structured.yaml is required for material PCR guidance and validation.",
+      ),
+    });
+  }
+
+  if (!markdownArtifact?.bytes && markdownArtifact?.error?.code === "ENOENT") {
+    return unavailableProjectionInspection({
+      structuredPath,
+      structuredAvailable: Boolean(structuredArtifact?.bytes),
+      fingerprint: missingProjectionState(
+        "source_missing",
+        "projection_source_missing",
+        "Canonical pcr.en-US.md is required to verify the structured projection.",
+      ),
+    });
+  }
+
+  if (!markdownArtifact?.bytes) {
+    return unavailableProjectionInspection({
+      structuredPath,
+      structuredAvailable: Boolean(structuredArtifact?.bytes),
+      fingerprint: invalidProjectionState(
+        "projection_source_unreadable",
+        `Canonical pcr.en-US.md could not be read (${errorCode(markdownArtifact?.error)}).`,
+        null,
+      ),
+    });
+  }
+
+  if (!structuredArtifact?.bytes) {
+    return unavailableProjectionInspection({
+      structuredPath,
+      structuredAvailable: false,
+      fingerprint: invalidProjectionState(
+        "structured_projection_unreadable",
+        `structured.yaml could not be read (${errorCode(structuredArtifact?.error)}).`,
+        false,
+      ),
+    });
+  }
+
+  const sourceMarkdown = markdownArtifact.bytes.toString("utf8");
+  const structuredText = structuredArtifact.bytes.toString("utf8");
+
+  let structured;
+  try {
+    structured = parseYaml(structuredText);
+  } catch (error) {
+    return unavailableProjectionInspection({
+      structuredPath,
+      structuredAvailable: true,
+      fingerprint: invalidProjectionState(
+        "structured_projection_parse_error",
+        `structured.yaml could not be parsed (${errorCode(error)}).`,
+        false,
+      ),
+    });
+  }
+
+  const schemaResult = validateCoreContract(
+    "structured-projection.schema.json",
+    structured,
+    { entityKind: "material structured projection" },
+  );
+  const integrity = inspectProjectionIntegrity({
+    sourceMarkdown,
+    structuredText,
+    metadata: structured?.projection_metadata,
+  });
+  const schemaIssues = schemaResult.valid
+    ? []
+    : [
+        {
+          code: "structured_schema_invalid",
+          message: `structured.yaml violates the material projection schema (${schemaResult.errors.length} issue(s)).`,
+        },
+        ...schemaResult.errors.map((error) => ({
+          code: `structured_schema.${error.keyword}`,
+          message: `${error.instance_path}: ${error.message}`,
+        })),
+      ];
+  const issues = deduplicateMessages([...schemaIssues, ...integrity.issues]);
+  const fingerprint = {
+    ...integrity,
+    status: schemaResult.valid ? integrity.status : "invalid",
+    schema_valid: schemaResult.valid,
+    issues,
+  };
+
+  return {
+    fingerprint,
+    structured: schemaResult.valid && integrity.status === "current" ? structured : null,
+    structuredPath,
+    structuredAvailable: true,
+    completenessIssues: schemaResult.valid
+      ? materialProjectionCompletenessIssues(structured, {
+          expectedPcrId: pcr.id,
+          allowUnresolvedProductFlowUuid:
+            hasDeclaredUnresolvedReferenceProductFlow(structured, manifest),
+        })
+      : [],
+  };
+}
+
+function unavailableProjectionInspection({ fingerprint, structuredPath, structuredAvailable }) {
+  return {
+    fingerprint,
+    structured: null,
+    structuredPath,
+    structuredAvailable,
+    completenessIssues: [],
+  };
+}
+
+function failedProjectionInspection({ root, pcr, error }) {
+  return unavailableProjectionInspection({
+    structuredPath: path.join(root, pcr.path, "structured.yaml"),
+    structuredAvailable: false,
+    fingerprint: invalidProjectionState(
+      "projection_inspection_failed",
+      `Projection integrity inspection failed (${errorCode(error)}).`,
+      false,
+    ),
+  });
+}
+
+function invalidProjectionState(code, message, schemaValid) {
+  return {
+    required: true,
+    status: "invalid",
+    schema_valid: schemaValid,
+    contract_version: null,
+    source_sha256: null,
+    generated_content_sha256: null,
+    source_hash_valid: null,
+    content_hash_valid: null,
+    issues: [{ code, message }],
+  };
+}
+
+function errorCode(error) {
+  return typeof error?.code === "string" && error.code
+    ? error.code
+    : "unknown_error";
+}
+
+function missingProjectionState(status, code, message) {
+  return {
+    required: true,
+    status,
+    schema_valid: null,
+    contract_version: null,
+    source_sha256: null,
+    generated_content_sha256: null,
+    source_hash_valid: null,
+    content_hash_valid: null,
+    issues: [{ code, message }],
+  };
+}
+
+function isMaterialPcr(pcr) {
+  return recordKindForPcr(pcr) === "methodology";
+}
+
+function normalizeCatalogScope(scope) {
+  const normalized = String(scope);
+  if (!PCR_CATALOG_SCOPE_SET.has(normalized)) {
+    throw new PcrCatalogScopeError(scope);
+  }
+  return normalized;
+}
+
+function recordMatchesScope(pcr, scope) {
+  if (scope === "all") {
+    return true;
+  }
+  return scope === "material"
+    ? pcr.record_kind === "methodology"
+    : pcr.record_kind === "legacy_scaffold_reference";
+}
+
+function currentCatalogEntryMatchesScope(root, entry, scope) {
+  const manifest = readConsistentCurrentManifest({ root, entry });
+  const recordKind = recordKindForPcr({
+    status: manifest.status ?? "unknown",
+    content_maturity: manifest.content_maturity ?? null,
+  });
+  return scope === "material"
+    ? recordKind === "methodology"
+    : recordKind === "legacy_scaffold_reference";
+}
+
+function readConsistentCurrentManifest({ root, entry }) {
+  let lastFailure = null;
+  for (let attempt = 1; attempt <= CURRENT_SNAPSHOT_MAX_ATTEMPTS; attempt += 1) {
+    try {
+      const locationA = assertCurrentSnapshotLocation({ root, entry });
+      const manifestABytes = readCanonicalFileBytes(locationA.manifestPath);
+      const manifest = parseYaml(manifestABytes.toString("utf8"));
+      if (manifest.id !== entry.id) {
+        throw snapshotAttemptError(
+          "manifest_identity_changed",
+          `Expected PCR id ${entry.id}, found ${String(manifest.id)}.`,
+          { expected_pcr_id: entry.id, actual_pcr_id: manifest.id ?? null },
+        );
+      }
+
+      const locationB = assertCurrentSnapshotLocation({ root, entry });
+      const manifestBBytes = readCanonicalFileBytes(locationB.manifestPath);
+      if (!manifestABytes.equals(manifestBBytes)) {
+        throw snapshotAttemptError(
+          "manifest_changed_during_read",
+          "manifest.yaml changed while its catalog scope was being determined.",
+        );
+      }
+      return manifest;
+    } catch (error) {
+      lastFailure = snapshotFailureDetails(error);
+    }
+  }
+  throw new PcrCurrentSnapshotInconsistentError({
+    pcrId: entry.id,
+    pcrPath: entry.path,
+    attempts: CURRENT_SNAPSHOT_MAX_ATTEMPTS,
+    lastFailure,
+  });
+}
+
+function recordKindForPcr(pcr) {
+  if (pcr.status === "scaffold" && pcr.content_maturity === "empty_scaffold") {
+    return "legacy_scaffold_reference";
+  }
+  if (
+    METHODOLOGY_LIFECYCLE_STATUSES.has(pcr.status) &&
+    METHODOLOGY_MATURITIES.has(pcr.content_maturity)
+  ) {
+    return "methodology";
+  }
+  return "invalid_lifecycle_state";
+}
+
+function assessPcrReadiness({
+  pcr,
+  projectionFingerprint,
+  structuredAvailable,
+  projectionCompletenessIssues = [],
+}) {
+  const blockers = [];
+  const warnings = [];
+  const methodologyStatus = pcr.content_maturity ?? "unknown";
+  const lifecycleStatus = pcr.status ?? "unknown";
+  const chineseTranslationStatus = pcr.translation_status?.["zh-CN"] ?? "unknown";
+  if (pcr.record_kind === "invalid_lifecycle_state") {
+    blockers.push({
+      code: "invalid_lifecycle_identity",
+      message:
+        `status ${lifecycleStatus} and content_maturity ${methodologyStatus} do not identify either ` +
+        "a legacy scaffold or a material methodology record.",
+    });
+  }
+  if (!GUIDANCE_MATURITIES.has(methodologyStatus)) {
+    blockers.push({
+      code: "methodology_not_authored",
+      message: `content_maturity ${methodologyStatus} is not usable methodology.`,
+    });
+  }
+  if (lifecycleStatus === "scaffold") {
+    blockers.push({
+      code: "scaffold_lifecycle",
+      message: "PCR lifecycle status is scaffold.",
+    });
+  } else if (!GUIDANCE_LIFECYCLE_STATUSES.has(lifecycleStatus)) {
+    blockers.push({
+      code: "lifecycle_not_usable",
+      message: `PCR lifecycle status ${lifecycleStatus} is not available for guidance.`,
+    });
+  }
+  if (lifecycleStatus === "deprecated" || methodologyStatus === "deprecated_methodology") {
+    blockers.push({
+      code: "deprecated_methodology",
+      message: "Deprecated PCR methodology must not guide new work.",
+    });
+  }
+  if (projectionFingerprint.required && (
+    projectionFingerprint.schema_valid !== true || projectionFingerprint.status !== "current"
+  )) {
+    blockers.push(...projectionFingerprint.issues);
+  }
+  if (
+    projectionFingerprint.required &&
+    projectionFingerprint.schema_valid === true &&
+    projectionFingerprint.status === "current"
+  ) {
+    blockers.push(...projectionCompletenessIssues);
+  }
+  if (
+    GUIDANCE_MATURITIES.has(methodologyStatus) &&
+    !USABLE_LIFECYCLE_STATES.get(lifecycleStatus)?.has(methodologyStatus)
+  ) {
+    blockers.push({
+      code: "incompatible_lifecycle_state",
+      message: `status ${lifecycleStatus} is incompatible with content_maturity ${methodologyStatus}.`,
+    });
+  }
+  if (
+    lifecycleStatus === "active" &&
+    !["aligned", "reviewed"].includes(chineseTranslationStatus)
+  ) {
+    blockers.push({
+      code: "translation_not_aligned",
+      message: `active PCR requires aligned or reviewed zh-CN translation; found ${chineseTranslationStatus}.`,
+    });
+  }
+  if (lifecycleStatus === "published" && chineseTranslationStatus !== "reviewed") {
+    blockers.push({
+      code: "translation_not_reviewed",
+      message: `published PCR requires reviewed zh-CN translation; found ${chineseTranslationStatus}.`,
+    });
+  }
+
+  if (methodologyStatus === "authored_methodology") {
+    warnings.push({
+      code: "methodology_not_reviewed",
+      message: "Authored methodology is candidate guidance and still requires methodology review.",
+    });
+  }
+  if (
+    lifecycleStatus === "candidate" &&
+    !["aligned", "reviewed"].includes(chineseTranslationStatus)
+  ) {
+    warnings.push({
+      code: "translation_not_aligned",
+      message: `Candidate zh-CN translation is ${chineseTranslationStatus}; use canonical en-US guidance for methodology decisions.`,
+    });
+  }
+
+  const uniqueBlockers = deduplicateMessages(blockers);
+  const uniqueWarnings = deduplicateMessages(warnings);
+  const usable = uniqueBlockers.length === 0;
+  const readiness = {
+    status: usable
+      ? (REVIEWED_MATURITIES.has(methodologyStatus) && lifecycleStatus !== "candidate" ? "ready" : "review_required")
+      : "unavailable",
+    lifecycle_status: lifecycleStatus,
+    methodology_status: methodologyStatus,
+    structured_projection_available: structuredAvailable,
+    projection_fingerprint: structuredClone(projectionFingerprint),
+    usable_for_guidance: usable,
+    usable_for_validation: usable,
+    blockers: uniqueBlockers,
+    warnings: uniqueWarnings,
+  };
+  assertCoreContract("readiness.schema.json", readiness, {
+    code: "PCR_INTERNAL_CONTRACT_INVALID",
+    entityKind: "PCR readiness",
+  });
+  return readiness;
+}
+
+function assertPcrUsable({ pcr, operation }) {
+  const usabilityKey = operation === "validation" ? "usable_for_validation" : "usable_for_guidance";
+  if (!pcr.readiness?.[usabilityKey]) {
+    throw new PcrUsabilityError({ pcrId: pcr.id, operation, readiness: pcr.readiness });
+  }
+}
+
+function buildValidationReport({
+  validationKind,
+  guidance,
+  input,
+  findings,
+  checksPerformed,
+  checksSkipped,
+}) {
+  const checkedRequirementCount = checksPerformed.reduce((total, check) => total + check.requirement_count, 0);
+  const skippedRequirementCount = checksSkipped.reduce((total, check) => total + check.requirement_count, 0);
+  const completeness = checksPerformed.length === 0
+    ? "none"
+    : checksSkipped.length > 0
+      ? "partial"
+      : "complete";
+  const findingSummary = countFindingsBySeverity(findings);
+  const validationStatus = findingSummary.error > 0
+    ? "failed"
+    : checksPerformed.length === 0
+      ? "inconclusive"
+      : "passed";
+
+  const report = {
+    schema_version: 1,
+    validation_kind: validationKind,
+    pcr: guidance.pcr,
+    readiness: structuredClone(guidance.readiness),
+    validation_status: validationStatus,
+    completeness,
+    input,
+    check_coverage: {
+      total_requirement_count: checkedRequirementCount + skippedRequirementCount,
+      checked_requirement_count: checkedRequirementCount,
+      skipped_requirement_count: skippedRequirementCount,
+      checks_performed: checksPerformed,
+      checks_skipped: checksSkipped,
+    },
+    finding_count: findings.length,
+    finding_summary: findingSummary,
+    findings,
+  };
+  assertCoreContract("validation-output.schema.json", report, {
+    code: "PCR_INTERNAL_CONTRACT_INVALID",
+    entityKind: "PCR validation report",
+  });
+  return report;
+}
+
+function performedCheck(checkId, requirementFamily, requirementCount) {
+  return {
+    check_id: checkId,
+    requirement_family: requirementFamily,
+    requirement_count: requirementCount,
+    evaluated_requirement_count: requirementCount,
+  };
+}
+
+function addSkippedCheck(checks, checkId, requirementFamily, requirementCount) {
+  if (requirementCount <= 0) {
+    return;
+  }
+  checks.push({
+    check_id: checkId,
+    requirement_family: requirementFamily,
+    requirement_count: requirementCount,
+    reason: "Validator does not yet implement this requirement family.",
+  });
+}
+
+function countFindingsBySeverity(findings) {
+  const summary = { error: 0, warning: 0, info: 0 };
+  for (const finding of findings) {
+    if (Object.hasOwn(summary, finding.severity)) {
+      summary[finding.severity] += 1;
+    }
+  }
+  return summary;
+}
+
+function deduplicateMessages(entries) {
+  return [
+    ...new Map(
+      entries.map((entry) => [`${entry.code}\0${entry.message}`, entry]),
+    ).values(),
+  ];
+}
+
+function countInventoryRows(processInventory) {
+  let count = 0;
+  for (const process of asArray(processInventory)) {
+    for (const direction of ["inputs", "outputs"]) {
+      const groups = process?.[direction];
+      if (!isRecord(groups)) {
+        continue;
+      }
+      for (const rows of Object.values(groups)) {
+        count += asArray(rows).length;
+      }
+    }
+  }
+  return count;
+}
+
+function topLevelRequirementCount(value, excludedKeys = []) {
+  if (!isRecord(value)) {
+    return 0;
+  }
+  const excluded = new Set(excludedKeys);
+  return Object.entries(value).filter(
+    ([key, requirement]) => !excluded.has(key) && hasRequirementValue(requirement),
+  ).length;
+}
+
+function hasRequirementValue(value) {
+  if (Array.isArray(value)) {
+    return value.some(hasRequirementValue);
+  }
+  if (isRecord(value)) {
+    return Object.values(value).some(hasRequirementValue);
+  }
+  return value !== undefined && value !== null && String(value).trim() !== "";
+}
+
+function asArray(value) {
+  return Array.isArray(value) ? value : [];
+}
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function findManifestFiles(directory) {
+  const results = [];
+  for (const domainDir of canonicalChildDirectories(directory)) {
+    for (const subdomainDir of canonicalChildDirectories(domainDir)) {
+      for (const pcrDir of canonicalChildDirectories(subdomainDir)) {
+        const manifestPath = path.join(pcrDir, "manifest.yaml");
+        if (isCanonicalFile(manifestPath)) {
+          results.push(manifestPath);
+        }
+      }
+    }
+  }
+  return results;
+}
+
+function canonicalChildDirectories(directory) {
+  return readdirSync(directory)
+    .map((entry) => path.join(directory, entry))
+    .filter(isCanonicalDirectory)
+    .sort((left, right) => left.localeCompare(right));
+}
+
+function isCanonicalDirectory(directory) {
+  try {
+    const stat = lstatSync(directory);
+    return !stat.isSymbolicLink() && stat.isDirectory();
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}
+
+function isCanonicalFile(filePath) {
+  try {
+    const stat = lstatSync(filePath);
+    return !stat.isSymbolicLink() && stat.isFile();
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      return false;
+    }
+    throw error;
+  }
+}
+
+function toPosix(value) {
+  return value.split(path.sep).join("/");
+}