@tiangong-lca/pcr 0.0.0-stage → 0.2.0

package/packages/pcr-core/schemas/classification-coverage.schema.json

@@ -0,0 +1,187 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tiangong-lca.org/schemas/pcr/v1/classification-coverage.schema.json",
+  "title": "TianGong PCR classification coverage index",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "index_kind",
+    "classification_system",
+    "classification_version",
+    "source",
+    "summary",
+    "entries"
+  ],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "index_kind": { "const": "classification-pcr-coverage" },
+    "classification_system": { "type": "string", "minLength": 1 },
+    "classification_version": { "type": "string", "minLength": 1 },
+    "source": { "$ref": "#/$defs/source" },
+    "summary": { "$ref": "#/$defs/summary" },
+    "entries": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/coverageEntry" }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "coverageEntry": {
+      "type": "object",
+      "required": [
+        "code",
+        "label",
+        "path_codes",
+        "path_titles",
+        "coverage_status",
+        "mapping",
+        "legacy_reference"
+      ],
+      "properties": {
+        "code": { "type": "string", "minLength": 1 },
+        "label": { "type": "string", "minLength": 1 },
+        "path_codes": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "path_titles": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "coverage_status": {
+          "$ref": "https://tiangong-lca.org/schemas/pcr/v1/controlled-vocabulary.schema.json#/$defs/classification_coverage_status"
+        },
+        "mapping": {
+          "anyOf": [
+            { "$ref": "#/$defs/mapping" },
+            { "type": "null" }
+          ]
+        },
+        "legacy_reference": {
+          "anyOf": [
+            { "$ref": "#/$defs/legacyReference" },
+            { "type": "null" }
+          ]
+        }
+      },
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "if": {
+            "properties": { "coverage_status": { "const": "mapped" } },
+            "required": ["coverage_status"]
+          },
+          "then": {
+            "properties": {
+              "mapping": { "$ref": "#/$defs/mapping" },
+              "legacy_reference": { "type": "null" }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "coverage_status": { "enum": ["unmapped", "candidate_suggestion", "manual_review"] }
+            },
+            "required": ["coverage_status"]
+          },
+          "then": {
+            "properties": { "mapping": { "type": "null" } }
+          }
+        }
+      ]
+    },
+    "source": {
+      "type": "object",
+      "required": [
+        "contract_version",
+        "generator",
+        "generator_version",
+        "normalized_leaves",
+        "mapping"
+      ],
+      "properties": {
+        "contract_version": { "const": "2" },
+        "generator": { "const": "builder/scripts/build-catalog.mjs" },
+        "generator_version": { "const": "2" },
+        "normalized_leaves": { "$ref": "#/$defs/sourceArtifact" },
+        "mapping": { "$ref": "#/$defs/sourceArtifact" }
+      },
+      "additionalProperties": false
+    },
+    "sourceArtifact": {
+      "type": "object",
+      "required": ["path", "hash_mode", "sha256"],
+      "properties": {
+        "path": { "type": "string", "minLength": 1 },
+        "hash_mode": { "const": "exact_bytes" },
+        "sha256": { "$ref": "#/$defs/sha256" }
+      },
+      "additionalProperties": false
+    },
+    "sha256": {
+      "type": "string",
+      "pattern": "^sha256:[0-9a-f]{64}$"
+    },
+    "summary": {
+      "type": "object",
+      "required": ["total", "mapped", "unmapped", "candidate_suggestion", "manual_review", "unknown"],
+      "properties": {
+        "total": { "type": "integer", "minimum": 0 },
+        "mapped": { "type": "integer", "minimum": 0 },
+        "unmapped": { "type": "integer", "minimum": 0 },
+        "candidate_suggestion": { "type": "integer", "minimum": 0 },
+        "manual_review": { "type": "integer", "minimum": 0 },
+        "unknown": { "type": "integer", "minimum": 0 }
+      },
+      "additionalProperties": false
+    },
+    "mapping": {
+      "type": "object",
+      "required": ["pcr_id", "mapping_type", "confidence", "acceptance"],
+      "properties": {
+        "pcr_id": { "type": "string", "minLength": 1 },
+        "mapping_type": {
+          "allOf": [
+            {
+              "$ref": "https://tiangong-lca.org/schemas/pcr/v1/controlled-vocabulary.schema.json#/$defs/classification_mapping_relation"
+            },
+            { "not": { "const": "manual_review" } }
+          ]
+        },
+        "confidence": { "type": "string", "minLength": 1 },
+        "acceptance": { "$ref": "#/$defs/acceptance" }
+      },
+      "additionalProperties": false
+    },
+    "acceptance": {
+      "type": "object",
+      "required": ["status", "decided_by", "decided_at_utc", "decision_ref"],
+      "properties": {
+        "status": { "const": "accepted" },
+        "decided_by": { "type": "string", "pattern": "\\S" },
+        "decided_at_utc": {
+          "type": "string",
+          "pattern": "^[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$"
+        },
+        "decision_ref": {
+          "type": "string",
+          "pattern": "^(?:docs|classifications/migrations)/[A-Za-z0-9][A-Za-z0-9._/-]*\\.(?:md|ya?ml|json)(?:#[A-Za-z0-9][A-Za-z0-9._-]*)?$"
+        }
+      },
+      "additionalProperties": false
+    },
+    "legacyReference": {
+      "type": "object",
+      "required": ["kind", "pcr_id", "path"],
+      "properties": {
+        "kind": { "const": "legacy_scaffold_reference" },
+        "pcr_id": { "type": "string", "minLength": 1 },
+        "path": { "type": "string", "minLength": 1 }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/packages/pcr-core/schemas/controlled-vocabulary.schema.json

@@ -0,0 +1,189 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tiangong-lca.org/schemas/pcr/v1/controlled-vocabulary.schema.json",
+  "title": "TianGong PCR controlled vocabulary",
+  "$defs": {
+    "amount_range_role": {
+      "type": "string",
+      "enum": [
+        "qa_guardrail",
+        "typical_range",
+        "allowed_range",
+        "default_estimate",
+        "uncertainty_range"
+      ]
+    },
+    "amount_specificity": {
+      "type": "string",
+      "enum": [
+        "generic",
+        "site_specific",
+        "product_specific",
+        "route_specific",
+        "scenario_specific",
+        "technology_specific",
+        "not_applicable"
+      ]
+    },
+    "amount_value_mode": {
+      "type": "string",
+      "enum": [
+        "fixed_value",
+        "foreground_record",
+        "calculated_value",
+        "modelled_estimate",
+        "not_applicable"
+      ]
+    },
+    "basis_kind": {
+      "type": "string",
+      "enum": [
+        "reference_flow",
+        "process_output",
+        "n_input",
+        "fuel_inventory",
+        "transport_service",
+        "storage_duration",
+        "crop_cycle"
+      ]
+    },
+    "classification_coverage_status": {
+      "type": "string",
+      "enum": [
+        "mapped",
+        "unmapped",
+        "candidate_suggestion",
+        "manual_review",
+        "unknown"
+      ]
+    },
+    "classification_mapping_relation": {
+      "type": "string",
+      "enum": [
+        "exact",
+        "broader",
+        "narrower",
+        "proxy",
+        "manual_review"
+      ]
+    },
+    "content_maturity": {
+      "type": "string",
+      "enum": [
+        "empty_scaffold",
+        "draft_methodology",
+        "authored_methodology",
+        "reviewed_methodology",
+        "published_methodology",
+        "deprecated_methodology"
+      ]
+    },
+    "evidence_kind": {
+      "type": "string",
+      "enum": [
+        "external_source",
+        "observed_dataset",
+        "method_formula",
+        "foreground_data",
+        "tiangong_default",
+        "collected_record",
+        "calculated_from_collection",
+        "identity_reference",
+        "source_rule",
+        "reasoned_estimate"
+      ]
+    },
+    "feedback_confidence": {
+      "type": "string",
+      "enum": [
+        "high",
+        "medium",
+        "low",
+        "unknown"
+      ]
+    },
+    "feedback_type": {
+      "type": "string",
+      "enum": [
+        "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"
+      ]
+    },
+    "flow_direction": {
+      "type": "string",
+      "enum": [
+        "inputs",
+        "outputs"
+      ]
+    },
+    "flow_type": {
+      "type": "string",
+      "enum": [
+        "product",
+        "waste",
+        "elementary"
+      ]
+    },
+    "pcr_status": {
+      "type": "string",
+      "enum": [
+        "scaffold",
+        "candidate",
+        "active",
+        "published",
+        "deprecated"
+      ]
+    },
+    "process_inclusion": {
+      "type": "string",
+      "enum": [
+        "required",
+        "conditional",
+        "optional",
+        "excluded_by_default"
+      ]
+    },
+    "source_type": {
+      "type": "string",
+      "enum": [
+        "official_guidance",
+        "literature",
+        "standard",
+        "dataset",
+        "method_factor",
+        "extension_guidance",
+        "handbook"
+      ]
+    },
+    "target_entity": {
+      "type": "string",
+      "enum": [
+        "flow",
+        "process",
+        "lifecyclemodel",
+        "dataset"
+      ]
+    },
+    "translation_status": {
+      "type": "string",
+      "enum": [
+        "not_available",
+        "scaffold",
+        "scaffold_pending_translation",
+        "draft_translation",
+        "aligned",
+        "reviewed",
+        "out_of_sync"
+      ]
+    }
+  }
+}

package/packages/pcr-core/schemas/dataset-validation-input.schema.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tiangong-lca.org/schemas/pcr/v1/dataset-validation-input.schema.json",
+  "title": "PCR Dataset Validation Input",
+  "description": "Flexible F2 foreground data package supplied to tiangong-pcr validate-dataset.",
+  "type": "object"
+}

