causalontology 1.0.0

data/lib/causalontology/jcs.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: false
+
+# RFC 8785 (JSON Canonicalization Scheme) serialization.
+#
+# Sorted keys (code-point order), minimal string escaping, ECMAScript-style
+# canonical numbers (1.0 -> "1", 0.7 stays "0.7", exponent "1e-7" not
+# "1e-07"). The number serialization implements the RFC 8785 rules for the
+# value ranges Causalontology uses (integers, integer-valued floats, and
+# short decimals); full ECMAScript exponent formatting for extreme
+# magnitudes is pinned at the 1.0.0 conformance freeze.
+#
+# Ruby specifics relied on here: JSON.parse keeps the integer-versus-decimal
+# source distinction ("1" -> Integer, "1.0" -> Float), and Float#to_s prints
+# the shortest round-trip decimal with the same decimal/exponent thresholds
+# as Python's repr (1e16 and 1e-4), so only the exponent spelling needs
+# normalizing ("1.0e-07" -> "1e-7").
+
+module Causalontology
+  module Jcs
+    # The two-character escapes of RFC 8785 section 3.2.2.2.
+    ESCAPES = {
+      '"'  => '\"',
+      "\\" => "\\\\",
+      "\b" => "\\b",
+      "\t" => "\\t",
+      "\n" => "\\n",
+      "\f" => "\\f",
+      "\r" => "\\r",
+    }.freeze
+
+    module_function
+
+    # A JSON string literal with minimal escaping: the seven two-character
+    # escapes, \u00xx for remaining control characters, everything else
+    # (including multibyte text) passed through as UTF-8.
+    def string(s)
+      parts = +'"'
+      s.each_char do |ch|
+        if ESCAPES.key?(ch)
+          parts << ESCAPES[ch]
+        elsif ch.ord < 0x20
+          parts << format("\\u%04x", ch.ord)
+        else
+          parts << ch
+        end
+      end
+      parts << '"'
+      parts
+    end
+
+    # A canonical JSON number: integers verbatim; integer-valued floats
+    # below 1e21 printed as integers; other floats in shortest round-trip
+    # form with the exponent normalized to ES6 style ("1e-7", "1e+21").
+    def number(n)
+      return n.to_s if n.is_a?(Integer)
+      raise ArgumentError, "NaN and Infinity are not permitted (RFC 8785)" unless n.finite?
+      return "0" if n == 0
+      return n.to_i.to_s if n == n.truncate && n.abs < 1e21
+      r = n.to_s # shortest round-trip decimal
+      if r.include?("e")
+        mant, exp = r.split("e")
+        mant = mant.sub(/\.0\z/, "") # Ruby prints "1.0e-07"; ES6 prints "1e-7"
+        sign = exp.start_with?("-") ? "-" : "+"
+        digits = exp.sub(/\A[+-]/, "").sub(/\A0+/, "")
+        digits = "0" if digits.empty?
+        r = mant + "e" + sign + digits
+      end
+      r
+    end
+
+    # The canonical serialization of a parsed JSON value (nil, true/false,
+    # Integer, Float, String, Array, or Hash with String keys).
+    def encode(value)
+      case value
+      when nil
+        "null"
+      when true
+        "true"
+      when false
+        "false"
+      when Integer, Float
+        number(value)
+      when String
+        string(value)
+      when Array
+        "[" + value.map { |v| encode(v) }.join(",") + "]"
+      when Hash
+        items = value.keys.sort_by(&:codepoints)
+        "{" + items.map { |k| string(k) + ":" + encode(value[k]) }.join(",") + "}"
+      else
+        raise TypeError, "cannot canonicalize #{value.class}"
+      end
+    end
+  end
+end

