unidpp 0.1.0

data/lib/unidpp/manifest.rb

@@ -0,0 +1,328 @@
+# frozen_string_literal: true
+
+module Unidpp
+  # Subject capability classes (I8: twin testimonial by default, sensorial
+  # by exception). A profile's requirements must be satisfiable by the
+  # class its subjects belong to — demanding live freshness from an S0
+  # product is an unsatisfiable profile.
+  #
+  #   S0 silent          testimony-only (no connectivity, no keys)
+  #   S1 passive-auth    NFC chip / PUF / IEC 61406 identity link
+  #   S2 logged-contact  dumps on physical read, no comms
+  #   S3 connected       full edge segments
+  module CapabilityClass
+    ORDER = %w[S0 S1 S2 S3].freeze
+
+    module_function
+
+    # @param required [String] profile's minimum required class
+    # @param actual [String] the subject's capability class
+    # @return [Boolean] whether +actual+ meets or exceeds +required+
+    def satisfies?(required, actual)
+      ORDER.index(actual) >= ORDER.index(required)
+    end
+  end
+
+  # Applicability axis values of a profile: composition is three-axial —
+  # jurisdiction x sector x characteristic (I10). Characteristic profiles
+  # attach by predicate on twin facts (age, material content, heritage
+  # status, market status) rather than by law-of-place or industry.
+  class ProfileAxes < Lutaml::Model::Serializable
+    attribute :jurisdictions, :string, collection: true, default: -> { [] }
+    attribute :sectors, :string, collection: true, default: -> { [] }
+    attribute :characteristics, :string, collection: true, default: -> { [] }
+
+    json do
+      map "jurisdictions", to: :jurisdictions, render_nil: false
+      map "sectors", to: :sectors, render_nil: false
+      map "characteristics", to: :characteristics, render_nil: false
+    end
+
+    yaml do
+      map "jurisdictions", to: :jurisdictions, render_nil: false
+      map "sectors", to: :sectors, render_nil: false
+      map "characteristics", to: :characteristics, render_nil: false
+    end
+
+    def empty?
+      jurisdictions.empty? && sectors.empty? && characteristics.empty?
+    end
+  end
+
+  # One predicate of a profile's trigger (I10 / I12). Predicates are
+  # evaluated against twin facts by the subject's custodian — locally,
+  # without enumeration. Time predicates are clock-fired: an object
+  # becoming >100 years old is an applicability event no human declares.
+  class TriggerPredicate < Lutaml::Model::Serializable
+    OPERATORS = %w[eq neq gt gte lt lte contains exists before after].freeze
+    # Fact-path suffixes that make a predicate time-derived (clock-fired).
+    TIME_SUBJECT_SUFFIXES = %w[_at _date _years _age].freeze
+
+    attribute :subject, :string          # fact path, e.g. "object.age_years"
+    attribute :operator, :string, values: OPERATORS
+    attribute :value, :string
+    attribute :cites, :string            # clause-level provenance URN
+
+    json do
+      map "subject", to: :subject
+      map "operator", to: :operator
+      map "value", to: :value, render_nil: false
+      map "cites", to: :cites, render_nil: false
+    end
+
+    yaml do
+      map "subject", to: :subject
+      map "operator", to: :operator
+      map "value", to: :value, render_nil: false
+      map "cites", to: :cites, render_nil: false
+    end
+
+    # @return [Boolean] whether this predicate is time-derived and can
+    #   fire on the passage of time alone
+    def time_fired?
+      time_operator? ||
+        TIME_SUBJECT_SUFFIXES.any? { |suffix| subject.to_s.end_with?(suffix) }
+    end
+
+    # Evaluates the predicate against a facts document (a Hash with
+    # dotted-path-resolvable keys, e.g. {"object" => {"age_years" => 120}}).
+    #
+    # @param facts [Hash]
+    # @return [Boolean]
+    def matches?(facts)
+      actual = TriggerPredicate.resolve_path(facts, subject)
+      return operator == "exists" ? !actual.nil? : false if actual.nil?
+
+      case operator
+      when "exists" then true
+      when "eq"     then compare_eq(actual)
+      when "neq"    then !compare_eq(actual)
+      when "contains" then contains_match?(actual)
+      when "gt", "gte", "lt", "lte" then numeric_compare(actual)
+      when "before", "after" then time_compare(actual)
+      else false
+      end
+    end
+
+    # @return [String] human-readable summary, for drift/conformance
+    #   reports
+    def description
+      "#{subject} #{operator} #{value}"
+    end
+
+    def self.resolve_path(facts, path)
+      path.to_s.split(".").reduce(facts) do |node, key|
+        break nil unless node.is_a?(Hash) || node.is_a?(Array)
+
+        node.is_a?(Array) ? node.map { |e| e[key] if e.is_a?(Hash) }.compact : node[key]
+      end
+    end
+
+    private
+
+    def time_operator?
+      %w[before after].include?(operator)
+    end
+
+    def compare_eq(actual)
+      if numeric?(actual) && numeric?(value)
+        actual.to_f == value.to_f
+      else
+        actual.to_s == value.to_s
+      end
+    end
+
+    # contains-match against array or scalar facts (distinct from the
+    # lutaml-generated +contains?+ enum predicate on the operator).
+    def contains_match?(actual)
+      if actual.is_a?(Array)
+        actual.map(&:to_s).include?(value.to_s)
+      else
+        actual.to_s.include?(value.to_s)
+      end
+    end
+
+    def numeric_compare(actual)
+      return false unless numeric?(actual) && numeric?(value)
+
+      a = actual.to_f
+      v = value.to_f
+      case operator
+      when "gt"  then a > v
+      when "gte" then a >= v
+      when "lt"  then a < v
+      when "lte" then a <= v
+      end
+    end
+
+    def time_compare(actual)
+      a = to_time(actual)
+      v = to_time(value)
+      return false if a.nil? || v.nil?
+
+      operator == "before" ? a < v : a > v
+    end
+
+    def numeric?(v)
+      Float(v.to_s) != nil
+    rescue ArgumentError, TypeError
+      false
+    end
+
+    def to_time(v)
+      return v if v.is_a?(Time) || v.is_a?(DateTime) || v.is_a?(Date)
+
+      DateTime.parse(v.to_s)
+    rescue ArgumentError, TypeError
+      nil
+    end
+  end
+
+  # Binding of a cryptographic suite to a profile (I9/I10: jurisdictional
+  # crypto suites are part of the profile, not the platform). The same
+  # payload carries multiple signatures; verifiers check only what their
+  # profile-scoped acceptance policy requires.
+  class CryptoSuiteBinding < Lutaml::Model::Serializable
+    USES = %w[sign hash kem transport].freeze
+    PHASES = %w[primary composite post-quantum].freeze
+
+    attribute :suite_id, :string          # registry item id (crypto-suite subregister)
+    attribute :jurisdiction, :string
+    attribute :use, :string, values: USES
+    attribute :phase, :string, values: PHASES, default: -> { "primary" }
+
+    json do
+      map "suite_id", to: :suite_id
+      map "jurisdiction", to: :jurisdiction
+      map "use", to: :use
+      map "phase", to: :phase
+    end
+
+    yaml do
+      map "suite_id", to: :suite_id
+      map "jurisdiction", to: :jurisdiction
+      map "use", to: :use
+      map "phase", to: :phase
+    end
+
+    def post_quantum?
+      phase == "post-quantum"
+    end
+  end
+
+  # The profile manifest (L2 / I10): a profile is a registered, versioned
+  # lens placed on the neutral core. It binds axes (jurisdiction x sector
+  # x characteristic), trigger predicates, the minimum subject capability
+  # class it can be served for, its crypto-suite bindings, the data points
+  # it requires (references into the semantic registry), languages, and
+  # its legal effective window. Registered transforms and trust
+  # requirements ride the registry items referenced here.
+  #
+  # (De)serialization is generated by lutaml-model from the attribute +
+  # mapping declarations below — no hand-rolled to_h / from_h.
+  class ProfileManifest < Lutaml::Model::Serializable
+    CAPABILITY_CLASSES = CapabilityClass::ORDER
+
+    attribute :profile_id, :string       # registry item identifier
+    attribute :version, :string          # registry item version pin
+    attribute :register, :string         # FERIN register that holds the profile
+    attribute :owner, :string            # regulator / profile owner
+    attribute :legal_basis, :string      # citation URI of the applicable law
+    attribute :axes, ProfileAxes
+    attribute :triggers, TriggerPredicate, collection: true, default: -> { [] }
+    attribute :capability_class, :string, values: CAPABILITY_CLASSES,
+                                           default: -> { "S0" }
+    attribute :crypto_suites, CryptoSuiteBinding, collection: true,
+                                                  default: -> { [] }
+    # Data points required by the profile: (register, item, version)
+    # references into the semantic registry, as resolvable URIs.
+    attribute :data_points, :string, collection: true, default: -> { [] }
+    attribute :languages, :string, collection: true, default: -> { [] }
+    attribute :effective_from, "Lutaml::Model::Type::DateTime"
+    attribute :effective_until, "Lutaml::Model::Type::DateTime"
+    # Resolution / traversal exposure (I12): confidential profiles are
+    # non-public register items; resolution scope limits the resolver.
+    attribute :resolution, :string,
+               values: %w[none national restricted public],
+               default: -> { "public" }
+    attribute :confidential, :boolean, default: -> { false }
+
+    json do
+      map "profile_id", to: :profile_id
+      map "version", to: :version
+      map "register", to: :register, render_nil: false
+      map "owner", to: :owner, render_nil: false
+      map "legal_basis", to: :legal_basis, render_nil: false
+      map "axes", to: :axes, render_nil: false
+      map "triggers", to: :triggers, render_nil: false
+      map "capability_class", to: :capability_class
+      map "crypto_suites", to: :crypto_suites, render_nil: false
+      map "data_points", to: :data_points, render_nil: false
+      map "languages", to: :languages, render_nil: false
+      map "effective_from", to: :effective_from, render_nil: false
+      map "effective_until", to: :effective_until, render_nil: false
+      map "resolution", to: :resolution
+      map "confidential", to: :confidential
+    end
+
+    yaml do
+      map "profile_id", to: :profile_id
+      map "version", to: :version
+      map "register", to: :register, render_nil: false
+      map "owner", to: :owner, render_nil: false
+      map "legal_basis", to: :legal_basis, render_nil: false
+      map "axes", to: :axes, render_nil: false
+      map "triggers", to: :triggers, render_nil: false
+      map "capability_class", to: :capability_class
+      map "crypto_suites", to: :crypto_suites, render_nil: false
+      map "data_points", to: :data_points, render_nil: false
+      map "languages", to: :languages, render_nil: false
+      map "effective_from", to: :effective_from, render_nil: false
+      map "effective_until", to: :effective_until, render_nil: false
+      map "resolution", to: :resolution
+      map "confidential", to: :confidential
+    end
+
+    # A profile with no trigger predicates applies to every subject of
+    # its axes; otherwise every predicate must match (conjunction).
+    #
+    # @param facts [Hash] twin facts document
+    # @return [Boolean]
+    def applies_to?(facts)
+      triggers.all? { |predicate| predicate.matches?(facts) }
+    end
+
+    # @param subject_capability [String] S0..S3 of the subject
+    # @return [Boolean] satisfiability of this profile for that class
+    def satisfiable_for?(subject_capability)
+      CapabilityClass.satisfies?(capability_class, subject_capability)
+    end
+
+    # Legal effective window at time +t+.
+    # @param t [Time, DateTime]
+    # @return [Boolean]
+    def effective_at?(t)
+      t = to_datetime(t)
+      (!effective_from || t >= effective_from) &&
+        (!effective_until || t < effective_until)
+    end
+
+    def jurisdiction_profile?
+      !axes.jurisdictions.empty?
+    end
+
+    def characteristic_profile?
+      !axes.characteristics.empty?
+    end
+
+    def time_triggered?
+      triggers.any?(&:time_fired?)
+    end
+
+    private
+
+    def to_datetime(t)
+      t.is_a?(DateTime) ? t : DateTime.parse(t.to_s)
+    end
+  end
+end