package/packages/pcr-core/schemas/feedback-draft-output.schema.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tiangong-lca.org/schemas/pcr/v1/feedback-draft-output.schema.json",
+  "title": "TianGong PCR feedback issue draft output",
+  "type": "object",
+  "required": ["title", "body"],
+  "properties": {
+    "title": { "type": "string", "minLength": 1 },
+    "body": { "type": "string", "minLength": 1 }
+  },
+  "additionalProperties": false
+}

package/packages/pcr-core/schemas/feedback.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tiangong-lca.org/schemas/pcr/v1/feedback-intake.schema.json",
+  "title": "TianGong PCR feedback intake",
+  "type": "object",
+  "required": ["feedback_type", "summary"],
+  "properties": {
+    "feedback_type": {
+      "$ref": "https://tiangong-lca.org/schemas/pcr/v1/controlled-vocabulary.schema.json#/$defs/feedback_type"
+    },
+    "pcr_id": { "type": "string", "minLength": 1 },
+    "pcr_version": { "type": "string" },
+    "affected_section": { "type": "string" },
+    "process_id": { "type": "string" },
+    "flow_role": { "type": "string" },
+    "summary": { "type": "string", "minLength": 1 },
+    "current_rule": { "type": "string" },
+    "proposed_change": { "type": "string" },
+    "evidence_sources": { "type": "string" },
+    "model_impact": { "type": "string" },
+    "confidence": {
+      "$ref": "https://tiangong-lca.org/schemas/pcr/v1/controlled-vocabulary.schema.json#/$defs/feedback_confidence"
+    },
+    "generated_by": { "type": "string" }
+  },
+  "additionalProperties": false
+}

