@tiangong-lca/pcr 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,86 @@
+/** Shared language identities. Website route aliases never become PCR identities. */
+export const CANONICAL_PCR_LANGUAGE = "en-US";
+export const REQUIRED_PCR_LANGUAGES = Object.freeze(["en-US", "zh-CN"]);
+export const LEGACY_PCR_ARTIFACT_HASH_FIELDS = Object.freeze({
+  pcr_en_us_sha256: "pcr.en-US.md",
+  pcr_zh_cn_sha256: "pcr.zh-CN.md",
+  structured_sha256: "structured.yaml",
+});
+
+export function assertPcrLanguageCode(language) {
+  if (typeof language !== "string" || !/^[a-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/u.test(language)) {
+    throw new Error(`Invalid PCR language code: ${String(language)}`);
+  }
+  let canonical;
+  try {
+    canonical = Intl.getCanonicalLocales(language)[0];
+  } catch {
+    throw new Error(`Invalid PCR language code: ${language}`);
+  }
+  if (canonical !== language || language === "und") {
+    throw new Error(`PCR language code must use its canonical BCP 47 spelling: ${language}`);
+  }
+  return language;
+}
+
+export function pcrMarkdownFile(language) {
+  return `pcr.${assertPcrLanguageCode(language)}.md`;
+}
+
+export function declaredPcrLanguages(manifest, { strict = true } = {}) {
+  const available = manifest?.languages?.available;
+  // Preserve the legacy reader's fixed-file inspection of incomplete metadata.
+  // Authoring and documentation export always use the strict contract.
+  if (!strict && available === undefined) return [...REQUIRED_PCR_LANGUAGES];
+  if (!Array.isArray(available) || available.length === 0) {
+    throw new Error("PCR manifest requires languages.available.");
+  }
+  const languages = available.map(assertPcrLanguageCode);
+  if (new Set(languages).size !== languages.length) {
+    throw new Error("PCR manifest languages.available must be unique.");
+  }
+  if (strict) {
+    if (manifest.languages.canonical !== CANONICAL_PCR_LANGUAGE) {
+      throw new Error(`PCR canonical language must be ${CANONICAL_PCR_LANGUAGE}.`);
+    }
+    for (const required of REQUIRED_PCR_LANGUAGES) {
+      if (!languages.includes(required)) throw new Error(`PCR requires language ${required}.`);
+    }
+  }
+  return languages;
+}
+
+export function pcrArtifactFiles(manifest, options = {}) {
+  return [...declaredPcrLanguages(manifest, options).map(pcrMarkdownFile), "structured.yaml"];
+}
+
+/** Current release artifacts, with v1 fixed hashes and v2 per-language hashes. */
+export function expectedPcrArtifactHashes(manifest) {
+  const artifacts = manifest?.release_artifacts;
+  if (!artifacts || typeof artifacts !== "object" || Array.isArray(artifacts)) {
+    throw new Error("Managed PCR requires release_artifacts.");
+  }
+  const languages = declaredPcrLanguages(manifest);
+  if (manifest.schema_version === 2) {
+    const hashes = artifacts.markdown_sha256;
+    if (!hashes || typeof hashes !== "object" || Array.isArray(hashes)) {
+      throw new Error("PCR schema v2 requires release_artifacts.markdown_sha256.");
+    }
+    if (Object.keys(hashes).sort().join("\n") !== [...languages].sort().join("\n")) {
+      throw new Error("Release Markdown hashes must match the declared languages exactly.");
+    }
+    return {
+      ...Object.fromEntries(languages.map((language) => [pcrMarkdownFile(language), hashes[language]])),
+      "structured.yaml": artifacts.structured_sha256,
+    };
+  }
+  if (manifest.schema_version !== undefined && manifest.schema_version !== 1) {
+    throw new Error(`Unsupported PCR manifest schema version: ${manifest.schema_version}`);
+  }
+  if (languages.some((language) => !REQUIRED_PCR_LANGUAGES.includes(language))) {
+    throw new Error("A released PCR with optional languages requires schema v2 artifact hashes.");
+  }
+  return Object.fromEntries(
+    Object.entries(LEGACY_PCR_ARTIFACT_HASH_FIELDS).map(([field, file]) => [file, artifacts[field]]),
+  );
+}

package/packages/pcr-core/src/offline-library.mjs

@@ -0,0 +1,121 @@
+import { createHash } from "node:crypto";
+import { createRequire } from "node:module";
+import { closeSync, openSync, readSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { inflateRawSync } from "node:zlib";
+import { parseYaml } from "./yaml-lite.mjs";
+import { expectedPcrArtifactHashes } from "./languages.mjs";
+import { PcrClassificationCoverageNotFoundError } from "./classification-coverage.mjs";
+
+export const LIBRARY_FORMAT_VERSION = 1;
+export const sha256 = (bytes) => `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+export function libraryError(code, message) {
+  return Object.assign(new Error(message), { code });
+}
+export function sqliteDatabase() {
+  const [major, minor] = process.versions.node.split(".").map(Number);
+  if (major < 24 || (major === 24 && minor < 19)) {
+    throw libraryError("PCR_LIBRARY_RUNTIME_UNSUPPORTED", "Offline libraries require Node.js 24.19 or newer.");
+  }
+  return createRequire(import.meta.url)("node:sqlite").DatabaseSync;
+}
+export function hashFile(filename) {
+  const hash = createHash("sha256");
+  const fd = openSync(filename, "r");
+  const buffer = Buffer.alloc(1024 * 1024);
+  try {
+    let count;
+    while ((count = readSync(fd, buffer, 0, buffer.length, null))) hash.update(buffer.subarray(0, count));
+    return `sha256:${hash.digest("hex")}`;
+  } finally { closeSync(fd); }
+}
+export function metadataDigest(db, table) {
+  if (!["records", "aliases", "coverage", "files"].includes(table)) throw new Error("Unknown snapshot table.");
+  const hash = createHash("sha256");
+  const columns = table === "files" ? "key, size, sha256" : "key, value, sha256";
+  for (const row of db.prepare(`SELECT ${columns} FROM ${table} ORDER BY key`).iterate()) {
+    hash.update(JSON.stringify(row)); hash.update("\n");
+  }
+  return `sha256:${hash.digest("hex")}`;
+}
+
+/** Read-only adapter; all original content remains compressed until selected. */
+export class OfflineLibrary {
+  constructor(filename, { expectedSha256 = null, verify = false, onArtifactRead = null } = {}) {
+    this.filename = path.resolve(filename);
+    this.root = path.dirname(this.filename);
+    this.onArtifactRead = onArtifactRead;
+    this.languages = ["en-US"];
+    try {
+      this.manifest = JSON.parse(readFileSync(`${this.filename}.json`, "utf8"));
+      if (this.manifest.format_version !== LIBRARY_FORMAT_VERSION) {
+        throw libraryError("PCR_LIBRARY_FORMAT_UNSUPPORTED", `Unsupported library format ${this.manifest.format_version}; supported: ${LIBRARY_FORMAT_VERSION}.`);
+      }
+      if (JSON.stringify(this.manifest.snapshot?.available_languages) !== JSON.stringify(this.languages)) throw new Error("Unsupported library language policy; expected English only.");
+      if (this.manifest.kind !== "tiangong-pcr-library" || !/^sha256:[a-f0-9]{64}$/u.test(this.manifest.sha256 ?? "")) throw new Error("Invalid library manifest.");
+      if (statSync(this.filename).size !== this.manifest.bytes) throw new Error("Library byte length differs from manifest.");
+      if (expectedSha256 !== null && !/^sha256:[a-f0-9]{64}$/u.test(expectedSha256)) throw new Error("Expected SHA-256 must use sha256:<64 lowercase hex digits>.");
+      if (verify || expectedSha256 !== null) {
+        const digest = hashFile(this.filename);
+        if (digest !== this.manifest.sha256 || (expectedSha256 !== null && digest !== expectedSha256)) throw new Error("Library SHA-256 mismatch.");
+      }
+      const DatabaseSync = sqliteDatabase();
+      this.db = new DatabaseSync(this.filename, { readOnly: true, allowExtension: false, defensive: true });
+      this.db.exec("PRAGMA query_only = ON; PRAGMA trusted_schema = OFF; BEGIN;");
+      if (this.db.prepare("PRAGMA user_version").get().user_version !== LIBRARY_FORMAT_VERSION) throw libraryError("PCR_LIBRARY_FORMAT_UNSUPPORTED", "SQLite format version does not match the reader.");
+      const metadata = JSON.parse(this.db.prepare("SELECT value FROM metadata WHERE key = 'snapshot'").get()?.value ?? "null");
+      if (JSON.stringify(metadata) !== JSON.stringify(this.manifest.snapshot)) throw new Error("Snapshot identity differs from manifest.");
+      for (const table of ["records", "aliases", "coverage", "files"]) {
+        if (metadataDigest(this.db, table) !== this.manifest.index_sha256?.[table]) throw new Error(`Library ${table} index checksum mismatch.`);
+      }
+      if (verify && this.db.prepare("PRAGMA integrity_check").get().integrity_check !== "ok") throw new Error("SQLite integrity check failed.");
+    } catch (error) {
+      this.close();
+      if (error.code?.startsWith("PCR_LIBRARY_")) throw error;
+      throw libraryError("PCR_LIBRARY_INVALID", `Cannot open offline library ${this.filename}: ${error.message}`);
+    }
+  }
+  close() { this.db?.close(); this.db = null; }
+  row(table, key) {
+    const row = this.db.prepare(`SELECT value, sha256 FROM ${table} WHERE key = ?`).get(key);
+    if (!row) return null;
+    if (sha256(row.value) !== row.sha256) throw libraryError("PCR_LIBRARY_INVALID", `Invalid ${table} row: ${key}`);
+    return JSON.parse(row.value);
+  }
+  listPcrs(scope) {
+    const where = scope === "all" ? "" : scope === "material" ? " WHERE kind = 'methodology'" : " WHERE kind = 'legacy_scaffold_reference'";
+    return this.db.prepare(`SELECT value FROM records${where} ORDER BY position`).all().map((row) => JSON.parse(row.value));
+  }
+  entry(id) {
+    const record = this.row("records", String(id));
+    return record ? { id: record.id, path: record.path, manifestPath: path.join(this.root, record.path, "manifest.yaml") } : null;
+  }
+  findAlias(id) { return this.row("aliases", String(id)); }
+  readFile(key) {
+    const row = this.db.prepare("SELECT data, size, sha256 FROM files WHERE key = ?").get(key);
+    if (!row) throw libraryError("PCR_LIBRARY_ARTIFACT_MISSING", `Missing library artifact: ${key}`);
+    try {
+      const bytes = inflateRawSync(row.data, { maxOutputLength: Math.max(1, row.size) });
+      if (bytes.length !== row.size || sha256(bytes) !== row.sha256) throw new Error("checksum mismatch");
+      this.onArtifactRead?.(key);
+      return bytes;
+    } catch (error) { throw libraryError("PCR_LIBRARY_ARTIFACT_INVALID", `Invalid library artifact ${key}: ${error.message}`); }
+  }
+  snapshotFiles(entry) {
+    const manifestBytes = this.readFile(`${entry.path}/manifest.yaml`);
+    const manifest = parseYaml(manifestBytes.toString("utf8"));
+    if (manifest.id !== entry.id) throw libraryError("PCR_LIBRARY_INVALID", "PCR manifest identity mismatch.");
+    const artifacts = Object.fromEntries(["pcr.en-US.md", "structured.yaml"].map((name) => [name, { bytes: this.readFile(`${entry.path}/${name}`) }]));
+    for (const [name, expected] of Object.entries(manifest.release_artifacts ? expectedPcrArtifactHashes(manifest) : {})) {
+      if (!Object.hasOwn(artifacts, name)) continue;
+      if (manifest.release_artifacts && sha256(artifacts[name]?.bytes ?? Buffer.alloc(0)) !== expected) throw libraryError("PCR_LIBRARY_ARTIFACT_INVALID", `Release artifact hash mismatch: ${entry.path}/${name}`);
+    }
+    return { manifest, manifestBytes, artifacts };
+  }
+  coverageSnapshot(system, version) {
+    const key = `${String(system).toLowerCase()}:${version}`;
+    const snapshot = this.row("coverage", key);
+    if (!snapshot) throw new PcrClassificationCoverageNotFoundError({ system, version, relativePath: `classifications/indexes/${system}-${version}-coverage.json` });
+    return snapshot;
+  }
+}

package/packages/pcr-core/src/output-semantics.mjs

@@ -0,0 +1,228 @@
+function semanticIssue(code, instancePath, message, params = {}) {
+  return {
+    code: `semantic.${code}`,
+    instance_path: instancePath,
+    schema_path: `#/x-semantic/${code.replaceAll(".", "/")}`,
+    keyword: "semantic",
+    message,
+    params,
+  };
+}
+
+export function readinessSemanticIssues(readiness) {
+  const issues = [];
+  const blockers = readiness.blockers;
+  const fingerprint = readiness.projection_fingerprint;
+  const usable = readiness.usable_for_guidance && readiness.usable_for_validation;
+
+  if (readiness.usable_for_guidance !== readiness.usable_for_validation) {
+    issues.push(semanticIssue(
+      "readiness.usability_alignment",
+      "/usable_for_validation",
+      "guidance and validation usability must have the same value.",
+    ));
+  }
+
+  if (blockers.length > 0) {
+    if (readiness.status !== "unavailable") {
+      issues.push(semanticIssue(
+        "readiness.blocked_status",
+        "/status",
+        "readiness with blockers must be unavailable.",
+        { blocker_count: blockers.length },
+      ));
+    }
+    if (usable || readiness.usable_for_guidance || readiness.usable_for_validation) {
+      issues.push(semanticIssue(
+        "readiness.blocked_usability",
+        "/usable_for_guidance",
+        "readiness with blockers must not be usable for guidance or validation.",
+        { blocker_count: blockers.length },
+      ));
+    }
+  } else {
+    if (readiness.status === "unavailable") {
+      issues.push(semanticIssue(
+        "readiness.unavailable_without_blocker",
+        "/status",
+        "unavailable readiness must include at least one blocker.",
+      ));
+    }
+    if (!usable) {
+      issues.push(semanticIssue(
+        "readiness.unblocked_usability",
+        "/usable_for_guidance",
+        "readiness without blockers must be usable for guidance and validation.",
+      ));
+    }
+  }
+
+  if (!fingerprint.required) {
+    if (
+      fingerprint.status !== "not_required" ||
+      fingerprint.schema_valid !== null ||
+      fingerprint.issues.length > 0
+    ) {
+      issues.push(semanticIssue(
+        "readiness.fingerprint_not_required",
+        "/projection_fingerprint/status",
+        "a non-required projection fingerprint must be not_required with no schema result or issues.",
+      ));
+    }
+  }
+
+  if (fingerprint.status === "current") {
+    if (
+      fingerprint.schema_valid !== true ||
+      fingerprint.source_hash_valid !== true ||
+      fingerprint.content_hash_valid !== true ||
+      fingerprint.issues.length > 0
+    ) {
+      issues.push(semanticIssue(
+        "readiness.current_fingerprint",
+        "/projection_fingerprint/status",
+        "a current projection fingerprint requires valid schema, source hash, content hash, and no issues.",
+      ));
+    }
+  }
+
+  if (fingerprint.required && usable && fingerprint.status !== "current") {
+    issues.push(semanticIssue(
+      "readiness.usable_fingerprint",
+      "/projection_fingerprint/status",
+      "usable material PCR readiness requires a current projection fingerprint.",
+    ));
+  }
+
+  return issues.sort(compareIssues);
+}
+
+export function validationReportSemanticIssues(report) {
+  const issues = [];
+  const summary = countFindings(report.findings);
+  const performed = report.check_coverage.checks_performed;
+  const skipped = report.check_coverage.checks_skipped;
+  const checkedRequirementCount = performed.reduce(
+    (total, check) => total + check.requirement_count,
+    0,
+  );
+  const skippedRequirementCount = skipped.reduce(
+    (total, check) => total + check.requirement_count,
+    0,
+  );
+
+  if (report.finding_count !== report.findings.length) {
+    issues.push(semanticIssue(
+      "validation.finding_count",
+      "/finding_count",
+      "finding_count must equal findings.length.",
+      { expected: report.findings.length, actual: report.finding_count },
+    ));
+  }
+
+  for (const severity of ["error", "warning", "info"]) {
+    if (report.finding_summary[severity] !== summary[severity]) {
+      issues.push(semanticIssue(
+        `validation.finding_summary.${severity}`,
+        `/finding_summary/${severity}`,
+        `${severity} finding summary must equal the findings array count.`,
+        { expected: summary[severity], actual: report.finding_summary[severity] },
+      ));
+    }
+  }
+
+  for (const [index, check] of performed.entries()) {
+    if (check.evaluated_requirement_count !== check.requirement_count) {
+      issues.push(semanticIssue(
+        "validation.performed_check_coverage",
+        `/check_coverage/checks_performed/${index}/evaluated_requirement_count`,
+        "a performed check must evaluate every requirement it declares.",
+        {
+          requirement_count: check.requirement_count,
+          evaluated_requirement_count: check.evaluated_requirement_count,
+        },
+      ));
+    }
+  }
+
+  const coverage = report.check_coverage;
+  if (coverage.checked_requirement_count !== checkedRequirementCount) {
+    issues.push(semanticIssue(
+      "validation.checked_requirement_count",
+      "/check_coverage/checked_requirement_count",
+      "checked_requirement_count must equal the sum of performed requirement counts.",
+      { expected: checkedRequirementCount, actual: coverage.checked_requirement_count },
+    ));
+  }
+  if (coverage.skipped_requirement_count !== skippedRequirementCount) {
+    issues.push(semanticIssue(
+      "validation.skipped_requirement_count",
+      "/check_coverage/skipped_requirement_count",
+      "skipped_requirement_count must equal the sum of skipped requirement counts.",
+      { expected: skippedRequirementCount, actual: coverage.skipped_requirement_count },
+    ));
+  }
+  const totalRequirementCount = checkedRequirementCount + skippedRequirementCount;
+  if (coverage.total_requirement_count !== totalRequirementCount) {
+    issues.push(semanticIssue(
+      "validation.total_requirement_count",
+      "/check_coverage/total_requirement_count",
+      "total_requirement_count must equal checked plus skipped requirements.",
+      { expected: totalRequirementCount, actual: coverage.total_requirement_count },
+    ));
+  }
+
+  const expectedCompleteness = performed.length === 0
+    ? "none"
+    : skipped.length > 0
+      ? "partial"
+      : "complete";
+  if (report.completeness !== expectedCompleteness) {
+    issues.push(semanticIssue(
+      "validation.completeness",
+      "/completeness",
+      "completeness must reflect performed and skipped checks.",
+      { expected: expectedCompleteness, actual: report.completeness },
+    ));
+  }
+
+  const expectedStatus = summary.error > 0
+    ? "failed"
+    : performed.length === 0
+      ? "inconclusive"
+      : "passed";
+  if (report.validation_status !== expectedStatus) {
+    issues.push(semanticIssue(
+      "validation.status",
+      "/validation_status",
+      "validation_status must reflect error findings and performed coverage.",
+      { expected: expectedStatus, actual: report.validation_status },
+    ));
+  }
+
+  if (!report.input.accepted && performed.length > 0) {
+    issues.push(semanticIssue(
+      "validation.rejected_input_coverage",
+      "/check_coverage/checks_performed",
+      "rejected input must not report performed checks.",
+    ));
+  }
+
+  return issues.sort(compareIssues);
+}
+
+function countFindings(findings) {
+  const summary = { error: 0, warning: 0, info: 0 };
+  for (const finding of findings) {
+    summary[finding.severity] += 1;
+  }
+  return summary;
+}
+
+function compareIssues(left, right) {
+  return (
+    left.instance_path.localeCompare(right.instance_path) ||
+    left.code.localeCompare(right.code) ||
+    left.message.localeCompare(right.message)
+  );
+}