rail_verdict 1.0.0

data/lib/rail_verdict/verification/policy.rb

@@ -0,0 +1,359 @@
+# frozen_string_literal: true
+
+module RailVerdict
+  module Verification
+    module Policy
+      module_function
+
+      def evaluate(configuration:, analyzer_results:, findings:, comparison: nil, baseline_meta: nil, git_context: nil)
+        analyzer_results = analyzer_results.sort_by(&:analyzer)
+        findings = findings.sort_by(&:sort_key)
+        operational_failures = []
+        required_incomplete = []
+
+        configuration.analyzers.each do |analyzer, selection|
+          next unless selection.fetch("enabled")
+
+          result = analyzer_results.find { |candidate| candidate.analyzer == analyzer }
+          if result.nil?
+            failure = { "code" => "unavailable", "analyzer" => analyzer, "message" => "required analyzer did not produce a result" }
+            operational_failures << failure
+            required_incomplete << failure if selection.fetch("required")
+          elsif result.evidence_status == "incomplete"
+            failure = {
+              "code" => result.failure.fetch("code"),
+              "analyzer" => analyzer,
+              "message" => result.failure.fetch("message")
+            }
+            operational_failures << failure
+            required_incomplete << failure if selection.fetch("required")
+          elsif selection.fetch("required") && (failure = incomplete_evidence_failure(analyzer, result))
+            operational_failures << failure
+            required_incomplete << failure
+          end
+        end
+
+        unless required_incomplete.empty?
+          return GateResult.new(
+            completion_status: "incomplete",
+            gate: "INCOMPLETE",
+            policy_status: "not_evaluated",
+            findings: summaries(findings, blocking: false),
+            analyzer_results: analyzer_results,
+            operational_failures: required_incomplete,
+            decision_reasons: [{
+              "code" => "required_evidence_incomplete",
+              "message" => "Required analyzer evidence is incomplete; policy was not evaluated."
+            }]
+          )
+        end
+
+        optional_failures = operational_failures.reject { |failure| required_incomplete.include?(failure) }
+
+        changed_findings = if git_context
+                             filter_to_changed_scope(findings, git_context)
+                           else
+                             findings
+                           end
+
+        mode = configuration.mode
+
+        if mode == "advisory" && git_context
+          scoped = changed_findings
+          gate = scoped.empty? ? "PASS" : "WARN"
+          policy_status = gate.downcase
+          reasons = []
+          reasons << if scoped.empty?
+                       if findings.empty?
+                         { "code" => "no_findings_detected", "message" => "All enabled analyzer evidence contains no findings." }
+                       else
+                         { "code" => "advisory_no_changed_findings", "message" => "No findings in changed scope; #{findings.length} findings outside changed scope are advisory." }
+                       end
+                     else
+                       { "code" => "advisory_findings_in_changed_scope", "message" => "#{scoped.length} findings in changed scope are advisory and do not block." }
+                     end
+          reasons << { "code" => "changed_scope", "message" => "Evaluated #{scoped.length} findings in changed scope (#{findings.length} total)." }
+          reasons << { "code" => "optional_evidence_unavailable", "message" => "Optional analyzer evidence was unavailable and was retained as an operational failure." } unless optional_failures.empty?
+          blocking_map = Set.new(scoped.map(&:fingerprint))
+          summaries_scoped = findings.sort_by(&:sort_key).map do |finding|
+            blocking = false
+            { "id" => finding.id, "fingerprint" => finding.fingerprint, "severity" => finding.severity, "state" => finding.state, "blocking" => blocking }
+          end
+          return GateResult.new(
+            completion_status: "complete",
+            gate: gate,
+            policy_status: policy_status,
+            findings: summaries_scoped,
+            analyzer_results: analyzer_results,
+            operational_failures: optional_failures,
+            decision_reasons: reasons
+          )
+        end
+
+        if mode == "advisory"
+          gate = findings.empty? ? "PASS" : "WARN"
+          policy_status = gate.downcase
+          reasons = []
+          reasons << if findings.empty?
+                       { "code" => "no_findings_detected", "message" => "All enabled analyzer evidence contains no findings." }
+                     else
+                       { "code" => "advisory_findings_present", "message" => "#{findings.length} findings are advisory and do not block." }
+                     end
+          reasons << { "code" => "optional_evidence_unavailable", "message" => "Optional analyzer evidence was unavailable and was retained as an operational failure." } unless optional_failures.empty?
+          return GateResult.new(
+            completion_status: "complete",
+            gate: gate,
+            policy_status: policy_status,
+            findings: summaries(findings, blocking: false),
+            analyzer_results: analyzer_results,
+            operational_failures: optional_failures,
+            decision_reasons: reasons
+          )
+        end
+
+        if mode == "no_new_debt" && comparison.nil? && !findings.empty?
+          return GateResult.new(
+            completion_status: "incomplete",
+            gate: "INCOMPLETE",
+            policy_status: "not_evaluated",
+            findings: summaries(findings, blocking: false),
+            analyzer_results: analyzer_results,
+            operational_failures: [{ "code" => "failed", "message" => "baseline required for no_new_debt policy; run `railverdict baseline create`" }],
+            decision_reasons: [{ "code" => "baseline_required", "message" => "no_new_debt requires a baseline; create one with `railverdict baseline create`" }]
+          )
+        end
+
+        if mode == "no_new_debt" && comparison.nil? && findings.empty?
+          return GateResult.new(
+            completion_status: "complete",
+            gate: "PASS",
+            policy_status: "pass",
+            findings: summaries(findings, blocking: false),
+            analyzer_results: analyzer_results,
+            operational_failures: optional_failures,
+            decision_reasons: [{ "code" => "no_findings_detected", "message" => "All enabled analyzer evidence contains no findings." }]
+          )
+        end
+
+        if mode == "no_new_debt" && comparison
+          counts = comparison.fetch("counts") rescue comparison["counts"] if comparison.is_a?(Hash)
+          counts ||= {}
+          waived_fps = Set.new((comparison.is_a?(Hash) ? (comparison["waived"] || []) : []))
+          introduced_fps = Set.new((comparison.is_a?(Hash) ? (comparison["introduced"] || []) : []))
+          changed_fps = Set.new((comparison.is_a?(Hash) ? (comparison["changed"] || []) : []))
+          moved_fps = Set.new((comparison.is_a?(Hash) ? (comparison["moved"] || []) : []))
+          regression_fps = introduced_fps | changed_fps | moved_fps
+          if git_context
+            regression_findings = changed_findings.select { |finding| regression_fps.include?(finding.fingerprint) && !waived_fps.include?(finding.fingerprint) }
+            existing_count = counts["existing"] || 0
+            gate = regression_findings.empty? ? "PASS" : "FAIL"
+            policy_status = gate.downcase
+            reasons = []
+            reasons << { "code" => "existing_debt_retained", "message" => "#{existing_count} existing findings retained from baseline." } if existing_count > 0
+            reasons << { "code" => "changed_scope", "message" => "Evaluated #{changed_findings.length} findings in changed scope (#{findings.length} total)." }
+            reasons << if regression_findings.empty?
+                         if findings.empty?
+                           { "code" => "no_findings_detected", "message" => "All enabled analyzer evidence contains no findings." }
+                         elsif changed_findings.empty?
+                           { "code" => "no_new_debt_pass_changed_scope", "message" => "No introduced regressions in changed scope." }
+                         else
+                           { "code" => "no_new_debt_pass", "message" => "No introduced regressions detected." }
+                         end
+                       else
+                         { "code" => "introduced_findings_blocking", "message" => "#{regression_findings.length} introduced findings in changed scope violate no_new_debt policy." }
+                       end
+            reasons << { "code" => "optional_evidence_unavailable", "message" => "Optional analyzer evidence was unavailable and was retained as an operational failure." } unless optional_failures.empty?
+            summaries_with_state = findings.sort_by(&:sort_key).map do |finding|
+              in_scope = changed_findings.any? { |scope_finding| scope_finding.fingerprint == finding.fingerprint }
+              blocking = in_scope && regression_fps.include?(finding.fingerprint) && !waived_fps.include?(finding.fingerprint)
+              blocking = false if finding.state == "existing"
+              blocking = false if finding.state == "waived"
+              { "id" => finding.id, "fingerprint" => finding.fingerprint, "severity" => finding.severity, "state" => finding.state, "blocking" => blocking }
+            end
+            return GateResult.new(
+              completion_status: "complete",
+              gate: gate,
+              policy_status: policy_status,
+              findings: summaries_with_state,
+              analyzer_results: analyzer_results,
+              operational_failures: optional_failures,
+              decision_reasons: reasons
+            )
+          end
+          blocking_findings = findings.select { |finding| regression_fps.include?(finding.fingerprint) && !waived_fps.include?(finding.fingerprint) }
+          existing_count = counts["existing"] || 0
+          gate = blocking_findings.empty? ? "PASS" : "FAIL"
+          policy_status = gate.downcase
+          reasons = []
+          reasons << { "code" => "existing_debt_retained", "message" => "#{existing_count} existing findings retained from baseline." } if existing_count > 0
+          reasons << if blocking_findings.empty?
+                       if findings.empty?
+                         { "code" => "no_findings_detected", "message" => "All enabled analyzer evidence contains no findings." }
+                       else
+                         { "code" => "no_new_debt_pass", "message" => "No introduced regressions detected." }
+                       end
+                     else
+                       { "code" => "introduced_findings_blocking", "message" => "#{blocking_findings.length} introduced findings violate no_new_debt policy." }
+                     end
+          reasons << { "code" => "optional_evidence_unavailable", "message" => "Optional analyzer evidence was unavailable and was retained as an operational failure." } unless optional_failures.empty?
+          summaries_with_state = findings.sort_by(&:sort_key).map do |finding|
+            blocking = regression_fps.include?(finding.fingerprint) && !waived_fps.include?(finding.fingerprint)
+            blocking = false if finding.state == "existing"
+            blocking = false if finding.state == "waived"
+            { "id" => finding.id, "fingerprint" => finding.fingerprint, "severity" => finding.severity, "state" => finding.state, "blocking" => blocking }
+          end
+          return GateResult.new(
+            completion_status: "complete",
+            gate: gate,
+            policy_status: policy_status,
+            findings: summaries_with_state,
+            analyzer_results: analyzer_results,
+            operational_failures: optional_failures,
+            decision_reasons: reasons
+          )
+        end
+
+        if git_context
+          scoped = changed_findings
+          gate = scoped.empty? ? "PASS" : "FAIL"
+          policy_status = gate.downcase
+          reasons = []
+          reasons << { "code" => "changed_scope", "message" => "Evaluated #{scoped.length} findings in changed scope (#{findings.length} total)." }
+          reasons << if scoped.empty?
+                       if findings.empty?
+                         { "code" => "no_findings_detected", "message" => "All enabled analyzer evidence contains no findings." }
+                       else
+                         { "code" => "no_findings_in_changed_scope", "message" => "No findings in changed scope." }
+                       end
+                     else
+                       { "code" => "blocking_findings_in_changed_scope", "message" => "#{scoped.length} findings in changed scope require policy FAIL." }
+                     end
+          reasons << { "code" => "optional_evidence_unavailable", "message" => "Optional analyzer evidence was unavailable and was retained as an operational failure." } unless optional_failures.empty?
+          scoped_fps = Set.new(scoped.map(&:fingerprint))
+          summaries_scoped = findings.sort_by(&:sort_key).map do |finding|
+            blocking = scoped_fps.include?(finding.fingerprint)
+            { "id" => finding.id, "fingerprint" => finding.fingerprint, "severity" => finding.severity, "state" => finding.state, "blocking" => blocking }
+          end
+          return GateResult.new(
+            completion_status: "complete",
+            gate: gate,
+            policy_status: policy_status,
+            findings: summaries_scoped,
+            analyzer_results: analyzer_results,
+            operational_failures: optional_failures,
+            decision_reasons: reasons
+          )
+        end
+
+        strict = true
+        blocking = true
+        gate = findings.empty? ? "PASS" : "FAIL"
+        policy_status = gate.downcase
+        reasons = []
+        reasons << if findings.empty?
+                     { "code" => "no_findings_detected", "message" => "All enabled analyzer evidence contains no findings." }
+                   else
+                     { "code" => "blocking_findings_present", "message" => "#{findings.length} findings require policy FAIL." }
+                   end
+        reasons << { "code" => "optional_evidence_unavailable", "message" => "Optional analyzer evidence was unavailable and was retained as an operational failure." } unless optional_failures.empty?
+
+        GateResult.new(
+          completion_status: "complete",
+          gate: gate,
+          policy_status: policy_status,
+          findings: summaries(findings, blocking: blocking),
+          analyzer_results: analyzer_results,
+          operational_failures: optional_failures,
+          decision_reasons: reasons
+        )
+      end
+
+      def incomplete_result(operational_failures:, analyzer_results: [], findings: [], code: "required_evidence_incomplete", message: "Required evidence is incomplete; policy was not evaluated.")
+        GateResult.new(
+          completion_status: "incomplete",
+          gate: "INCOMPLETE",
+          policy_status: "not_evaluated",
+          findings: summaries(findings, blocking: false),
+          analyzer_results: analyzer_results,
+          operational_failures: operational_failures,
+          decision_reasons: [{ "code" => code, "message" => message }]
+        )
+      end
+
+      def interrupted_result(analyzer_results: [], findings: [])
+        incomplete_result(
+          analyzer_results: analyzer_results,
+          findings: findings,
+          operational_failures: [{ "code" => "interrupted", "message" => "Execution was interrupted after child-process cleanup." }],
+          code: "interrupted",
+          message: "Execution was interrupted; no trustworthy gate was produced."
+        )
+      end
+
+      def summaries(findings, blocking:)
+        findings.sort_by(&:sort_key).map do |finding|
+          {
+            "id" => finding.id,
+            "fingerprint" => finding.fingerprint,
+            "severity" => finding.severity,
+            "state" => finding.state,
+            "blocking" => blocking
+          }
+        end
+      end
+      private_class_method :summaries
+
+      def incomplete_evidence_failure(analyzer, result)
+        summary = result.evidence_summary
+        return nil unless summary
+
+        if %w[minitest rspec].include?(analyzer)
+          total = summary["tests_total"]
+          if total.is_a?(Integer) && total == 0
+            return { "code" => "incomplete_evidence", "analyzer" => analyzer, "message" => "#{analyzer} reported zero tests" }
+          end
+        end
+
+        if analyzer == "simplecov"
+          fresh = summary["stale"]
+          if fresh == true || fresh == "true"
+            return { "code" => "incomplete_evidence", "analyzer" => analyzer, "message" => "SimpleCov coverage is stale" }
+          end
+        end
+
+        nil
+      end
+      private_class_method :incomplete_evidence_failure
+
+      def filter_to_changed_scope(findings, git_context)
+        changed_paths = Set.new(git_context.changed_files.map { |file| file.path }.compact)
+        changed_line_set = git_context.changed_line_set
+
+        findings.select do |finding|
+          path = finding.location.fetch("path")
+          next false unless changed_paths.include?(path)
+
+          if finding.category == "test"
+            lines = changed_line_set[path]
+            if lines.nil? || lines.empty?
+              next true
+            end
+            line = finding.location["start_line"]
+            next true if line.nil?
+            next true if lines.include?(line.to_i)
+            next true
+          end
+
+          lines = changed_line_set[path]
+          next true if lines.nil? || lines.empty?
+
+          line = finding.location["start_line"]
+          next true if line.nil?
+
+          lines.include?(line.to_i)
+        end
+      end
+      private_class_method :filter_to_changed_scope
+    end
+  end
+end