data/lib/unidpp/quantity.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+
+module Unidpp
+  # Quantity = value + registered unit URI (the units chain: ISO 80000 ->
+  # UnitsDB/UnitsML -> OpenCDD mirror). Units are *registered URIs*, not
+  # bare symbols; unit conversion is a registered transform (deterministic
+  # factors from the registry), so this class never converts implicitly —
+  # arithmetic requires identical unit URIs and raises on mismatch. The
+  # twin stores canonical measured values in canonical units only; no
+  # pre-transformed duplicates.
+  #
+  # Measurement uncertainty is mandatory metadata on measured values
+  # (published MTF): it is carried as a standard (k=1) uncertainty with
+  # its coverage factor, and conformity decisions near a boundary follow
+  # the ILAC-G8/JCGM-106 shared-risk rule (measured values agree when
+  # |difference| <= expanded combined uncertainty).
+  #
+  # (De)serialization is generated by lutaml-model from the attribute +
+  # mapping declarations below — no hand-rolled to_h / from_h.
+  class Quantity < Lutaml::Model::Serializable
+    class UnitMismatchError < Unidpp::Error; end
+
+    # Standard uncertainty with coverage factor.
+    class Uncertainty < Lutaml::Model::Serializable
+      attribute :value, :decimal
+      attribute :coverage_factor, :decimal, default: -> { BigDecimal("2") }
+
+      json do
+        map "value", to: :value
+        map "coverage_factor", to: :coverage_factor
+      end
+
+      yaml do
+        map "value", to: :value
+        map "coverage_factor", to: :coverage_factor
+      end
+
+      # @return [BigDecimal] expanded uncertainty U = k * u
+      def expanded
+        value * coverage_factor
+      end
+    end
+
+    attribute :value, :decimal
+    # Registered unit URI, e.g. "https://unitsml.org/unit#kWh" or the
+    # UnitsDB identifier URI for the unit.
+    attribute :unit, :string
+    attribute :uncertainty, Uncertainty
+
+    json do
+      map "value", to: :value
+      map "unit", to: :unit
+      map "uncertainty", to: :uncertainty, render_nil: false
+    end
+
+    yaml do
+      map "value", to: :value
+      map "unit", to: :unit
+      map "uncertainty", to: :uncertainty, render_nil: false
+    end
+
+    # -- strict-unit arithmetic ------------------------------------------------
+
+    def +(other)
+      assert_same_unit(other)
+      Quantity.new(value: value + other.value, unit: unit,
+                   uncertainty: combine_uncertainty(other))
+    end
+
+    def -(other)
+      assert_same_unit(other)
+      Quantity.new(value: value - other.value, unit: unit,
+                   uncertainty: combine_uncertainty(other))
+    end
+
+    # Scalar multiple (unit unchanged); scaling does not apply to
+    # uncertainties.
+    def *(factor)
+      Quantity.new(value: value * factor, unit: unit)
+    end
+
+    def zero?
+      value.zero?
+    end
+
+    def negative?
+      value.negative?
+    end
+
+    def positive?
+      value.positive?
+    end
+
+    # @param other [Quantity]
+    # @return [Boolean] same registered unit URI
+    def compatible_with?(other)
+      unit == other.unit
+    end
+
+    # ILAC-G8 shared-risk conformity decision: two measured values agree
+    # when their absolute difference is within the expanded combined
+    # uncertainty (U = k * sqrt(u1^2 + u2^2), k = the larger coverage
+    # factor). Values without uncertainties agree only on exact equality.
+    #
+    # @param other [Quantity]
+    # @return [Boolean]
+    def agrees_with?(other)
+      assert_same_unit(other)
+      return value == other.value unless uncertainty && other.uncertainty
+
+      (value - other.value).abs <= expanded_combined_uncertainty(other)
+    end
+
+    # @param other [Quantity]
+    # @return [BigDecimal] k * sqrt(u1^2 + u2^2), nil when uncertainless
+    def expanded_combined_uncertainty(other)
+      return nil unless uncertainty && other.uncertainty
+
+      k = [uncertainty.coverage_factor,
+           other.uncertainty.coverage_factor].max
+      sum_of_squares = uncertainty.value * uncertainty.value +
+                       other.uncertainty.value * other.uncertainty.value
+      k * BigDecimal(sum_of_squares.sqrt(10))
+    end
+
+    private
+
+    def assert_same_unit(other)
+      return if compatible_with?(other)
+
+      raise UnitMismatchError,
+            "unit mismatch: #{unit} vs #{other.unit} — convert through a " \
+            "registered transform, never implicitly"
+    end
+
+    def combine_uncertainty(other)
+      return nil unless uncertainty && other.uncertainty
+
+      Uncertainty.new(
+        value: BigDecimal(Math.sqrt(
+          (uncertainty.value * uncertainty.value +
+           other.uncertainty.value * other.uncertainty.value).to_f
+        )),
+        coverage_factor: uncertainty.coverage_factor
+      )
+    end
+  end
+end