package/packages/pcr-core/schemas/guidance-output.schema.json

@@ -0,0 +1,97 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tiangong-lca.org/schemas/pcr/v1/guidance-output.schema.json",
+  "title": "TianGong PCR Agent Guidance",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "guidance_kind",
+    "pcr",
+    "readiness",
+    "source_structured",
+    "system_boundary",
+    "boundary_abstraction",
+    "reference_flow",
+    "measurement_rules",
+    "process_map",
+    "process_inventory",
+    "production_guidance",
+    "published_dataset_profile",
+    "allocation_rules",
+    "data_quality_rules",
+    "validation_rules",
+    "data_sources",
+    "validation_notes"
+  ],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "guidance_kind": { "const": "tiangong-pcr-agent-guidance" },
+    "pcr": { "type": "object" },
+    "readiness": {
+      "$ref": "https://tiangong-lca.org/schemas/pcr/v1/readiness.schema.json"
+    },
+    "source_structured": { "type": "string", "minLength": 1 },
+    "system_boundary": {
+      "type": "object",
+      "required": ["rules"],
+      "properties": {
+        "rules": { "$ref": "#/$defs/normativeRules" }
+      },
+      "additionalProperties": false
+    },
+    "reference_flow": { "type": "object" },
+    "boundary_abstraction": { "type": "object" },
+    "measurement_rules": { "$ref": "#/$defs/objectArray" },
+    "process_map": { "$ref": "#/$defs/objectArray" },
+    "process_inventory": { "$ref": "#/$defs/objectArray" },
+    "production_guidance": {
+      "type": "object",
+      "required": ["collection_protocols", "calculation_rules", "data_quality_requirements"],
+      "properties": {
+        "collection_protocols": { "$ref": "#/$defs/objectArray" },
+        "calculation_rules": { "$ref": "#/$defs/objectArray" },
+        "data_quality_requirements": { "$ref": "#/$defs/objectArray" }
+      },
+      "additionalProperties": false
+    },
+    "published_dataset_profile": { "type": "object" },
+    "allocation_rules": { "$ref": "#/$defs/normativeRules" },
+    "data_quality_rules": { "$ref": "#/$defs/objectArray" },
+    "validation_rules": { "$ref": "#/$defs/normativeRules" },
+    "data_sources": { "$ref": "#/$defs/objectArray" },
+    "validation_notes": {
+      "type": "array",
+      "items": { "type": "string", "minLength": 1 }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "objectArray": {
+      "type": "array",
+      "items": { "type": "object" }
+    },
+    "normativeRules": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/normativeRule" }
+    },
+    "normativeRule": {
+      "type": "object",
+      "required": ["rule_id", "applies_to", "rule", "source_ids"],
+      "properties": {
+        "rule_id": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[a-z0-9]+(?:_[a-z0-9]+)*$"
+        },
+        "applies_to": { "type": "string", "minLength": 1 },
+        "rule": { "type": "string", "minLength": 1 },
+        "source_ids": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/packages/pcr-core/schemas/model-validation-input.schema.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tiangong-lca.org/schemas/pcr/v1/model-validation-input.schema.json",
+  "title": "PCR Model Validation Input",
+  "description": "Flexible F2 input for validating process or lifecyclemodel drafts against PCR guidance.",
+  "oneOf": [
+    { "type": "object" },
+    { "type": "string" }
+  ]
+}