data/lib/causalontology/schema.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: false
+
+# Schema validation against spec/schema/*.schema.json.
+#
+# A deliberately small interpreter for exactly the JSON Schema keywords the
+# eight Causalontology schemas use: type, const, enum, pattern, required,
+# properties, additionalProperties, items, minItems, minLength, minimum,
+# maximum, oneOf, and local $ref (#/$defs/...). "format" is treated as an
+# annotation, as the 2020-12 draft does by default.
+
+require "json"
+require_relative "canonical"
+
+module Causalontology
+  module Schema
+    SCHEMA_FILES = {
+      "cro"        => "cro.schema.json",
+      "occurrent"  => "occurrent.schema.json",
+      "continuant" => "continuant.schema.json",
+      "realizable" => "realizable.schema.json",
+      "assertion"  => "assertion.schema.json",
+      "enrichment" => "enrichment.schema.json",
+      "retraction" => "retraction.schema.json",
+      "succession" => "succession.schema.json",
+    }.freeze
+
+    @cache = {}
+
+    class << self
+      def schema_dir
+        env = ENV["CAUSALONTOLOGY_SPEC"]
+        return File.join(env, "schema") if env && !env.empty?
+        # lib/causalontology -> lib -> ruby -> bindings -> repository root
+        File.expand_path("../../../../spec/schema", __dir__)
+      end
+
+      def load_schema(kind)
+        unless SCHEMA_FILES.key?(kind)
+          raise ArgumentError, "unknown kind: #{kind.inspect}"
+        end
+        @cache[kind] ||= JSON.parse(
+          File.read(File.join(schema_dir, SCHEMA_FILES[kind])))
+      end
+
+      # Follow local $ref chains (#/$defs/...) to the referenced subschema.
+      def resolve_ref(schema, root)
+        while schema.key?("$ref")
+          ref = schema["$ref"]
+          unless ref.start_with?("#/")
+            raise ArgumentError, "only local $ref supported: #{ref.inspect}"
+          end
+          node = root
+          ref[2..].split("/").each { |part| node = node[part] }
+          schema = node
+        end
+        schema
+      end
+
+      def type_matches?(value, t)
+        case t
+        when "object"  then value.is_a?(Hash)
+        when "array"   then value.is_a?(Array)
+        when "string"  then value.is_a?(String)
+        when "number"  then value.is_a?(Integer) || value.is_a?(Float)
+        when "boolean" then value == true || value == false
+        else
+          raise ArgumentError, "unknown schema type: #{t.inspect}"
+        end
+      end
+
+      def numeric?(value)
+        value.is_a?(Integer) || value.is_a?(Float)
+      end
+
+      def check(value, schema, root, path, errors)
+        schema = resolve_ref(schema, root)
+
+        if schema.key?("oneOf")
+          passing = 0
+          schema["oneOf"].each do |sub|
+            suberrs = []
+            check(value, sub, root, path, suberrs)
+            passing += 1 if suberrs.empty?
+          end
+          if passing != 1
+            errors << "#{path}: matches #{passing} of the oneOf branches " \
+                      "(need exactly 1)"
+          end
+          return
+        end
+
+        t = schema["type"]
+        if !t.nil? && !type_matches?(value, t)
+          errors << "#{path}: expected #{t}"
+          return
+        end
+
+        if schema.key?("const") && value != schema["const"]
+          errors << "#{path}: must equal #{schema["const"].inspect}"
+        end
+        if schema.key?("enum") && !schema["enum"].include?(value)
+          errors << "#{path}: #{value.inspect} not in enumeration"
+        end
+        if schema.key?("pattern") && value.is_a?(String)
+          unless Regexp.new(schema["pattern"]).match?(value)
+            errors << "#{path}: #{value.inspect} does not match " \
+                      "#{schema["pattern"]}"
+          end
+        end
+        if schema.key?("minLength") && value.is_a?(String)
+          if value.length < schema["minLength"]
+            errors << "#{path}: shorter than minLength"
+          end
+        end
+        if schema.key?("minimum") && numeric?(value)
+          if value < schema["minimum"]
+            errors << "#{path}: below minimum #{schema["minimum"]}"
+          end
+        end
+        if schema.key?("maximum") && numeric?(value)
+          if value > schema["maximum"]
+            errors << "#{path}: above maximum #{schema["maximum"]}"
+          end
+        end
+
+        if value.is_a?(Array)
+          if schema.key?("minItems") && value.length < schema["minItems"]
+            errors << "#{path}: fewer than #{schema["minItems"]} items"
+          end
+          if schema.key?("items")
+            value.each_with_index do |item, i|
+              check(item, schema["items"], root, "#{path}[#{i}]", errors)
+            end
+          end
+        end
+
+        if value.is_a?(Hash)
+          props = schema["properties"] || {}
+          (schema["required"] || []).each do |req|
+            unless value.key?(req)
+              errors << "#{path}: required property '#{req}' missing"
+            end
+          end
+          if schema["additionalProperties"] == false
+            value.each_key do |key|
+              unless props.key?(key)
+                errors << "#{path}: additional property '#{key}'"
+              end
+            end
+          end
+          props.each do |key, sub|
+            if value.key?(key)
+              check(value[key], sub, root, "#{path}.#{key}", errors)
+            end
+          end
+        end
+      end
+
+      # [ok, reasons] - structural validity against the kind's JSON Schema.
+      def validate_schema(obj, kind = nil)
+        kind ||= Canonical.infer_kind(obj)
+        root = load_schema(kind)
+        errors = []
+        check(obj, root, root, "$", errors)
+        [errors.empty?, errors]
+      end
+    end
+  end
+end