data/lib/rail_verdict/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RailVerdict
+  VERSION = "1.0.0"
+end

data/lib/rail_verdict/waiver.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+module RailVerdict
+  class Waiver
+    SCHEMA_VERSION = "1.0"
+
+    class IncompatibleError < RailVerdict::Error; end
+
+    attr_reader :hash
+
+    def initialize(hash)
+      @hash = hash.freeze
+      freeze
+    end
+
+    def fingerprint
+      @hash.fetch("fingerprint")
+    end
+
+    def to_h
+      @hash
+    end
+
+    def self.valid_fingerprint?(value)
+      value.is_a?(String) && value.match?(Fingerprint::FINGERPRINT_PATTERN)
+    end
+
+    def self.active?(waiver, clock: Time.now.utc)
+      hash = waiver.is_a?(Hash) ? waiver : waiver.to_h
+      created_at = parse_time(hash["created_at"] || hash[:created_at])
+      expires_at = parse_time(hash["expires_at"] || hash[:expires_at])
+      return false unless created_at && expires_at
+
+      clock >= created_at && clock < expires_at
+    end
+
+    def self.validate_hash(hash)
+      errors = SchemaValidator.validate_waiver(hash)
+      unless errors.empty?
+        raise IncompatibleError, "waiver invalid: #{errors.join('; ')}"
+      end
+      created_at = parse_time(hash["created_at"])
+      expires_at = parse_time(hash["expires_at"])
+      raise IncompatibleError, "waiver expires_at must be after created_at" unless created_at && expires_at && expires_at > created_at
+      raise IncompatibleError, "waiver timestamps must be UTC (Z)" unless utc_string?(hash["created_at"]) && utc_string?(hash["expires_at"])
+
+      hash
+    end
+
+    def self.parse_time(value)
+      return nil if value.nil?
+
+      Time.iso8601(value.to_s).utc
+    rescue ArgumentError
+      nil
+    end
+    private_class_method :parse_time
+
+    def self.utc_string?(value)
+      value.to_s.end_with?("Z")
+    end
+    private_class_method :utc_string?
+  end
+end