data/lib/unidpp/registry/applicability.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Unidpp
+  module Registry
+    # Applicability binding (source invariant 9): profile-set growth is
+    # dated binding, not new identity. Adding a profile to an existing
+    # subject is a registry applicability event with an effective window
+    # and a retroactivity flag; manifest history is as-of-reconstructable.
+    #
+    # Retroactivity semantics: a retroactive binding legally backdates —
+    # it applies from its effective_from even though registered later
+    # (end-of-waste style re-qualification, corrected as-of state). A
+    # non-retroactive binding cannot impose obligations for times before
+    # the authority declared it (registered_at).
+    class ApplicabilityBinding < Lutaml::Model::Serializable
+      attribute :subject, :string        # canonical product/type identity
+      attribute :profile_item, :string   # registry item identifier
+      attribute :register, :string       # register holding the profile
+      attribute :profile_version, :string
+      attribute :effective_from, "Lutaml::Model::Type::DateTime"
+      attribute :effective_until, "Lutaml::Model::Type::DateTime"
+      attribute :registered_at, "Lutaml::Model::Type::DateTime"
+      attribute :retroactive, :boolean, default: -> { false }
+
+      json do
+        map "subject", to: :subject
+        map "profile_item", to: :profile_item
+        map "register", to: :register, render_nil: false
+        map "profile_version", to: :profile_version, render_nil: false
+        map "effective_from", to: :effective_from, render_nil: false
+        map "effective_until", to: :effective_until, render_nil: false
+        map "registered_at", to: :registered_at, render_nil: false
+        map "retroactive", to: :retroactive
+      end
+
+      yaml do
+        map "subject", to: :subject
+        map "profile_item", to: :profile_item
+        map "register", to: :register, render_nil: false
+        map "profile_version", to: :profile_version, render_nil: false
+        map "effective_from", to: :effective_from, render_nil: false
+        map "effective_until", to: :effective_until, render_nil: false
+        map "registered_at", to: :registered_at, render_nil: false
+        map "retroactive", to: :retroactive
+      end
+
+      # Legal as-of semantics.
+      #
+      # @param t [Time, DateTime]
+      # @return [Boolean] the binding applied to the subject at +t+
+      def applies_at?(t)
+        t = t.is_a?(DateTime) ? t : DateTime.parse(t.to_s)
+        return false if effective_from && t < effective_from
+        return false if effective_until && t >= effective_until
+        return false if !retroactive? && registered_at && t < registered_at
+
+        true
+      end
+
+      # @return [Boolean]
+      def retroactive?
+        retroactive == true
+      end
+    end
+  end
+end