package/packages/pcr-core/schemas/pcr-id-aliases.schema.json

@@ -0,0 +1,120 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://tiangong-lca.org/schemas/pcr/v1/pcr-id-aliases.schema.json",
+  "title": "TianGong legacy PCR id alias registry",
+  "type": "object",
+  "required": ["schema_version", "registry_kind", "status", "aliases"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "registry_kind": { "const": "legacy-pcr-id-aliases" },
+    "status": { "const": "current" },
+    "aliases": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/alias" }
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "pcrId": {
+      "type": "string",
+      "pattern": "^pcr\\.[a-z0-9]+(?:[.-][a-z0-9]+)*$"
+    },
+    "alias": {
+      "type": "object",
+      "required": [
+        "source_pcr_id",
+        "source_pcr_path",
+        "target",
+        "reason",
+        "decision_ref"
+      ],
+      "properties": {
+        "source_pcr_id": { "$ref": "#/$defs/pcrId" },
+        "source_pcr_path": {
+          "type": "string",
+          "pattern": "^library/pcrs/[a-z0-9][a-z0-9-]*/[a-z0-9][a-z0-9-]*/[a-z0-9][a-z0-9-]*$"
+        },
+        "target": {
+          "oneOf": [
+            { "$ref": "#/$defs/classificationCoverageTarget" },
+            { "$ref": "#/$defs/canonicalPcrTarget" }
+          ]
+        },
+        "reason": {
+          "enum": ["empty_scaffold_migration", "canonical_pcr_replacement"]
+        },
+        "decision_ref": {
+          "type": "string",
+          "pattern": "^(?:docs|classifications/migrations)/[A-Za-z0-9][A-Za-z0-9._/-]*\\.(?:md|ya?ml|json)(?:#[A-Za-z0-9][A-Za-z0-9._-]*)?$"
+        }
+      },
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "target": {
+                "type": "object",
+                "properties": { "kind": { "const": "classification_coverage" } },
+                "required": ["kind"]
+              }
+            },
+            "required": ["target"]
+          },
+          "then": {
+            "properties": { "reason": { "const": "empty_scaffold_migration" } }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "target": {
+                "type": "object",
+                "properties": { "kind": { "const": "canonical_pcr" } },
+                "required": ["kind"]
+              }
+            },
+            "required": ["target"]
+          },
+          "then": {
+            "properties": { "reason": { "const": "canonical_pcr_replacement" } }
+          }
+        }
+      ]
+    },
+    "classificationCoverageTarget": {
+      "type": "object",
+      "required": [
+        "kind",
+        "classification_system",
+        "classification_version",
+        "code"
+      ],
+      "properties": {
+        "kind": { "const": "classification_coverage" },
+        "classification_system": {
+          "type": "string",
+          "pattern": "^[a-z0-9][a-z0-9_-]*$"
+        },
+        "classification_version": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
+        },
+        "code": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
+        }
+      },
+      "additionalProperties": false
+    },
+    "canonicalPcrTarget": {
+      "type": "object",
+      "required": ["kind", "pcr_id"],
+      "properties": {
+        "kind": { "const": "canonical_pcr" },
+        "pcr_id": { "$ref": "#/$defs/pcrId" }
+      },
+      "additionalProperties": false
+    }
+  }
+}