Add scoreCalculations provenance object (W3C PROV-style) for deterministic, auditable risk scores

[github-actions]

Motivation

RDX already carries method definitions and inputFactors, but reproducible verification of computed AFR/impact/risk values is difficult without a machine-readable calculation provenance record. For audits, regulatory compliance and CI-based validation, consumers must be able to re-run the exact scoring calculation and verify it produced the published score. Adopting a compact scoreCalculation object (inspired by W3C PROV) will make computations auditable and enable deterministic round-trip verification.

Proposed change

1. Schema additions

• Add optional array scoreCalculations[] under riskSet.

• Each scoreCalculation object SHOULD include:

  • id (string)
  • targetRef (string) — the id of the object whose score is calculated (attackFeasibilityRating.id, impactRating.id, riskValue.id)
  • methodRef (string) — methodId used
  • expression (string) — either a human-readable formula or a reference to a method's canonical expression (e.g., method:rdx-afr-v1#formula). Expression may use a restricted DSL (e.g., jsonata/mathjs) or a URI pointing to a canonical spec.
  • inputs (array of { "name": "baseAFR", "ref": "attackFeasibilityRating-123.inputFactors[0]", "value": 0.7 }) — concrete input values used for the computation
  • computedValue (number|string) — the recorded result
  • computedBy (string) — tool name + version
  • computedAt (date-time)
  • inputsHash (string) — hex of canonicalized inputs (e.g., SHA-256 over a canonical JSON representation)
  • resultHash (string) — optional hash of computedValue + inputsHash
  • provBundle (optional) — lightweight W3C PROV-style JSON snippet linking activities/agents/entities (not required to be full PROV-XML)

2. Deterministic canonicalization

• Define in methodology/Methodology.md the canonical JSON serialization rules used for inputsHash (e.g., RFC8785 JSON canonicalization, field ordering) and the hash algorithm (recommend SHA-256 or SHA-512).

3. Tooling & tests

• Provide a small reference implementation (tools/score_recompute.py) that re-computes scoreCalculations from inputs and expression, recomputes inputsHash, verifies the computedValue and resultHash.

4. Examples

• Add examples/rdx-score-provenance-example.json with at least one attackFeasibilityRating and corresponding scoreCalculation demonstrating a deterministic verification.

5. New requirement ID: RDX-116 (new requirement): "RDX documents SHOULD include an optional scoreCalculations provenance block for each computed rating that records formula, inputs, authoring tool, timestamp and canonicalized hashes for reproducibility and audit." Add to REQUIREMENTS.md.

References

• W3C PROV Overview and data model inspiration. https://www.w3.org/TR/prov-overview/
• NIST discussions on traceability and provenance (NIST IR 8536 drafts). https://nvlpubs.nist.gov/
• RFC8785 JSON Canonicalization (for deterministic hashing). https://www.rfc-editor.org/rfc/rfc8785.html

Acceptance criteria

• Schema: spec/json/rdx.schema.json and corresponding XSD extended to accept scoreCalculations[] and its fields.
• Example: examples/rdx-score-provenance-example.json is validated and a provided tool tools/score_recompute.py recomputes and verifies inputsHash and computedValue successfully for the example.
• Documentation: methodology/Methodology.md updated with canonicalization rules, recommended hash algorithms, and example recomputation flow.
• REQUIREMENTS.md: add RDX-116 and map to RDX-004 (data governance) and RDX-021/023/025 (rating objects) in the rationale.
• CI: add a unit test that runs the recompute tool against the example and fails if recomputed hashes or values differ.

---

Generated by tools/ai_idea_scout.py via the AI Idea Scout workflow.
Review the proposal, refine the title/body/labels, and close if not desired.