data/lib/rail_verdict/waiver_store.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+require "json"
+require "pathname"
+
+module RailVerdict
+  class WaiverStore
+    DEFAULT_FILENAME = ".railverdict-waivers.json"
+
+    def self.default_path(repository_root)
+      File.join(File.realpath(repository_root), DEFAULT_FILENAME)
+    end
+
+    def self.resolve_path(repository_root:, configuration:, waiver_override: nil)
+      root = File.realpath(repository_root)
+      if waiver_override && !waiver_override.to_s.strip.empty?
+        path = waiver_override.to_s
+        return Pathname.new(path).absolute? ? path : File.expand_path(path, root)
+      end
+      if configuration.respond_to?(:waivers_path) && configuration.waivers_path
+        configured = configuration.waivers_path.to_s
+        return Pathname.new(configured).absolute? ? configured : File.expand_path(configured, root)
+      end
+      File.join(root, DEFAULT_FILENAME)
+    end
+
+    def self.read(path)
+      unless File.file?(path)
+        raise Waiver::IncompatibleError, "waiver file not found at #{path}"
+      end
+      raw = File.binread(path)
+      begin
+        data = JSON.parse(raw)
+      rescue JSON::ParserError => error
+        raise Waiver::IncompatibleError, "waiver file at #{path} is corrupted: #{error.message}; fix the file or remove the waiver"
+      end
+      errors = SchemaValidator.validate_waivers(data)
+      unless errors.empty?
+        raise Waiver::IncompatibleError, "waiver file at #{path} is incompatible: #{errors.join('; ')}; fix the file or remove the waiver"
+      end
+      seen = {}
+      data.fetch("waivers").each do |waiver|
+        fingerprint = waiver.fetch("fingerprint")
+        if seen.key?(fingerprint)
+          raise Waiver::IncompatibleError, "waiver file at #{path} contains duplicate fingerprint #{fingerprint}"
+        end
+        seen[fingerprint] = true
+        Waiver.validate_hash(waiver)
+      end
+      data["waivers"].sort_by { |waiver| waiver.fetch("fingerprint") }.map { |hash| Waiver.new(hash) }
+    end
+
+    def self.read_optional(path)
+      return [] unless File.file?(path)
+
+      read(path)
+    end
+  end
+end