data/lib/unidpp/registry/client.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Unidpp
+  module Registry
+    # Registry client: item lookup with version+status, supersession
+    # resolution, and applicability as-of queries over any Store. The
+    # client is read-only — registration (proposals, public review,
+    # control-body decisions) belongs to the register operator's own
+    # tooling; consumers resolve references.
+    class Client
+      class ItemNotFoundError < Unidpp::Error; end
+      class NoValidVersionError < Unidpp::Error; end
+
+      attr_reader :store
+
+      # @param store [Store]
+      def initialize(store:)
+        @store = store
+      end
+
+      # @return [Register, nil]
+      def register
+        store.register
+      end
+
+      # @return [Array<Item>]
+      def items
+        store.items
+      end
+
+      # @param register [String, nil] optional register scope
+      # @param identifier [String] item identifier
+      # @return [Item, nil]
+      def item(identifier, register: nil)
+        store.items.find do |i|
+          i.identifier == identifier && (register.nil? || i.register == register)
+        end
+      end
+
+      # @param identifier [String]
+      # @return [Item]
+      # @raise [ItemNotFoundError]
+      def item!(identifier, register: nil)
+        scope = register ? " in register #{register.inspect}" : ""
+        item(identifier, register: register) ||
+          raise(ItemNotFoundError,
+                "no registry item #{identifier.inspect}#{scope}")
+      end
+
+      # Version-pinned lookup: the exact version when given, otherwise the
+      # version currently in force.
+      #
+      # @param identifier [String]
+      # @param version [String, nil]
+      # @return [ItemVersion]
+      # @raise [ItemNotFoundError, Item::UnknownVersionError]
+      def version_of(identifier, version: nil, register: nil)
+        found = item!(identifier, register: register)
+        version ? found.version!(version) : current_version_of(found)
+      end
+
+      # @param item [Item]
+      # @return [ItemVersion]
+      # @raise [NoValidVersionError] when no version is in force
+      def current_version_of(item)
+        item.current_version ||
+          raise(NoValidVersionError, "#{item.identifier} has no valid version")
+      end
+
+      # Supersession resolution: the terminal version of the chain.
+      #
+      # @param identifier [String]
+      # @return [ItemVersion]
+      # @raise [ItemNotFoundError]
+      def resolve(identifier, register: nil)
+        supersession_chain(identifier, register: register).last
+      end
+
+      # @param identifier [String]
+      # @param from [String, nil] chain start version
+      # @return [Array<ItemVersion>] chain in supersession order
+      # @raise [ItemNotFoundError]
+      def supersession_chain(identifier, from: nil, register: nil)
+        item!(identifier, register: register).supersession_chain(from: from)
+      end
+
+      # Point-in-time item state: the version in force at +t+.
+      #
+      # @param identifier [String]
+      # @param as_of [Time, DateTime]
+      # @return [ItemVersion, nil]
+      # @raise [ItemNotFoundError]
+      def version_as_of(identifier, as_of:, register: nil)
+        item!(identifier, register: register).in_force_at(as_of)
+      end
+
+      # -- applicability --------------------------------------------------
+
+      # @param subject [String] canonical product/type identity
+      # @return [Array<ApplicabilityBinding>]
+      def bindings_for(subject)
+        store.bindings.select { |b| b.subject == subject }
+      end
+
+      # The legal as-of query: which profiles applied to +subject+ at +t+.
+      # Retroactive bindings apply from their effective_from even when
+      # registered later; non-retroactive ones only from registered_at.
+      #
+      # @param subject [String]
+      # @param as_of [Time, DateTime]
+      # @return [Array<ApplicabilityBinding>]
+      def applicable_profiles(subject, as_of:)
+        bindings_for(subject).select { |b| b.applies_at?(as_of) }
+      end
+
+      # The same query resolved to version-pinned profile items.
+      #
+      # @param subject [String]
+      # @param as_of [Time, DateTime]
+      # @return [Array<Item>] profile items applicable at +t+
+      def applicable_profile_items(subject, as_of:)
+        applicable_profiles(subject, as_of: as_of).map do |binding|
+          item(binding.profile_item, register: binding.register)
+        end.compact
+      end
+
+      # The manifests of the profiles applicable at +t+ (nil entries are
+      # skipped for bindings whose item carries no embedded manifest).
+      #
+      # @param subject [String]
+      # @param as_of [Time, DateTime]
+      # @return [Array<ProfileManifest>]
+      def applicable_manifests(subject, as_of:)
+        applicable_profiles(subject, as_of: as_of).filter_map do |binding|
+          found = item(binding.profile_item, register: binding.register)
+          found&.manifest
+        end
+      end
+    end
+  end
+end