causalontology 2.0.0

data/lib/causalontology/canonical.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: false
+
+# Canonicalization and content-addressed identity.
+#
+# Implements the identity procedure of spec/identity.md:
+#   1. take the object as JSON,
+#   2. keep only the identity-bearing fields for its kind (with "type" injected),
+#   3. serialize with the JSON Canonicalization Scheme (RFC 8785),
+#   4. hash with SHA-256,
+#   5. identifier = scheme + ":" + lowercase hex digest.
+
+require "digest"
+require_relative "jcs"
+
+module Causalontology
+  module Canonical
+    # The identity-bearing fields of each of the seventeen kinds. "type" is
+    # always injected, so it is not listed here. Order does not matter (JCS
+    # sorts keys).
+    IDENTITY_FIELDS = {
+      # ---- type tier ----
+      "occurrent"  => ["label", "category", "stratum"],
+      "causal_relation_object" => ["causes", "effects", "mechanism", "temporal",
+                                   "modality", "context", "refines", "skips"],
+      "continuant" => ["label", "category"],
+      "realizable" => ["kind", "bearer", "label"],
+      "stratum"    => ["label", "scheme", "ordinal", "unit", "governs"],
+      "bridge"     => ["coarse", "fine", "relation"],
+      "port"       => ["bearer", "label", "direction", "accepts", "realizable"],
+      "conduit"    => ["label", "from", "to", "carries", "transform"],
+      "quality"    => ["label", "datatype", "unit", "stratum"],
+      # ---- token tier ----
+      "token_individual"   => ["instantiates", "designator", "part_of"],
+      "token_occurrence"   => ["instantiates", "interval", "participants",
+                               "locus", "observer"],
+      "state_assertion"    => ["subject", "quality", "value", "interval"],
+      "token_causal_claim" => ["causes", "effects", "covering_law",
+                               "actual_delay", "counterfactual"],
+      # ---- provenance tier ----
+      "assertion"  => ["about", "source", "evidence_type", "evidence", "strength",
+                       "confidence", "timestamp", "evidenced_by"],
+      "enrichment" => ["about", "field", "entry", "source", "timestamp"],
+      "retraction" => ["retracts", "source", "timestamp"],
+      "succession" => ["predecessor", "successor", "timestamp"],
+    }.freeze
+
+    # Whole-word re-mint (P7): the scheme IS the type value for every kind.
+    PREFIX = IDENTITY_FIELDS.keys.each_with_object({}) { |k, h| h[k] = k }.freeze
+    KIND_OF_PREFIX = PREFIX.invert.freeze
+
+    module_function
+
+    # Infer an object's kind from its type field, id prefix, or shape.
+    def infer_kind(obj)
+      return obj["type"] if obj.key?("type")
+      if obj.key?("id") && obj["id"].is_a?(String) && obj["id"].include?(":")
+        pre = obj["id"].split(":", 2)[0]
+        return KIND_OF_PREFIX[pre] if KIND_OF_PREFIX.key?(pre)
+      end
+      return "bridge" if obj.key?("coarse") && obj.key?("fine")
+      return "causal_relation_object" if obj.key?("causes") && obj.key?("effects")
+      return "retraction" if obj.key?("retracts")
+      return "succession" if obj.key?("predecessor") && obj.key?("successor")
+      return "enrichment" if obj.key?("field") && obj.key?("entry")
+      return "assertion" if obj.key?("evidence_type") ||
+                            (obj.key?("about") && obj.key?("confidence"))
+      return "realizable" if obj.key?("kind") && obj.key?("bearer")
+      raise ArgumentError,
+            "cannot infer kind (occurrents and continuants share a shape); " \
+            "pass kind explicitly"
+    end
+
+    # The identity-bearing subset of an object, with type always present.
+    # Returns [kind, subset].
+    def identity_bearing(obj, kind = nil)
+      kind ||= infer_kind(obj)
+      unless IDENTITY_FIELDS.key?(kind)
+        raise ArgumentError, "unknown kind: #{kind.inspect}"
+      end
+      out = { "type" => kind }
+      IDENTITY_FIELDS[kind].each do |field|
+        out[field] = obj[field] if obj.key?(field)
+      end
+      [kind, out]
+    end
+
+    # The RFC 8785 identity-bearing bytes of an object (a UTF-8 string).
+    def canonicalize(obj, kind = nil)
+      _, ib = identity_bearing(obj, kind)
+      Jcs.encode(ib).encode(Encoding::UTF_8)
+    end
+
+    # The content-addressed identifier: scheme + ":" + SHA-256 hex.
+    def identify(obj, kind = nil)
+      kind, ib = identity_bearing(obj, kind)
+      digest = Digest::SHA256.hexdigest(Jcs.encode(ib).encode(Encoding::UTF_8))
+      PREFIX[kind] + ":" + digest
+    end
+  end
+end

