@tiangong-lca/pcr 0.0.0-stage → 0.1.2

package/packages/pcr-core/src/classification-coverage.mjs

@@ -0,0 +1,732 @@
+import { pcrSource } from "./source-context.mjs";
+import { createHash } from "node:crypto";
+import {
+  closeSync,
+  constants as fsConstants,
+  existsSync,
+  fstatSync,
+  lstatSync,
+  openSync,
+  readFileSync,
+  realpathSync,
+} from "node:fs";
+import path from "node:path";
+import { TextDecoder } from "node:util";
+
+import { assertCoreContract } from "./contracts.mjs";
+import {
+  CLASSIFICATION_COVERAGE_STATUS_VALUES,
+  CLASSIFICATION_MAPPING_RELATION_VALUES,
+} from "./generated/controlled-vocabulary.mjs";
+import { parseYaml } from "./yaml-lite.mjs";
+
+export const CLASSIFICATION_COVERAGE_STATUSES = CLASSIFICATION_COVERAGE_STATUS_VALUES;
+export const CLASSIFICATION_COVERAGE_CONTRACT_VERSION = "2";
+export const CLASSIFICATION_COVERAGE_GENERATOR = "builder/scripts/build-catalog.mjs";
+export const CLASSIFICATION_COVERAGE_GENERATOR_VERSION = "2";
+
+const CLASSIFICATION_MAPPING_RELATIONS = new Set(CLASSIFICATION_MAPPING_RELATION_VALUES);
+
+export class PcrClassificationCoverageNotFoundError extends Error {
+  constructor({ system, version, relativePath }) {
+    super(`Classification coverage index not found for ${system}:${version}: ${relativePath}`);
+    this.name = "PcrClassificationCoverageNotFoundError";
+    this.code = "PCR_CLASSIFICATION_COVERAGE_NOT_FOUND";
+    this.details = {
+      classification: `${system}:${version}`,
+      coverage_index: relativePath,
+    };
+  }
+}
+
+export class PcrClassificationCodeUnknownError extends Error {
+  constructor({ system, version, code }) {
+    super(`Classification code is not present in the coverage index: ${system}:${version}:${code}`);
+    this.name = "PcrClassificationCodeUnknownError";
+    this.code = "PCR_CLASSIFICATION_CODE_UNKNOWN";
+    this.details = { classification: `${system}:${version}:${code}` };
+  }
+}
+
+export class PcrClassificationCoverageSemanticError extends Error {
+  constructor({ system, version, source, issues }) {
+    super(
+      `Classification coverage index is inconsistent for ${system}:${version}: ${issues.join("; ")}`,
+    );
+    this.name = "PcrClassificationCoverageSemanticError";
+    this.code = "PCR_INVALID_CLASSIFICATION_COVERAGE";
+    this.details = {
+      classification: `${system}:${version}`,
+      source,
+      issues: [...issues],
+    };
+  }
+}
+
+export class PcrClassificationCoverageStatusError extends Error {
+  constructor(status) {
+    super(
+      `Unsupported classification coverage status ${String(status)}. Expected one of: ${CLASSIFICATION_COVERAGE_STATUSES.join(", ")}.`,
+    );
+    this.name = "PcrClassificationCoverageStatusError";
+    this.code = "PCR_INVALID_CLASSIFICATION_COVERAGE_STATUS";
+    this.details = {
+      status: String(status),
+      allowed_statuses: [...CLASSIFICATION_COVERAGE_STATUSES],
+    };
+  }
+}
+
+export function classificationCoveragePath({ root, system, version }) {
+  const normalized = normalizeClassification({ system, version });
+  return path.join(
+    path.resolve(root),
+    "classifications/indexes",
+    `${normalized.system}-${normalized.version}-coverage.json`,
+  );
+}
+
+export function hasClassificationCoverage({ root, system, version }) {
+  return existsSync(classificationCoveragePath({ root, system, version }));
+}
+
+export function readClassificationCoverage({ root, system, version }) {
+  return readClassificationCoverageSnapshot({ root, system, version }).document;
+}
+
+export function readClassificationCoverageSnapshot({ root, system, version }) {
+  if (pcrSource(root)) return pcrSource(root).coverageSnapshot(system, version);
+  const normalizedRoot = path.resolve(root);
+  const normalized = normalizeClassification({ system, version });
+  const coveragePath = classificationCoveragePath({
+    root: normalizedRoot,
+    system: normalized.system,
+    version: normalized.version,
+  });
+  const relativePath = toPosix(path.relative(normalizedRoot, coveragePath));
+  if (!existsSync(coveragePath)) {
+    throw new PcrClassificationCoverageNotFoundError({
+      ...normalized,
+      relativePath,
+    });
+  }
+
+  let coverageSource;
+  try {
+    coverageSource = readContainedUtf8RegularFile({
+      root: normalizedRoot,
+      relativePath,
+      label: "coverage index",
+    });
+  } catch (error) {
+    throw new PcrClassificationCoverageSemanticError({
+      ...normalized,
+      source: relativePath,
+      issues: [error instanceof Error ? error.message : String(error)],
+    });
+  }
+
+  let coverage;
+  try {
+    coverage = JSON.parse(coverageSource.text);
+  } catch (error) {
+    throw new PcrClassificationCoverageSemanticError({
+      ...normalized,
+      source: relativePath,
+      issues: [`invalid JSON (${error instanceof Error ? error.message : String(error)})`],
+    });
+  }
+
+  assertCoreContract("classification-coverage.schema.json", coverage, {
+    code: "PCR_INVALID_CLASSIFICATION_COVERAGE",
+    entityKind: "Classification coverage index",
+    source: relativePath,
+  });
+  assertCoverageSemantics({ coverage, normalized, source: relativePath });
+  assertCoverageSources({
+    coverage,
+    normalized,
+    root: normalizedRoot,
+    source: relativePath,
+  });
+  return Object.freeze({
+    document: structuredClone(coverage),
+    relative_path: relativePath,
+    sha256: exactByteSha256(coverageSource.bytes),
+  });
+}
+
+export function getClassificationCoverageSummary({ root, system, version }) {
+  const coverage = readClassificationCoverage({ root, system, version });
+  return {
+    schema_version: coverage.schema_version,
+    index_kind: coverage.index_kind,
+    classification_system: coverage.classification_system,
+    classification_version: coverage.classification_version,
+    source: structuredClone(coverage.source),
+    summary: structuredClone(coverage.summary),
+  };
+}
+
+export function listClassificationCoverage({ root, system, version, status = null }) {
+  if (status !== null && !CLASSIFICATION_COVERAGE_STATUSES.includes(String(status))) {
+    throw new PcrClassificationCoverageStatusError(status);
+  }
+  const coverage = readClassificationCoverage({ root, system, version });
+  const entries = status === null
+    ? coverage.entries
+    : coverage.entries.filter((entry) => entry.coverage_status === String(status));
+  return {
+    classification_system: coverage.classification_system,
+    classification_version: coverage.classification_version,
+    available_statuses: [...CLASSIFICATION_COVERAGE_STATUSES],
+    entries: structuredClone(entries),
+  };
+}
+
+export function findClassificationCoverageEntry({ root, system, version, code }) {
+  const coverage = readClassificationCoverage({ root, system, version });
+  const entry = coverage.entries.find((candidate) => String(candidate.code) === String(code));
+  if (!entry) {
+    throw new PcrClassificationCodeUnknownError({
+      system: String(system).toLowerCase(),
+      version: String(version),
+      code: String(code),
+    });
+  }
+  return structuredClone(entry);
+}
+
+function normalizeClassification({ system, version }) {
+  const normalizedSystem = String(system).toLowerCase();
+  const normalizedVersion = String(version);
+  if (!/^[a-z0-9][a-z0-9_-]*$/u.test(normalizedSystem)) {
+    throw new Error(`Unsupported classification system token: ${String(system)}`);
+  }
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(normalizedVersion)) {
+    throw new Error(`Unsupported classification version token: ${String(version)}`);
+  }
+  return { system: normalizedSystem, version: normalizedVersion };
+}
+
+function assertCoverageSemantics({ coverage, normalized, source }) {
+  const issues = [];
+  if (String(coverage.classification_system).toLowerCase() !== normalized.system) {
+    issues.push(
+      `classification_system ${String(coverage.classification_system)} does not match ${normalized.system}`,
+    );
+  }
+  if (String(coverage.classification_version) !== normalized.version) {
+    issues.push(
+      `classification_version ${String(coverage.classification_version)} does not match ${normalized.version}`,
+    );
+  }
+
+  const seenCodes = new Set();
+  const statusCounts = Object.fromEntries(
+    CLASSIFICATION_COVERAGE_STATUSES.map((status) => [status, 0]),
+  );
+  for (const entry of coverage.entries) {
+    if (seenCodes.has(entry.code)) {
+      issues.push(`duplicate entry code ${entry.code}`);
+    }
+    seenCodes.add(entry.code);
+    statusCounts[entry.coverage_status] += 1;
+    if (entry.path_codes.length !== entry.path_titles.length) {
+      issues.push(`entry ${entry.code} has mismatched path_codes and path_titles lengths`);
+    }
+    if (entry.coverage_status === "mapped" && !entry.mapping) {
+      issues.push(`mapped entry ${entry.code} has no mapping`);
+    }
+    if (entry.mapping && !isProjectedMapping(entry.mapping)) {
+      issues.push(`entry ${entry.code} has a mapping without an accepted decision projection`);
+    }
+    if (
+      ["unmapped", "candidate_suggestion", "manual_review"].includes(entry.coverage_status)
+      && entry.mapping
+    ) {
+      issues.push(`${entry.coverage_status} entry ${entry.code} cannot carry an accepted mapping`);
+    }
+    if (entry.mapping && entry.legacy_reference) {
+      issues.push(`entry ${entry.code} cannot be both a material mapping and a legacy reference`);
+    }
+    if (entry.legacy_reference && entry.coverage_status !== "unmapped") {
+      issues.push(`legacy reference entry ${entry.code} must have coverage_status unmapped`);
+    }
+  }
+  if (coverage.summary.total !== coverage.entries.length) {
+    issues.push(
+      `summary.total ${coverage.summary.total} does not match entries length ${coverage.entries.length}`,
+    );
+  }
+  for (const status of CLASSIFICATION_COVERAGE_STATUSES) {
+    if (coverage.summary[status] !== statusCounts[status]) {
+      issues.push(
+        `summary.${status} ${coverage.summary[status]} does not match entry count ${statusCounts[status]}`,
+      );
+    }
+  }
+
+  if (issues.length > 0) {
+    throw new PcrClassificationCoverageSemanticError({
+      ...normalized,
+      source,
+      issues,
+    });
+  }
+}
+
+function assertCoverageSources({ coverage, normalized, root, source }) {
+  const issues = [];
+  const verifiedSources = {};
+  for (const [sourceName, descriptor, canonicalPath] of [
+    [
+      "normalized_leaves",
+      coverage.source.normalized_leaves,
+      canonicalNormalizedLeavesPath(normalized),
+    ],
+    ["mapping", coverage.source.mapping, canonicalMappingPath(normalized)],
+  ]) {
+    if (descriptor.path !== canonicalPath) {
+      issues.push(sourcePathBindingIssue({ sourceName, descriptor, canonicalPath, normalized }));
+      continue;
+    }
+
+    let sourceFile;
+    try {
+      sourceFile = readContainedUtf8RegularFile({
+        root,
+        relativePath: canonicalPath,
+        label: `source ${sourceName}`,
+      });
+    } catch (error) {
+      issues.push(error instanceof Error ? error.message : String(error));
+      continue;
+    }
+    const actualSha256 = exactByteSha256(sourceFile.bytes);
+    if (actualSha256 !== descriptor.sha256) {
+      issues.push(
+        `source ${sourceName} exact-byte SHA-256 mismatch: expected ${descriptor.sha256}, received ${actualSha256}`,
+      );
+      continue;
+    }
+    verifiedSources[sourceName] = sourceFile;
+  }
+
+  if (verifiedSources.normalized_leaves && verifiedSources.mapping) {
+    let normalizedLeaves;
+    let mapping;
+    try {
+      normalizedLeaves = JSON.parse(verifiedSources.normalized_leaves.text);
+    } catch (error) {
+      issues.push(
+        `source normalized_leaves is not valid JSON (${error instanceof Error ? error.message : String(error)})`,
+      );
+    }
+    try {
+      mapping = parseYaml(verifiedSources.mapping.text);
+    } catch (error) {
+      issues.push(
+        `source mapping is not valid YAML (${error instanceof Error ? error.message : String(error)})`,
+      );
+    }
+    if (normalizedLeaves && mapping) {
+      issues.push(
+        ...coverageProjectionIssues({ coverage, normalized, normalizedLeaves, mapping }),
+      );
+    }
+  }
+  if (issues.length > 0) {
+    throw new PcrClassificationCoverageSemanticError({
+      ...normalized,
+      source,
+      issues,
+    });
+  }
+}
+
+function sourcePathBindingIssue({ sourceName, descriptor, canonicalPath, normalized }) {
+  const reportedPath = String(descriptor.path);
+  const normalizedPath = path.posix.normalize(reportedPath);
+  const escapesRoot = (
+    path.posix.isAbsolute(reportedPath)
+    || normalizedPath === ".."
+    || normalizedPath.startsWith("../")
+  );
+  const reason = escapesRoot
+    ? "escapes the repository root and does not match"
+    : "does not match";
+  return `source ${sourceName} path ${reportedPath} ${reason} canonical path ${canonicalPath} for ${normalized.system}:${normalized.version}`;
+}
+
+function coverageProjectionIssues({ coverage, normalized, normalizedLeaves, mapping }) {
+  const issues = [];
+  if (
+    String(normalizedLeaves.classification_system).toLowerCase() !== normalized.system
+    || String(normalizedLeaves.classification_version) !== normalized.version
+  ) {
+    issues.push(
+      `source normalized_leaves coordinate ${String(normalizedLeaves.classification_system)}:${String(normalizedLeaves.classification_version)} does not match ${normalized.system}:${normalized.version}`,
+    );
+  }
+  if (
+    String(mapping.classification_system).toLowerCase() !== normalized.system
+    || String(mapping.classification_version) !== normalized.version
+  ) {
+    issues.push(
+      `source mapping coordinate ${String(mapping.classification_system)}:${String(mapping.classification_version)} does not match ${normalized.system}:${normalized.version}`,
+    );
+  }
+  if (mapping.schema_version !== 2 || mapping.status !== "current") {
+    issues.push("source mapping must use accepted-only schema_version 2 with status current");
+  }
+
+  if (!Array.isArray(normalizedLeaves.leaves)) {
+    issues.push("source normalized_leaves.leaves must be an array");
+    return issues;
+  }
+  if (!Array.isArray(mapping.mappings)) {
+    issues.push("source mapping.mappings must be an array");
+    return issues;
+  }
+
+  const leavesByCode = new Map();
+  for (const leaf of normalizedLeaves.leaves) {
+    const code = sourceCode(leaf);
+    if (code === null) {
+      issues.push("source normalized_leaves contains a leaf without a code");
+      continue;
+    }
+    if (!isProjectedLeaf(leaf)) {
+      issues.push(`source normalized leaf ${code} cannot be projected deterministically`);
+      continue;
+    }
+    if (leavesByCode.has(code)) {
+      issues.push(`source normalized_leaves contains duplicate code ${code}`);
+      continue;
+    }
+    leavesByCode.set(code, leaf);
+  }
+
+  const entriesByCode = new Map(coverage.entries.map((entry) => [String(entry.code), entry]));
+  const sourceCodes = [...leavesByCode.keys()].sort(compareText);
+  const entryCodes = coverage.entries.map((entry) => String(entry.code));
+  if (!sameStringArrays(entryCodes, sourceCodes)) {
+    issues.push("coverage entries do not match the deterministic normalized-leaf code order");
+  }
+  for (const code of sourceCodes) {
+    const leaf = leavesByCode.get(code);
+    const entry = entriesByCode.get(code);
+    if (!entry) {
+      issues.push(`coverage entries are missing normalized leaf ${code}`);
+      continue;
+    }
+    if (entry.label !== leaf.title) {
+      issues.push(`coverage entry ${code} label does not match normalized leaf title`);
+    }
+    if (!sameStringArrays(entry.path_codes, leaf.path_codes)) {
+      issues.push(`coverage entry ${code} path_codes do not match normalized leaf path_codes`);
+    }
+    if (!sameStringArrays(entry.path_titles, leaf.path_titles)) {
+      issues.push(`coverage entry ${code} path_titles do not match normalized leaf path_titles`);
+    }
+  }
+  for (const code of entryCodes) {
+    if (!leavesByCode.has(code)) {
+      issues.push(`coverage entries contain code ${code} absent from normalized leaves`);
+    }
+  }
+
+  const mappingsByCode = new Map();
+  for (const candidate of mapping.mappings) {
+    const code = sourceCode(candidate);
+    if (code === null) {
+      issues.push("source mapping contains an edge without a code");
+      continue;
+    }
+    if (!leavesByCode.has(code)) {
+      issues.push(`source mapping code ${code} is absent from normalized leaves`);
+    }
+    if (!isProjectedMapping(candidate)) {
+      issues.push(`source mapping for ${code} cannot be projected deterministically`);
+      continue;
+    }
+    if (mappingsByCode.has(code)) {
+      issues.push(`source mapping contains duplicate code ${code}`);
+      continue;
+    }
+    mappingsByCode.set(code, candidate);
+  }
+
+  for (const [code, entry] of entriesByCode) {
+    const sourceMapping = mappingsByCode.get(code);
+    if (!sourceMapping) {
+      if (entry.mapping || entry.legacy_reference) {
+        issues.push(`coverage entry ${code} projects an edge absent from canonical mapping`);
+      }
+      continue;
+    }
+    if (entry.mapping) {
+      for (const field of ["pcr_id", "mapping_type", "confidence"]) {
+        if (entry.mapping[field] !== sourceMapping[field]) {
+          issues.push(`coverage entry ${code} mapping.${field} does not match canonical mapping`);
+        }
+      }
+      for (const field of ["status", "decided_by", "decided_at_utc", "decision_ref"]) {
+        if (entry.mapping.acceptance?.[field] !== sourceMapping.acceptance?.[field]) {
+          issues.push(
+            `coverage entry ${code} mapping.acceptance.${field} does not match canonical mapping`,
+          );
+        }
+      }
+      if (entry.coverage_status !== "mapped") {
+        issues.push(
+          `coverage entry ${code} coverage_status ${entry.coverage_status} does not match accepted canonical mapping projection mapped`,
+        );
+      }
+      continue;
+    }
+    if (entry.legacy_reference) {
+      if (entry.legacy_reference.pcr_id !== sourceMapping.pcr_id) {
+        issues.push(`coverage entry ${code} legacy_reference.pcr_id does not match canonical mapping`);
+      }
+      continue;
+    }
+    issues.push(`coverage entry ${code} does not represent its canonical mapping edge`);
+  }
+  return issues;
+}
+
+function sourceCode(value) {
+  if (!value || typeof value !== "object" || value.code === undefined || value.code === null) {
+    return null;
+  }
+  const code = String(value.code);
+  return code.length > 0 ? code : null;
+}
+
+function isProjectedLeaf(leaf) {
+  return (
+    leaf
+    && typeof leaf === "object"
+    && typeof leaf.title === "string"
+    && leaf.title.length > 0
+    && isStringArray(leaf.path_codes)
+    && leaf.path_codes.length > 0
+    && isStringArray(leaf.path_titles)
+    && leaf.path_titles.length > 0
+  );
+}
+
+function isProjectedMapping(mapping) {
+  return (
+    mapping
+    && typeof mapping === "object"
+    && typeof mapping.pcr_id === "string"
+    && mapping.pcr_id.startsWith("pcr.")
+    && CLASSIFICATION_MAPPING_RELATIONS.has(mapping.mapping_type)
+    && mapping.mapping_type !== "manual_review"
+    && typeof mapping.confidence === "string"
+    && mapping.confidence.length > 0
+    && mapping.acceptance?.status === "accepted"
+    && typeof mapping.acceptance?.decided_by === "string"
+    && mapping.acceptance.decided_by.trim().length > 0
+    && isCanonicalUtcTimestamp(mapping.acceptance?.decided_at_utc)
+    && typeof mapping.acceptance?.decision_ref === "string"
+    && mapping.acceptance.decision_ref.trim().length > 0
+  );
+}
+
+function isCanonicalUtcTimestamp(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 isStringArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+
+function sameStringArrays(left, right) {
+  return (
+    isStringArray(left)
+    && isStringArray(right)
+    && left.length === right.length
+    && left.every((value, index) => value === right[index])
+  );
+}
+
+function compareText(left, right) {
+  const normalizedLeft = String(left);
+  const normalizedRight = String(right);
+  return normalizedLeft < normalizedRight ? -1 : normalizedLeft > normalizedRight ? 1 : 0;
+}
+
+function canonicalNormalizedLeavesPath({ system, version }) {
+  return `classifications/systems/${system}/${version}/normalized/leaves.json`;
+}
+
+function canonicalMappingPath({ system, version }) {
+  return `classifications/mappings/${system}-${version}-to-pcr.yaml`;
+}
+
+function readContainedUtf8RegularFile({ root, relativePath, label }) {
+  if (typeof relativePath !== "string" || relativePath.length === 0) {
+    throw new Error(`${label} path must be a non-empty repository-relative path`);
+  }
+  if (
+    path.posix.isAbsolute(relativePath)
+    || relativePath.includes("\\")
+    || path.posix.normalize(relativePath) !== relativePath
+  ) {
+    throw new Error(`${label} path is not a canonical repository-relative path: ${relativePath}`);
+  }
+
+  const resolvedRoot = path.resolve(root);
+  const resolvedPath = path.resolve(resolvedRoot, ...relativePath.split("/"));
+  const containedRelativePath = path.relative(resolvedRoot, resolvedPath);
+  if (
+    containedRelativePath.length === 0
+    || containedRelativePath === ".."
+    || containedRelativePath.startsWith(`..${path.sep}`)
+    || path.isAbsolute(containedRelativePath)
+  ) {
+    throw new Error(`${label} path escapes the repository root: ${relativePath}`);
+  }
+
+  assertRegularPathChain({
+    resolvedRoot,
+    containedRelativePath,
+    relativePath,
+    label,
+  });
+  assertRealPathContained({
+    root: resolvedRoot,
+    candidate: resolvedPath,
+    label,
+    relativePath,
+  });
+
+  let descriptor;
+  let bytes;
+  try {
+    descriptor = openSync(
+      resolvedPath,
+      fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW | fsConstants.O_NONBLOCK,
+    );
+    const openedStats = fstatSync(descriptor);
+    if (!openedStats.isFile()) {
+      throw new Error(`${label} is not a regular file: ${relativePath}`);
+    }
+    const currentStats = assertRegularPathChain({
+      resolvedRoot,
+      containedRelativePath,
+      relativePath,
+      label,
+    });
+    assertRealPathContained({
+      root: resolvedRoot,
+      candidate: resolvedPath,
+      label,
+      relativePath,
+    });
+    if (openedStats.dev !== currentStats.dev || openedStats.ino !== currentStats.ino) {
+      throw new Error(`${label} path changed while it was being opened: ${relativePath}`);
+    }
+    bytes = readFileSync(descriptor);
+  } catch (error) {
+    if (error instanceof Error && error.message.startsWith(`${label} `)) {
+      throw error;
+    }
+    throw new Error(
+      `${label} could not be opened without following symbolic links: ${relativePath} (${error instanceof Error ? error.code ?? error.message : String(error)})`,
+    );
+  } finally {
+    if (descriptor !== undefined) {
+      closeSync(descriptor);
+    }
+  }
+
+  return {
+    bytes,
+    text: decodeFatalUtf8(bytes, { label, relativePath }),
+  };
+}
+
+function assertRegularPathChain({ resolvedRoot, containedRelativePath, relativePath, label }) {
+  const segments = containedRelativePath.split(path.sep);
+  let currentPath = resolvedRoot;
+  let finalStats;
+  for (const [index, segment] of segments.entries()) {
+    currentPath = path.join(currentPath, segment);
+    let stats;
+    try {
+      stats = lstatSync(currentPath);
+    } catch (error) {
+      throw new Error(
+        `${label} does not exist at ${relativePath} (${error instanceof Error ? error.code ?? error.message : String(error)})`,
+      );
+    }
+    if (stats.isSymbolicLink()) {
+      throw new Error(`${label} path contains a symbolic link: ${relativePath}`);
+    }
+    const isLastSegment = index === segments.length - 1;
+    if (isLastSegment && !stats.isFile()) {
+      throw new Error(`${label} is not a regular file: ${relativePath}`);
+    }
+    if (!isLastSegment && !stats.isDirectory()) {
+      throw new Error(`${label} parent is not a directory: ${relativePath}`);
+    }
+    if (isLastSegment) {
+      finalStats = stats;
+    }
+  }
+  return finalStats;
+}
+
+function decodeFatalUtf8(bytes, { label, relativePath }) {
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch (error) {
+    throw new Error(
+      `${label} is not valid UTF-8: ${relativePath} (${error instanceof Error ? error.message : String(error)})`,
+    );
+  }
+}
+
+function assertRealPathContained({ root, candidate, label, relativePath }) {
+  const realRoot = realpathSync(root);
+  const realCandidate = realpathSync(candidate);
+  const realRelativePath = path.relative(realRoot, realCandidate);
+  if (
+    realRelativePath.length === 0
+    || realRelativePath === ".."
+    || realRelativePath.startsWith(`..${path.sep}`)
+    || path.isAbsolute(realRelativePath)
+  ) {
+    throw new Error(`${label} real path escapes the repository root: ${relativePath}`);
+  }
+}
+
+function exactByteSha256(bytes) {
+  return `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+}
+
+function toPosix(value) {
+  return value.split(path.sep).join("/");
+}