data/lib/rail_verdict.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "rail_verdict/version"
+require_relative "rail_verdict/errors"
+require_relative "rail_verdict/schema_validator"
+require_relative "rail_verdict/strict_yaml"
+require_relative "rail_verdict/configuration"
+require_relative "rail_verdict/run_context"
+require_relative "rail_verdict/process_runner"
+require_relative "rail_verdict/fingerprint"
+require_relative "rail_verdict/contracts/finding"
+require_relative "rail_verdict/contracts/analyzer_result"
+require_relative "rail_verdict/analyzers/_shared"
+require_relative "rail_verdict/analyzers/rubocop"
+require_relative "rail_verdict/analyzers/minitest"
+require_relative "rail_verdict/analyzers/rspec"
+require_relative "rail_verdict/analyzers/simplecov"
+require_relative "rail_verdict/analyzers/bundler_audit"
+require_relative "rail_verdict/coverage/changed_line_evaluator"
+require_relative "rail_verdict/check"
+require_relative "rail_verdict/init"
+require_relative "rail_verdict/doctor"
+require_relative "rail_verdict/findings_command"
+require_relative "rail_verdict/baseline"
+require_relative "rail_verdict/comparison"
+require_relative "rail_verdict/waiver"
+require_relative "rail_verdict/waiver_store"
+require_relative "rail_verdict/git/errors"
+require_relative "rail_verdict/git/command"
+require_relative "rail_verdict/git/diff_parser"
+require_relative "rail_verdict/git/context"
+require_relative "rail_verdict/contracts/gate_result"
+require_relative "rail_verdict/rails_context"
+require_relative "rail_verdict/verification/policy"
+require_relative "rail_verdict/reporters/console"
+require_relative "rail_verdict/reporters/json_reporter"
+require_relative "rail_verdict/reporters/sarif"
+require_relative "rail_verdict/reporters/github_annotations"
+require_relative "rail_verdict/cli"
+require_relative "rail_verdict/intelligence"
+require_relative "rail_verdict/intelligence/source_reader"
+require_relative "rail_verdict/intelligence/manifest"
+require_relative "rail_verdict/intelligence/secret_detector"
+require_relative "rail_verdict/intelligence/redactor"
+require_relative "rail_verdict/intelligence/prompt"
+require_relative "rail_verdict/intelligence/budget"
+require_relative "rail_verdict/intelligence/cache"
+require_relative "rail_verdict/intelligence/context_builder"
+require_relative "rail_verdict/intelligence/orchestrator"
+require_relative "rail_verdict/intelligence/provider"
+require_relative "rail_verdict/intelligence/providers/fake_provider"
+require_relative "rail_verdict/intelligence/providers/openai_compat"
+require_relative "rail_verdict/repair/constraints"
+require_relative "rail_verdict/repair/verification_plan"
+require_relative "rail_verdict/repair/boundary"
+require_relative "rail_verdict/repair/diff_context"
+require_relative "rail_verdict/repair/prompt_renderer"
+require_relative "rail_verdict/repair/packet"
+require_relative "rail_verdict/repair/context_assembler"
+require_relative "rail_verdict/repair/verifier"
+require_relative "rail_verdict/repair/command"
+
+module RailVerdict
+end

