@tiangong-lca/pcr 0.0.0-stage → 0.2.0

package/packages/pcr-core/src/consumption-calculation.mjs

@@ -0,0 +1,53 @@
+import { ConsumptionError, object, strictNumber } from "./consumption-data.mjs";
+
+function text(value, name) {
+  if (typeof value !== "string" || !value.trim()) throw new ConsumptionError("PCR_CALCULATION_INPUT", `${name} must state the unit, basis or evidence explicitly.`, { field: name });
+  return value;
+}
+
+// Arithmetic only: the Agent owns physical equivalence, applicability and evidence.
+export function calculate(request) {
+  if (!object(request)) throw new ConsumptionError("PCR_CALCULATION_INPUT", "Use a JSON object with operation normalize, convert or balance. See calculate --help.");
+  const evidence = text(request.evidence, "evidence");
+  const basis = text(request.basis, "basis");
+  let result;
+  let formula;
+  if (request.operation === "normalize") {
+    const amount = strictNumber(request.amount, "amount");
+    const sourceReference = strictNumber(request.source_reference, "source_reference", { positive: true });
+    const targetReference = strictNumber(request.target_reference, "target_reference", { positive: true });
+    const unit = text(request.unit, "unit");
+    text(request.reference_unit, "reference_unit");
+    result = { amount: amount * targetReference / sourceReference, unit, factor: targetReference / sourceReference };
+    formula = "amount * target_reference / source_reference; both reference quantities share reference_unit and the stated physical basis";
+  } else if (request.operation === "convert") {
+    const amount = strictNumber(request.amount, "amount");
+    const factor = strictNumber(request.factor, "factor", { positive: true });
+    text(request.from_unit, "from_unit");
+    const unit = text(request.to_unit, "to_unit");
+    result = { amount: amount * factor, unit, factor };
+    formula = "amount * factor; factor is explicitly supplied in to_unit / from_unit";
+  } else if (request.operation === "balance") {
+    const unit = text(request.unit, "unit");
+    const sums = {};
+    for (const name of ["inputs", "outputs"]) {
+      if (!Array.isArray(request[name]) || !request[name].length) throw new ConsumptionError("PCR_CALCULATION_INPUT", `${name} must be a non-empty array of {amount, label} in the declared common unit and basis.`);
+      sums[name] = request[name].reduce((sum, item, index) => {
+        if (!object(item)) throw new ConsumptionError("PCR_CALCULATION_INPUT", `${name}[${index}] must be an amount/label object.`);
+        text(item.label, `${name}[${index}].label`);
+        return sum + strictNumber(item.amount, `${name}[${index}].amount`);
+      }, 0);
+    }
+    const accumulation = strictNumber(request.accumulation, "accumulation");
+    result = { input_total: sums.inputs, output_total: sums.outputs, accumulation, residual: sums.inputs - sums.outputs - accumulation, unit };
+    formula = "sum(inputs) - sum(outputs) - accumulation; positive residual is unaccounted net input";
+  } else {
+    throw new ConsumptionError("PCR_CALCULATION_OPERATION", "Use operation normalize, convert or balance. No formulas, factors or units are inferred.");
+  }
+  if (Object.values(result).some((value) => typeof value === "number" && !Number.isFinite(value))) throw new ConsumptionError("PCR_CALCULATION_OVERFLOW", "Calculation produced a non-finite number; rescale or correct the input quantities.");
+  return {
+    schema_version: 1, calculation_kind: "tiangong-pcr-arithmetic", operation: request.operation,
+    request, formula, result, basis, evidence,
+    interpretation: "Arithmetic only, using supplied values and JavaScript floating-point precision. Physical applicability, evidence quality, tolerance and anomaly judgment are not evaluated.",
+  };
+}

package/packages/pcr-core/src/consumption-data.mjs