data/lib/causalontology/semantics.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: false
+
+# The semantic rules beyond the schemas (spec/semantics.md).
+#
+# Local rules are checked here; store-context rules (materialized acyclicity,
+# retraction lineage) live in store.rb where the context exists.
+
+require "set"
+require_relative "canonical"
+
+module Causalontology
+  module Semantics
+    # Rule 4: the fixed unit-conversion constants (average Gregorian values).
+    UNIT_SECONDS = {
+      "instant" => 0,
+      "seconds" => 1,
+      "minutes" => 60,
+      "hours"   => 3600,
+      "days"    => 86400,
+      "weeks"   => 604800,
+      "months"  => 2629746,
+      "years"   => 31556952,
+    }.freeze
+
+    # Rule 12: enrichment field-to-kind validity and entry shapes.
+    ENRICHMENT_FIELDS = {
+      "aliases"      => [["occurrent", "continuant"], "alias"],
+      "participants" => [["occurrent"],               "cnt"],
+      "subsumes"     => [["continuant"],              "cnt"],
+      "part_of"      => [["continuant"],              "cnt"],
+      "realized_in"  => [["realizable"],              "occ"],
+    }.freeze
+
+    CRO_OPTIONAL_FIELDS = ["mechanism", "temporal", "modality", "context"].freeze
+
+    # The positive modalities of the formal conflict test (rule 6).
+    POSITIVE = Set.new(["necessary", "sufficient", "contributory"]).freeze
+
+    module_function
+
+    def kind_of_id(identifier)
+      Canonical::KIND_OF_PREFIX[identifier.split(":", 2)[0]]
+    end
+
+    # [ok, reasons] - the locally checkable semantic rules.
+    def validate_semantics(obj, kind = nil)
+      kind ||= Canonical.infer_kind(obj)
+      errors = []
+
+      if kind == "cro"
+        t = obj["temporal"]
+        if !t.nil? && !t["dmin"].nil? && !t["dmax"].nil? && t["dmin"] > t["dmax"]
+          errors << "dmin must be <= dmax"
+        end
+        oid = obj["id"]
+        if oid && (obj["mechanism"] || []).include?(oid)
+          errors << "mechanism must be acyclic " \
+                    "(a Causal Relation Object may not contain itself)"
+        end
+        if oid && obj["refines"] == oid
+          errors << "refines must be acyclic"
+        end
+      end
+
+      if kind == "enrichment"
+        field = obj["field"]
+        about = obj["about"] || ""
+        entry = obj["entry"]
+        spec = ENRICHMENT_FIELDS[field]
+        if spec
+          legal_kinds, shape = spec
+          about_kind = kind_of_id(about)
+          if about_kind && !legal_kinds.include?(about_kind)
+            errors << "#{field} is not a legal field for a #{about_kind} (rule 12)"
+          end
+          if shape == "alias"
+            unless entry.is_a?(Hash) && entry.key?("lang") && entry.key?("text")
+              errors << "an aliases entry must be a language-tagged text object"
+            end
+          else
+            unless entry.is_a?(String) && entry.start_with?(shape + ":")
+              errors << "a #{field} entry must be a #{shape}: identifier"
+            end
+          end
+        end
+      end
+
+      [errors.empty?, errors]
+    end
+
+    # [partial, missing] - which optional CRO fields are unspecified.
+    def is_partial(cro)
+      missing = CRO_OPTIONAL_FIELDS.reject { |f| cro.key?(f) }
+      [!missing.empty?, missing]
+    end
+
+    # Rule 4: temporal admissibility with the fixed constants.
+    def admissible(cro, elapsed_seconds)
+      t = cro["temporal"]
+      return true if t.nil? # no window imposes no constraint
+      unit = UNIT_SECONDS.fetch(t["unit"])
+      lo = t["dmin"] * unit
+      hi = t["dmax"] * unit
+      lo <= elapsed_seconds && elapsed_seconds <= hi
+    end
+
+    def window_overlap(a, b)
+      ta = a["temporal"]
+      tb = b["temporal"]
+      return true if ta.nil? || tb.nil? # either absent counts as overlapping
+      ua = UNIT_SECONDS.fetch(ta["unit"])
+      ub = UNIT_SECONDS.fetch(tb["unit"])
+      lo_a = ta["dmin"] * ua
+      hi_a = ta["dmax"] * ua
+      lo_b = tb["dmin"] * ub
+      hi_b = tb["dmax"] * ub
+      lo_a <= hi_b && lo_b <= hi_a
+    end
+
+    def contexts_compatible(a, b)
+      ca = a["context"]
+      cb = b["context"]
+      return true if ca.nil? || ca.empty? || cb.nil? || cb.empty?
+      sa = Set.new(ca)
+      sb = Set.new(cb)
+      sa == sb || sa.subset?(sb) || sb.subset?(sa)
+    end
+
+    # Rule 6: the formal conflict test.
+    def conflicts(a, b)
+      return false if Set.new(a["causes"]) != Set.new(b["causes"])
+      return false if Set.new(a["effects"]) != Set.new(b["effects"])
+      return false unless contexts_compatible(a, b)
+      return false unless window_overlap(a, b)
+      ma = a["modality"]
+      mb = b["modality"]
+      (ma == "preventive" && POSITIVE.include?(mb)) ||
+        (mb == "preventive" && POSITIVE.include?(ma))
+    end
+
+    # Rule 3: [ok, reason] - is child a valid refinement of parent?
+    def refinement_valid(child, parent)
+      if child["refines"] != parent["id"]
+        return [false, "child does not name the parent in refines"]
+      end
+      if Set.new(child["causes"]) != Set.new(parent["causes"]) ||
+         Set.new(child["effects"]) != Set.new(parent["effects"])
+        return [false, "a refinement must keep the parent's causes and effects"]
+      end
+      added = 0
+      CRO_OPTIONAL_FIELDS.each do |field|
+        if parent.key?(field)
+          if child[field] != parent[field]
+            return [false, "a refinement may not change a field the " \
+                           "parent specified; this is a rival claim"]
+          end
+        elsif child.key?(field)
+          added += 1
+        end
+      end
+      if added == 0
+        return [false, "a refinement must add at least one unspecified field"]
+      end
+      [true, "valid refinement"]
+    end
+
+    # Rule 7: "consistent" | "inconsistent" | "indeterminate".
+    #
+    # members: a mapping from CRO identifier to CRO object for the parent's
+    # mechanism entries (the store's view of them).
+    def hierarchy_consistent(parent, members)
+      mechanism = parent["mechanism"] || []
+      return "consistent" if mechanism.empty? # nothing claimed, nothing to check
+      edges = {}
+      mechanism.each do |mid|
+        m = members[mid]
+        return "indeterminate" if m.nil? # a dangling_reference gap, not a failure
+        m["causes"].each do |c|
+          (edges[c] ||= Set.new).merge(m["effects"])
+        end
+      end
+
+      reachable = lambda do |src, dst|
+        seen = Set.new
+        stack = [src]
+        until stack.empty?
+          node = stack.pop
+          return true if node == dst
+          next if seen.include?(node)
+          seen << node
+          stack.concat((edges[node] || []).to_a)
+        end
+        false
+      end
+
+      parent["causes"].each do |c|
+        parent["effects"].each do |e|
+          return "inconsistent" unless reachable.call(c, e)
+        end
+      end
+      "consistent"
+    end
+  end
+end