data/lib/causalontology/ed25519.rb

@@ -0,0 +1,158 @@
+# frozen_string_literal: false
+
+# Ed25519 digital signatures (RFC 8032), pure Ruby, standard library only.
+#
+# Slow but correct: intended for the conformance suite and for small tools.
+# Production stores should use an optimized library; the signatures are
+# byte-compatible either way (Ed25519 is deterministic, RFC 8032).
+#
+# Ruby's native bignums make this a direct port of the Python reference:
+# Integer#pow(exp, mod) is Python's three-argument pow, and Ruby's % on a
+# positive modulus is floored (always non-negative), exactly like Python's.
+# All byte strings handled here are forced to ASCII-8BIT (binary), so
+# byteslice/reverse operate on bytes, never on multibyte characters.
+
+require "digest"
+
+module Causalontology
+  module Ed25519
+    P = 2**255 - 19
+    Q = 2**252 + 27742317777372353535851937790883648493
+
+    module_function
+
+    def sha512(s)
+      Digest::SHA512.digest(s)
+    end
+
+    def modp_inv(x)
+      x.pow(P - 2, P)
+    end
+
+    # A 32-byte little-endian string for a non-negative integer below 2**256.
+    def int_to_le32(n)
+      hex = n.to_s(16).rjust(64, "0")
+      [hex].pack("H*").reverse
+    end
+
+    # The non-negative integer encoded by a little-endian byte string.
+    def le_to_int(s)
+      s.dup.force_encoding(Encoding::BINARY).reverse.unpack1("H*").to_i(16)
+    end
+
+    # The curve constant d = -121665 / 121666 (mod p).
+    CURVE_D = -121665 * modp_inv(121666) % P
+    # A square root of -1 (mod p), used in point decompression.
+    SQRT_M1 = 2.pow((P - 1) / 4, P)
+
+    # Points are [x, y, z, t] in extended homogeneous coordinates.
+    def point_add(pt, qt)
+      a = (pt[1] - pt[0]) * (qt[1] - qt[0]) % P
+      b = (pt[1] + pt[0]) * (qt[1] + qt[0]) % P
+      c = 2 * pt[3] * qt[3] * CURVE_D % P
+      d = 2 * pt[2] * qt[2] % P
+      e = b - a
+      f = d - c
+      g = d + c
+      h = b + a
+      [e * f % P, g * h % P, f * g % P, e * h % P]
+    end
+
+    def point_mul(s, pt)
+      q = [0, 1, 1, 0] # the neutral element
+      while s > 0
+        q = point_add(q, pt) if s & 1 == 1
+        pt = point_add(pt, pt)
+        s >>= 1
+      end
+      q
+    end
+
+    def point_equal(pt, qt)
+      return false if (pt[0] * qt[2] - qt[0] * pt[2]) % P != 0
+      return false if (pt[1] * qt[2] - qt[1] * pt[2]) % P != 0
+      true
+    end
+
+    def recover_x(y, sign)
+      return nil if y >= P
+      x2 = (y * y - 1) * modp_inv(CURVE_D * y * y + 1) % P
+      return (sign == 1 ? nil : 0) if x2 == 0
+      x = x2.pow((P + 3) / 8, P)
+      x = x * SQRT_M1 % P if (x * x - x2) % P != 0
+      return nil if (x * x - x2) % P != 0
+      x = P - x if (x & 1) != sign
+      x
+    end
+
+    # The base point G.
+    BASE_Y = 4 * modp_inv(5) % P
+    BASE_X = recover_x(BASE_Y, 0)
+    BASE_POINT = [BASE_X, BASE_Y, 1, BASE_X * BASE_Y % P].freeze
+
+    def point_compress(pt)
+      zinv = modp_inv(pt[2])
+      x = pt[0] * zinv % P
+      y = pt[1] * zinv % P
+      int_to_le32(y | ((x & 1) << 255))
+    end
+
+    def point_decompress(s)
+      return nil if s.bytesize != 32
+      y = le_to_int(s)
+      sign = y >> 255
+      y &= (1 << 255) - 1
+      x = recover_x(y, sign)
+      return nil if x.nil?
+      [x, y, 1, x * y % P]
+    end
+
+    def secret_expand(secret)
+      raise ArgumentError, "secret key must be 32 bytes" if secret.bytesize != 32
+      h = sha512(secret)
+      a = le_to_int(h.byteslice(0, 32))
+      a &= (1 << 254) - 8
+      a |= (1 << 254)
+      [a, h.byteslice(32, 32)]
+    end
+
+    def sha512_modq(s)
+      le_to_int(sha512(s)) % Q
+    end
+
+    # The 32-byte public key for a 32-byte secret key.
+    def secret_to_public(secret)
+      a, _prefix = secret_expand(secret)
+      point_compress(point_mul(a, BASE_POINT))
+    end
+
+    # The 64-byte Ed25519 signature of msg under the 32-byte secret key.
+    def sign(secret, msg)
+      msg = msg.dup.force_encoding(Encoding::BINARY)
+      a, prefix = secret_expand(secret)
+      public_key = point_compress(point_mul(a, BASE_POINT))
+      r = sha512_modq(prefix + msg)
+      rs = point_compress(point_mul(r, BASE_POINT))
+      h = sha512_modq(rs + public_key + msg)
+      s = (r + h * a) % Q
+      rs + int_to_le32(s)
+    end
+
+    # True iff signature is a valid Ed25519 signature of msg under public.
+    def verify(public_key, msg, signature)
+      msg = msg.dup.force_encoding(Encoding::BINARY)
+      return false if public_key.bytesize != 32 || signature.bytesize != 64
+      a_point = point_decompress(public_key)
+      return false if a_point.nil?
+      rs = signature.byteslice(0, 32)
+      r_point = point_decompress(rs)
+      return false if r_point.nil?
+      s = le_to_int(signature.byteslice(32, 32))
+      return false if s >= Q
+      h = sha512_modq(rs + public_key + msg)
+      sb = point_mul(s, BASE_POINT)
+      ha = point_mul(h, a_point)
+      point_equal(sb, point_add(r_point, ha))
+    end
+  end
+end

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,204 @@
+# frozen_string_literal: false
+
+# Schema validation against spec/schema/*.schema.json.
+#
+# A deliberately small interpreter for exactly the JSON Schema keywords the
+# seventeen Causalontology schemas use: type, const, enum, pattern, required,
+# properties, additionalProperties, items, minItems, minLength, minimum,
+# maximum, oneOf, local $ref (#/$defs/...), and cross-file $ref to a sibling
+# schema (https://causalontology.org/schema/<file>.schema.json#/...). "format"
+# is treated as an annotation, as the 2020-12 draft does by default.
+
+require "json"
+require_relative "canonical"
+
+module Causalontology
+  module Schema
+    # kind -> schema file. Three token kinds keep their original 1.0.0-reserved
+    # file names (individual/token/state); the id scheme is the whole word.
+    SCHEMA_FILES = {
+      "occurrent"  => "occurrent.schema.json",
+      "causal_relation_object" => "causal_relation_object.schema.json",
+      "continuant" => "continuant.schema.json",
+      "realizable" => "realizable.schema.json",
+      "stratum"    => "stratum.schema.json",
+      "bridge"     => "bridge.schema.json",
+      "port"       => "port.schema.json",
+      "conduit"    => "conduit.schema.json",
+      "quality"    => "quality.schema.json",
+      "token_individual"   => "individual.schema.json",
+      "token_occurrence"   => "token.schema.json",
+      "state_assertion"    => "state.schema.json",
+      "token_causal_claim" => "token_causal_claim.schema.json",
+      "assertion"  => "assertion.schema.json",
+      "enrichment" => "enrichment.schema.json",
+      "retraction" => "retraction.schema.json",
+      "succession" => "succession.schema.json",
+    }.freeze
+
+    BASE = "https://causalontology.org/schema/"
+
+    @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
+
+      # Load and cache a schema document by its file name.
+      def load_file(filename)
+        @cache[filename] ||= JSON.parse(
+          File.read(File.join(schema_dir, filename)))
+      end
+
+      def load_schema(kind)
+        unless SCHEMA_FILES.key?(kind)
+          raise ArgumentError, "unknown kind: #{kind.inspect}"
+        end
+        load_file(SCHEMA_FILES[kind])
+      end
+
+      # Navigate a JSON pointer (slash-separated) within a document.
+      def navigate(doc, pointer)
+        node = doc
+        pointer.split("/").each do |part|
+          next if part == ""
+          node = node[part]
+        end
+        node
+      end
+
+      # Resolve local and cross-file $refs to a concrete schema node plus the
+      # root document it lives in. Returns [schema, root].
+      def resolve_ref(schema, root)
+        while schema.is_a?(Hash) && schema.key?("$ref")
+          ref = schema["$ref"]
+          if ref.start_with?("#/")
+            schema = navigate(root, ref[2..])
+          elsif ref.start_with?(BASE)
+            rest = ref[BASE.length..]
+            filename, pointer = rest.split("#/", 2)
+            root = load_file(filename)
+            schema = pointer ? navigate(root, pointer) : root
+          else
+            raise ArgumentError, "unsupported $ref: #{ref.inspect}"
+          end
+        end
+        [schema, root]
+      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 "integer" then value.is_a?(Integer)
+        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, root = 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