@@ -0,0 +1,88 @@
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } from "node:fs";
+import path from "node:path";
+
+export class ConsumptionError extends Error {
+  constructor(code, message, details = {}) {
+    super(message);
+    this.name = "ConsumptionError";
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export const sha256 = (bytes) => `sha256:${createHash("sha256").update(bytes).digest("hex")}`;
+export const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+export const pointerToken = (value) => String(value).replaceAll("~", "~0").replaceAll("/", "~1");
+
+export function atPointer(value, pointer) {
+  if (typeof pointer !== "string" || (pointer !== "" && !pointer.startsWith("/")) || /~(?:[^01]|$)/u.test(pointer)) {
+    throw new ConsumptionError("PCR_POINTER_INVALID", "Use an RFC 6901 JSON Pointer, such as /processDataSet/exchanges/exchange/0.");
+  }
+  if (pointer === "") return value;
+  let current = value;
+  for (const encoded of pointer.slice(1).split("/")) {
+    const key = encoded.replaceAll("~1", "/").replaceAll("~0", "~");
+    if (current === null || typeof current !== "object" || !Object.hasOwn(current, key)
+      || (Array.isArray(current) && !/^(0|[1-9]\d*)$/u.test(key))) {
+      throw new ConsumptionError("PCR_POINTER_NOT_FOUND", `No value exists at ${pointer}. Inspect the summary or a paged section first.`, { pointer });
+    }
+    current = current[key];
+  }
+  return current;
+}
+
+export function readJsonDocument(filename, maxBytes = 16 * 1024 * 1024) {
+  const file = path.resolve(filename);
+  let bytes;
+  try {
+    const stat = statSync(file);
+    if (!stat.isFile() || stat.size > maxBytes) {
+      throw new ConsumptionError("PCR_INPUT_SIZE", `Expected a JSON file no larger than ${maxBytes} bytes: ${file}`);
+    }
+    bytes = readFileSync(file);
+    if (bytes.length > maxBytes) throw new ConsumptionError("PCR_INPUT_SIZE", `Input grew beyond ${maxBytes} bytes: ${file}`);
+  } catch (error) {
+    if (error instanceof ConsumptionError) throw error;
+    throw new ConsumptionError("PCR_INPUT_READ", `Cannot read local JSON file ${file}: ${error.message}`, { file });
+  }
+  try {
+    return { file, sha256: sha256(bytes), bytes: bytes.length, value: JSON.parse(bytes.toString("utf8").replace(/^\uFEFF/u, "")) };
+  } catch (error) {
+    throw new ConsumptionError("PCR_INPUT_JSON", `Malformed JSON in ${file}: ${error.message}`, { file });
+  }
+}
+
+export function entriesAt(value, pointer) {
+  if (value === undefined || value === null) return [];
+  return Array.isArray(value)
+    ? value.map((item, index) => ({ pointer: `${pointer}/${index}`, value: item }))
+    : [{ pointer, value }];
+}
+
+export function paginate(items, page = 1, pageSize = 10) {
+  if (!Number.isSafeInteger(page) || page < 1 || !Number.isSafeInteger(pageSize) || pageSize < 1 || pageSize > 100) {
+    throw new ConsumptionError("PCR_PAGE_INVALID", "Use --page >= 1 and --page-size from 1 to 100.");
+  }
+  const pages = Math.max(1, Math.ceil(items.length / pageSize));
+  if (page > pages) throw new ConsumptionError("PCR_PAGE_RANGE", `Page ${page} exceeds ${pages}; use --page ${pages}.`);
+  return {
+    items: items.slice((page - 1) * pageSize, page * pageSize),
+    pagination: { page, page_size: pageSize, total: items.length, total_pages: pages, has_more: page < pages },
+  };
+}
+
+export function preview(value, maxChars = 2400) {
+  const json = JSON.stringify(value);
+  return json.length <= maxChars ? { value, truncated: false }
+    : { excerpt: json.slice(0, maxChars), truncated: true, total_characters: json.length };
+}
+
+export function strictNumber(value, name, { positive = false } = {}) {
+  if ((typeof value !== "number" && typeof value !== "string")
+    || (typeof value === "string" && !/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:[eE][+-]?\d+)?$/u.test(value))
+    || !Number.isFinite(Number(value)) || (positive && Number(value) <= 0)) {
+    throw new ConsumptionError("PCR_NUMBER_INVALID", `${name} must be a finite${positive ? " positive" : ""} decimal number. Missing values are not zero.`, { field: name });
+  }
+  return Number(value);
+}

package/packages/pcr-core/src/consumption-guidance.mjs

@@ -0,0 +1,62 @@
+import { getVerifiedPcrProjection } from "./index.mjs";
+import { ConsumptionError, atPointer, entriesAt, paginate, preview } from "./consumption-data.mjs";
+
+const TOPICS = {
+  overview: ["product_category_identity", "functional_unit", "boundary_abstraction"],
+  "reference-flow": ["functional_unit", "reference_flow_definition"],
+  boundary: ["system_boundary/rules", "boundary_abstraction"],
+  measurement: ["measurement_rules"],
+  inventory: ["process_map", "process_inventory"],
+  collection: ["dataset_production/collection_protocols"],
+  calculation: ["dataset_production/calculation_rules"],
+  allocation: ["allocation_rules"],
+  quality: ["data_quality_rules", "dataset_production/data_quality_requirements", "published_dataset_profile"],
+  validation: ["validation_rules"],
+  sources: ["data_sources"],
+};
+export const GUIDANCE_TOPICS = Object.keys(TOPICS);
+
+export function projectionBinding(snapshot) {
+  return {
+    pcr_id: snapshot.pcr.id,
+    version: snapshot.pcr.version,
+    projection_sha256: snapshot.structured.projection_metadata.generated_content_sha256,
+    markdown_sha256: snapshot.structured.projection_metadata.canonical_markdown.sha256,
+    methodology_status: snapshot.readiness.methodology_status,
+  };
+}
+
+export function pcrEvidence(snapshot, pointer) {
+  return { ...projectionBinding(snapshot), pointer };
+}
+
+export function selectGuidance({ root, pcrId, topic = "overview", pointer, page = 1, pageSize = 10 }) {
+  const snapshot = getVerifiedPcrProjection({ root, pcrId });
+  const base = {
+    schema_version: 1, guidance_kind: "tiangong-pcr-guidance-selection",
+    pcr: projectionBinding(snapshot), readiness: snapshot.readiness,
+    source_structured: snapshot.source_structured,
+    source_markdown: snapshot.source_structured.replace(/structured\.yaml$/u, "pcr.en-US.md"),
+    topics: GUIDANCE_TOPICS,
+    citation_note: "Pointers address this verified structured projection. Preserve its hashes; applicability remains an Agent judgment. Explicit rule IDs may persist across revisions; array pointers are snapshot-bound.",
+  };
+  if (pointer !== undefined) {
+    return { ...base, source: pcrEvidence(snapshot, pointer), value: atPointer(snapshot.structured, pointer) };
+  }
+  if (!Object.hasOwn(TOPICS, topic)) throw new ConsumptionError("PCR_GUIDANCE_TOPIC", `Use --topic ${GUIDANCE_TOPICS.join("|")}.`);
+  const entries = [];
+  for (const name of TOPICS[topic]) {
+    const pointer = `/${name}`;
+    let value;
+    try { value = atPointer(snapshot.structured, pointer); }
+    catch (error) { if (error.code !== "PCR_POINTER_NOT_FOUND") throw error; }
+    for (const entry of entriesAt(value, pointer)) {
+      entries.push({
+        source: pcrEvidence(snapshot, entry.pointer),
+        rule_id: entry.value?.rule_id ?? entry.value?.protocol_id ?? entry.value?.row_id ?? entry.value?.id ?? null,
+        ...preview(entry.value),
+      });
+    }
+  }
+  return { ...base, topic, ...paginate(entries, page, pageSize) };
+}

package/packages/pcr-core/src/consumption-review.mjs

@@ -0,0 +1,83 @@
+import { atPointer } from "./consumption-data.mjs";
+import { getVerifiedPcrProjection } from "./index.mjs";
+import { projectionBinding } from "./consumption-guidance.mjs";
+import { documentIdentity, extractReferences, loadTidasContext } from "./tidas-inspection.mjs";
+import { validateCoreContract } from "./contracts.mjs";
+
+const TOPICS = ["scope_and_applicability", "reference_basis", "inventory_and_boundary", "allocation", "data_quality"];
+
+export function prepareReview({ root, pcrId, input, related }) {
+  const snapshot = getVerifiedPcrProjection({ root, pcrId });
+  const context = loadTidasContext({ input, related });
+  const unresolved = extractReferences(context).filter((reference) => reference.status !== "resolved");
+  return {
+    schema_version: 1, report_kind: "tiangong-pcr-agent-review", status: "draft",
+    pcr: projectionBinding(snapshot), inputs: context.documents.map(documentIdentity),
+    scope: {
+      description: `Review of supplied ${context.primary.kind}; the Agent must establish its declared scope and reference basis.`,
+      applicability: "Not assessed. Explain product, technology, gate and PCR applicability before drawing conclusions.",
+      limitations: [
+        "No semantic review or TIDAS schema validation has been performed by this command.",
+        `${unresolved.length} reference(s) could not be uniquely resolved in the supplied local inputs; inspect references before claiming omissions.`,
+        `${context.ignoredFiles.length} JSON file(s) with no native TIDAS dataset root were ignored by input inspection.`,
+        `PCR methodology status: ${snapshot.readiness.methodology_status}; library availability does not promote candidate methodology.`,
+      ],
+    },
+    coverage: TOPICS.map((topic) => ({ topic, status: "not_reviewed", rationale: "Awaiting Agent investigation of applicability and evidence." })),
+    findings: [],
+  };
+}
+
+export function checkReview({ root, pcrId, input, related, report }) {
+  const shape = validateCoreContract("agent-review.schema.json", report);
+  const issues = [];
+  const add = (code, location, message) => issues.push({ code, location, message });
+  if (!shape.valid) {
+    for (const error of shape.issues ?? shape.errors) add("report_shape", error.instance_path ?? error.instancePath ?? "", error.message);
+  } else {
+    const snapshot = getVerifiedPcrProjection({ root, pcrId });
+    const binding = projectionBinding(snapshot);
+    const context = loadTidasContext({ input, related });
+    const actual = context.documents.map(documentIdentity);
+    const files = new Map(context.documents.map((doc) => [doc.file, doc]));
+    const sameBinding = (candidate) => Object.keys(binding).every((key) => candidate[key] === binding[key]);
+    if (!sameBinding(report.pcr)) add("pcr_changed", "/pcr", "PCR identity, content hashes or methodology status differ from the selected verified projection.");
+    if (report.inputs.length !== actual.length || report.inputs.some((item, index) => Object.keys(actual[index] ?? {}).some((key) => item[key] !== actual[index][key]))) {
+      add("inputs_changed", "/inputs", "Input files, identities, order or exact-byte hashes differ. Regenerate the draft bindings and review the changed evidence.");
+    }
+    if (report.status === "reviewed" && !report.coverage.some((item) => item.status === "reviewed")) add("review_empty", "/coverage", "A reviewed report must name at least one actually reviewed topic; otherwise retain draft status.");
+    const ids = new Set();
+    for (const [index, finding] of report.findings.entries()) {
+      const prefix = `/findings/${index}`;
+      if (ids.has(finding.id)) add("duplicate_finding", `${prefix}/id`, "Finding IDs must be unique within this report.");
+      ids.add(finding.id);
+      for (const [refIndex, reference] of finding.input_refs.entries()) {
+        const location = `${prefix}/input_refs/${refIndex}`;
+        const doc = files.get(reference.file);
+        if (!doc || reference.sha256 !== doc.sha256) add("input_reference_changed", location, "Reference must identify an explicitly supplied input and its current exact-byte hash.");
+        else {
+          try { atPointer(doc.value, reference.pointer); }
+          catch (error) { add("input_pointer", location, error.message); }
+        }
+      }
+      for (const [refIndex, reference] of finding.pcr_refs.entries()) {
+        const location = `${prefix}/pcr_refs/${refIndex}`;
+        if (!sameBinding(reference)) add("pcr_reference_changed", location, "PCR reference does not match the selected verified projection.");
+        else {
+          try { atPointer(snapshot.structured, reference.pointer); }
+          catch (error) { add("pcr_pointer", location, error.message); }
+        }
+      }
+    }
+  }
+  return {
+    schema_version: 1, check_kind: "tiangong-pcr-review-envelope-check",
+    envelope_valid: issues.length === 0, methodology_approval: false,
+    report_status: shape.valid ? report.status : null,
+    checked: ["report_shape", ...(shape.valid ? ["input_and_pcr_bindings", "finding_reference_locations", "review_status_consistency"] : [])],
+    not_checked: ["PCR applicability", "truth of observations or conclusions", "sufficiency of evidence", "coverage completeness", "TIDAS schema validity"],
+    issues,
+    next_step: issues.length ? "Correct the report or re-review changed evidence, then run review check again."
+      : "Have the Agent/user assess the reasoning and remaining scope. Envelope validity does not approve the dataset.",
+  };
+}

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

@@ -0,0 +1,195 @@
+import { readFileSync } from "node:fs";
+
+import { createSchemaRegistry } from "./schema-validation.mjs";
+import {
+  readinessSemanticIssues,
+  validationReportSemanticIssues,
+} from "./output-semantics.mjs";
+
+const CORE_SCHEMA_DEPENDENCY_FILES = ["controlled-vocabulary.schema.json"];
+const CORE_SCHEMA_FILES = [
+  "agent-review.schema.json",
+  "classification-coverage.schema.json",
+  "dataset-validation-input.schema.json",
+  "feedback-draft-output.schema.json",
+  "feedback.schema.json",
+  "guidance-output.schema.json",
+  "model-validation-input.schema.json",
+  "pcr-id-aliases.schema.json",
+  "readiness.schema.json",
+  "structured-projection.schema.json",
+  "validation-output.schema.json",
+];
+
+const schemaEntries = CORE_SCHEMA_FILES.map((fileName) => ({
+  fileName,
+  schema: JSON.parse(readFileSync(new URL(`../schemas/${fileName}`, import.meta.url), "utf8")),
+}));
+const schemaDependencies = CORE_SCHEMA_DEPENDENCY_FILES.map((fileName) =>
+  JSON.parse(readFileSync(new URL(`../schemas/${fileName}`, import.meta.url), "utf8")),
+);
+const contractIds = new Map(schemaEntries.map(({ fileName, schema }) => [fileName, schema.$id]));
+const entityKindsByFile = {
+  "agent-review.schema.json": "agent_review",
+  "classification-coverage.schema.json": "classification_coverage",
+  "dataset-validation-input.schema.json": "dataset_validation_input",
+  "feedback-draft-output.schema.json": "feedback_draft_output",
+  "feedback.schema.json": "feedback_intake",
+  "guidance-output.schema.json": "guidance_output",
+  "model-validation-input.schema.json": "model_validation_input",
+  "pcr-id-aliases.schema.json": "pcr_id_aliases",
+  "readiness.schema.json": "readiness",
+  "structured-projection.schema.json": "structured_projection",
+  "validation-output.schema.json": "validation_report",
+};
+const registry = createSchemaRegistry(
+  [...schemaDependencies, ...schemaEntries.map(({ schema }) => schema)],
+  Object.fromEntries(
+    schemaEntries.map(({ fileName, schema }) => [schema.$id, entityKindsByFile[fileName]]),
+  ),
+);
+
+const semanticValidators = new Map([
+  [contractIds.get("readiness.schema.json"), readinessSemanticIssues],
+  [contractIds.get("validation-output.schema.json"), validationReportSemanticIssues],
+]);
+
+export class CoreContractSemanticError extends Error {
+  constructor({
+    code = "PCR_SEMANTIC_CONTRACT_INVALID",
+    contract,
+    entityKind,
+    source = null,
+    issues,
+  }) {
+    const location = source ? ` at ${source}` : "";
+    const details = issues.map((issue) => `${issue.instance_path}: ${issue.message}`).join("; ");
+    super(`${entityKind} semantic contract failed${location}: ${details}`);
+    this.name = "CoreContractSemanticError";
+    this.code = code;
+    this.contract = contract;
+    this.entity_kind = entityKind;
+    this.schema_id = contract;
+    this.source = source;
+    this.issues = structuredClone(issues);
+    this.errors = structuredClone(issues);
+  }
+
+  toJSON() {
+    return {
+      code: this.code,
+      entity_kind: this.entity_kind,
+      schema_id: this.schema_id,
+      source: this.source,
+      errors: structuredClone(this.errors),
+    };
+  }
+}
+
+export const CORE_SCHEMA_IDS = Object.freeze({
+  classificationCoverage: contractIds.get("classification-coverage.schema.json"),
+  structured: contractIds.get("structured-projection.schema.json"),
+  readiness: contractIds.get("readiness.schema.json"),
+  guidance: contractIds.get("guidance-output.schema.json"),
+  validationReport: contractIds.get("validation-output.schema.json"),
+  feedbackDraft: contractIds.get("feedback-draft-output.schema.json"),
+  feedbackIntake: contractIds.get("feedback.schema.json"),
+  modelInput: contractIds.get("model-validation-input.schema.json"),
+  datasetInput: contractIds.get("dataset-validation-input.schema.json"),
+  pcrIdAliases: contractIds.get("pcr-id-aliases.schema.json"),
+});
+
+export function assertCoreContract(contract, value, options = {}) {
+  const contractId = resolveContractId(contract);
+  registry.assert(contractId, value, options);
+  const issues = semanticValidators.get(contractId)?.(value) ?? [];
+  if (issues.length > 0) {
+    throw new CoreContractSemanticError({
+      code: options.code,
+      contract: contractId,
+      entityKind: options.entityKind ?? entityKindsByContract.get(contractId) ?? contractId,
+      source: options.source,
+      issues,
+    });
+  }
+  return value;
+}
+
+export function validateCoreContract(contract, value, options = {}) {
+  const contractId = resolveContractId(contract);
+  const result = registry.validate(contractId, value, options);
+  if (!result.valid) {
+    return result;
+  }
+  const errors = semanticValidators.get(contractId)?.(value) ?? [];
+  if (errors.length === 0) {
+    return result;
+  }
+  return {
+    ...result,
+    valid: false,
+    code: "PCR_SEMANTIC_CONTRACT_INVALID",
+    errors,
+    issues: errors,
+  };
+}
+
+export function coreContractId(fileName) {
+  return resolveContractId(fileName);
+}
+
+export const validateStructured = (value) =>
+  validateCoreContract("structured-projection.schema.json", value);
+export const assertStructured = (value, options = {}) =>
+  assertCoreContract("structured-projection.schema.json", value, options);
+export const validateReadiness = (value) => validateCoreContract("readiness.schema.json", value);
+export const assertReadiness = (value, options = {}) =>
+  assertCoreContract("readiness.schema.json", value, options);
+export const validateGuidance = (value) => validateCoreContract("guidance-output.schema.json", value);
+export const assertGuidance = (value, options = {}) =>
+  assertCoreContract("guidance-output.schema.json", value, options);
+export const validateValidationReport = (value) =>
+  validateCoreContract("validation-output.schema.json", value);
+export const assertValidationReport = (value, options = {}) =>
+  assertCoreContract("validation-output.schema.json", value, options);
+export const validateFeedbackDraft = (value) =>
+  validateCoreContract("feedback-draft-output.schema.json", value);
+export const assertFeedbackDraft = (value, options = {}) =>
+  assertCoreContract("feedback-draft-output.schema.json", value, options);
+export const validateFeedbackIntake = (value) =>
+  validateCoreContract("feedback.schema.json", value);
+export const assertFeedbackIntake = (value, options = {}) =>
+  assertCoreContract("feedback.schema.json", value, options);
+export const validateModelInput = (value) =>
+  validateCoreContract("model-validation-input.schema.json", value);
+export const assertModelInput = (value, options = {}) =>
+  assertCoreContract("model-validation-input.schema.json", value, options);
+export const validateDatasetInput = (value) =>
+  validateCoreContract("dataset-validation-input.schema.json", value);
+export const assertDatasetInput = (value, options = {}) =>
+  assertCoreContract("dataset-validation-input.schema.json", value, options);
+export const validateClassificationCoverage = (value) =>
+  validateCoreContract("classification-coverage.schema.json", value);
+export const assertClassificationCoverage = (value, options = {}) =>
+  assertCoreContract("classification-coverage.schema.json", value, options);
+export const validatePcrIdAliases = (value) =>
+  validateCoreContract("pcr-id-aliases.schema.json", value);
+export const assertPcrIdAliases = (value, options = {}) =>
+  assertCoreContract("pcr-id-aliases.schema.json", value, options);
+
+export const validateStructuredProjection = validateStructured;
+export const assertStructuredProjection = assertStructured;
+export const validateGuidanceOutput = validateGuidance;
+export const assertGuidanceOutput = assertGuidance;
+export const validateModelValidationInput = validateModelInput;
+export const assertModelValidationInput = assertModelInput;
+export const validateDatasetValidationInput = validateDatasetInput;
+export const assertDatasetValidationInput = assertDatasetInput;
+
+function resolveContractId(contract) {
+  return contractIds.get(contract) ?? contract;
+}
+
+const entityKindsByContract = new Map(
+  schemaEntries.map(({ fileName, schema }) => [schema.$id, entityKindsByFile[fileName]]),
+);

package/packages/pcr-core/src/generated/controlled-vocabulary.mjs

@@ -0,0 +1,41 @@
+// Generated by builder/scripts/generate-controlled-vocabulary.mjs.
+// Do not edit this file directly; edit builder/vocab/*.yaml and run npm run vocab:generate.
+
+export const AMOUNT_RANGE_ROLE_VALUES = Object.freeze(["qa_guardrail","typical_range","allowed_range","default_estimate","uncertainty_range"]);
+export const AMOUNT_SPECIFICITY_VALUES = Object.freeze(["generic","site_specific","product_specific","route_specific","scenario_specific","technology_specific","not_applicable"]);
+export const AMOUNT_VALUE_MODE_VALUES = Object.freeze(["fixed_value","foreground_record","calculated_value","modelled_estimate","not_applicable"]);
+export const BASIS_KIND_VALUES = Object.freeze(["reference_flow","process_output","n_input","fuel_inventory","transport_service","storage_duration","crop_cycle"]);
+export const CLASSIFICATION_COVERAGE_STATUS_VALUES = Object.freeze(["mapped","unmapped","candidate_suggestion","manual_review","unknown"]);
+export const CLASSIFICATION_MAPPING_RELATION_VALUES = Object.freeze(["exact","broader","narrower","proxy","manual_review"]);
+export const CONTENT_MATURITY_VALUES = Object.freeze(["empty_scaffold","draft_methodology","authored_methodology","reviewed_methodology","published_methodology","deprecated_methodology"]);
+export const EVIDENCE_KIND_VALUES = Object.freeze(["external_source","observed_dataset","method_formula","foreground_data","tiangong_default","collected_record","calculated_from_collection","identity_reference","source_rule","reasoned_estimate"]);
+export const FEEDBACK_CONFIDENCE_VALUES = Object.freeze(["high","medium","low","unknown"]);
+export const FEEDBACK_TYPE_VALUES = Object.freeze(["missing_pcr","classification_mapping_gap","unclear_reference_flow","wrong_or_missing_uuid","process_boundary_issue","inventory_flow_gap","range_evidence_update","unit_or_flow_property_issue","validation_rule_issue","translation_mismatch","source_update"]);
+export const FLOW_DIRECTION_VALUES = Object.freeze(["inputs","outputs"]);
+export const FLOW_TYPE_VALUES = Object.freeze(["product","waste","elementary"]);
+export const PCR_STATUS_VALUES = Object.freeze(["scaffold","candidate","active","published","deprecated"]);
+export const PROCESS_INCLUSION_VALUES = Object.freeze(["required","conditional","optional","excluded_by_default"]);
+export const SOURCE_TYPE_VALUES = Object.freeze(["official_guidance","literature","standard","dataset","method_factor","extension_guidance","handbook"]);
+export const TARGET_ENTITY_VALUES = Object.freeze(["flow","process","lifecyclemodel","dataset"]);
+export const TRANSLATION_STATUS_VALUES = Object.freeze(["not_available","scaffold","scaffold_pending_translation","draft_translation","aligned","reviewed","out_of_sync"]);
+
+export const CONTROLLED_VOCABULARY = Object.freeze({
+  amount_range_role: AMOUNT_RANGE_ROLE_VALUES,
+  amount_specificity: AMOUNT_SPECIFICITY_VALUES,
+  amount_value_mode: AMOUNT_VALUE_MODE_VALUES,
+  basis_kind: BASIS_KIND_VALUES,
+  classification_coverage_status: CLASSIFICATION_COVERAGE_STATUS_VALUES,
+  classification_mapping_relation: CLASSIFICATION_MAPPING_RELATION_VALUES,
+  content_maturity: CONTENT_MATURITY_VALUES,
+  evidence_kind: EVIDENCE_KIND_VALUES,
+  feedback_confidence: FEEDBACK_CONFIDENCE_VALUES,
+  feedback_type: FEEDBACK_TYPE_VALUES,
+  flow_direction: FLOW_DIRECTION_VALUES,
+  flow_type: FLOW_TYPE_VALUES,
+  pcr_status: PCR_STATUS_VALUES,
+  process_inclusion: PROCESS_INCLUSION_VALUES,
+  source_type: SOURCE_TYPE_VALUES,
+  target_entity: TARGET_ENTITY_VALUES,
+  translation_status: TRANSLATION_STATUS_VALUES,
+});
+