data/lib/causalontology/signing.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: false
+
+# Record-level signing and verification (spec/provenance.md).
+#
+# The signature is computed over the record's canonical identity-bearing bytes
+# (the RFC 8785 form with id and signature removed - exactly the bytes that are
+# hashed for the record's identifier), so verification needs nothing but the
+# record itself. Ed25519 is deterministic (RFC 8032): re-signing the same record
+# with the same key yields the same signature, so re-submission is idempotent.
+
+require_relative "ed25519"
+require_relative "canonical"
+
+module Causalontology
+  module Signing
+    module_function
+
+    # Hex encoding of a binary string.
+    def bin_to_hex(s)
+      s.unpack1("H*")
+    end
+
+    # Binary decoding of a hex string, or nil when the text is not clean hex.
+    def hex_to_bin(hex)
+      return nil unless hex.is_a?(String)
+      return nil unless hex.length.even? && hex.match?(/\A\h*\z/)
+      [hex].pack("H*")
+    end
+
+    # [secret, "ed25519:<hex>"] from a 32-byte seed.
+    def keypair_from_seed(seed32)
+      public_key = Ed25519.secret_to_public(seed32)
+      [seed32, "ed25519:" + bin_to_hex(public_key)]
+    end
+
+    # Return the record completed with its id and Ed25519 signature.
+    def sign_record(record, secret, kind = nil)
+      kind ||= Canonical.infer_kind(record)
+      body = record.dup
+      body.delete("signature")
+      message = Canonical.canonicalize(body, kind)
+      signature = bin_to_hex(Ed25519.sign(secret, message))
+      out = body.dup
+      out["id"] = Canonical.identify(body, kind)
+      out["signature"] = signature
+      out
+    end
+
+    # The hex of the key the record must verify against: a succession is
+    # signed by the predecessor key; every other record by its source.
+    def signer_key_hex(record, kind)
+      field = kind == "succession" ? "predecessor" : "source"
+      value = record[field] || ""
+      return nil unless value.is_a?(String) && value.start_with?("ed25519:")
+      value.split(":", 2)[1]
+    end
+
+    # True iff the record's signature verifies against its own key field.
+    def verify_record(record, kind = nil)
+      kind ||= Canonical.infer_kind(record)
+      sig_hex = record["signature"]
+      key_hex = signer_key_hex(record, kind)
+      return false if sig_hex.nil? || sig_hex.empty?
+      return false if key_hex.nil? || key_hex.empty?
+      public_key = hex_to_bin(key_hex)
+      signature = hex_to_bin(sig_hex)
+      return false if public_key.nil? || signature.nil?
+      body = record.dup
+      body.delete("signature")
+      message = Canonical.canonicalize(body, kind)
+      Ed25519.verify(public_key, message, signature)
+    end
+  end
+end