data/schemas/ai-analysis-v1.schema.json

@@ -0,0 +1,54 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://railverdict.dev/schemas/ai-analysis/v1.schema.json",
+  "title": "RailVerdict AIAnalysis v1",
+  "description": "Advisory, bounded AI explanation for a deterministic finding. Never gate authority.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "finding_id",
+    "fingerprint",
+    "assessment",
+    "confidence",
+    "summary",
+    "provenance"
+  ],
+  "properties": {
+    "schema_version": { "const": "1.0" },
+    "finding_id": { "type": "string", "minLength": 1, "maxLength": 256 },
+    "fingerprint": { "type": "string", "pattern": "^sha256:[0-9a-f]{64}$" },
+    "assessment": { "enum": ["likely_cause", "needs_investigation", "uncertain"] },
+    "confidence": { "enum": ["low", "medium", "high"] },
+    "summary": { "type": "string", "minLength": 1, "maxLength": 2048 },
+    "root_cause": { "type": "string", "minLength": 1, "maxLength": 2048 },
+    "suggested_fix": { "type": "string", "minLength": 1, "maxLength": 2048 },
+    "recommended_tests": {
+      "type": "array",
+      "maxItems": 20,
+      "items": { "type": "string", "minLength": 1, "maxLength": 1024 }
+    },
+    "evidence_notes": {
+      "type": "array",
+      "maxItems": 10,
+      "items": { "type": "string", "minLength": 1, "maxLength": 1024 }
+    },
+    "provenance": { "$ref": "#/$defs/provenance" }
+  },
+  "additionalProperties": false,
+  "unevaluatedProperties": false,
+  "$defs": {
+    "provenance": {
+      "type": "object",
+      "required": ["provider", "model", "prompt_version", "created_at"],
+      "properties": {
+        "provider": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "model": { "type": "string", "minLength": 1, "maxLength": 128 },
+        "prompt_version": { "type": "string", "minLength": 1, "maxLength": 64 },
+        "created_at": { "type": "string", "format": "date-time" },
+        "schema_version": { "type": "string", "const": "1.0" }
+      },
+      "additionalProperties": false,
+      "unevaluatedProperties": false
+    }
+  }
+}