unidpp 0.1.0

data/lib/unidpp/registry/file_store.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "json"
+require "yaml"
+
+module Unidpp
+  module Registry
+    # Local JSON/YAML store adapter: registry content read from a
+    # directory or a single consolidated document. All (de)serialization
+    # of items, bindings and register metadata goes through lutaml-model
+    # (Item.from_yaml / from_json, etc.); this adapter only locates and
+    # reads raw documents.
+    #
+    # Directory layout (glossarist-dataset style, one item per file):
+    #
+    #   <path>/register.yaml      Register metadata
+    #   <path>/items/*.yaml       one Item per file
+    #   <path>/bindings/*.yaml    one ApplicabilityBinding or a
+    #                             bindings: [...] list per file
+    #
+    # Single-file layout (JSON or YAML): one document with the keys
+    # +register+, +items+, +applicability+.
+    #
+    # Item version entries are immutable per version and perfectly
+    # cacheable — only register status is mutable — so a FileStore may
+    # also serve as an offline mirror of a remote register.
+    class FileStore < Store
+      class FormatError < Unidpp::Error; end
+
+      ITEM_GLOB = "items/*.{yaml,yml,json}".freeze
+      BINDING_GLOB = "bindings/*.{yaml,yml,json}".freeze
+
+      # @param path [String] directory or single document file
+      def initialize(path)
+        @path = File.expand_path(path)
+        @directory = File.directory?(@path)
+        freeze_content
+      end
+
+      # @return [Array<Item>]
+      def items
+        content[:items]
+      end
+
+      # @return [Array<ApplicabilityBinding>]
+      def bindings
+        content[:bindings]
+      end
+
+      # @return [Register, nil]
+      def register
+        content[:register]
+      end
+
+      private
+
+      def content
+        @content
+      end
+
+      def freeze_content
+        @content =
+          if @directory
+            load_directory
+          else
+            load_single_file
+          end
+      end
+
+      def load_directory
+        {
+          register: load_register,
+          items: Dir[File.join(@path, ITEM_GLOB)].sort.map { |f| load_item(f) },
+          bindings: Dir[File.join(@path, BINDING_GLOB)].sort.flat_map { |f| load_bindings(f) },
+        }
+      end
+
+      def load_single_file
+        doc = read_document(@path)
+        unless doc.is_a?(Hash)
+          raise FormatError, "registry document must be a mapping: #{@path}"
+        end
+
+        {
+          register: doc["register"] && Register.from_hash(doc["register"]),
+          items: Array(doc["items"]).map { |i| Item.from_hash(i) },
+          bindings: Array(doc["applicability"] || doc["bindings"])
+                      .map { |b| ApplicabilityBinding.from_hash(b) },
+        }
+      end
+
+      def load_register
+        path = Dir[File.join(@path, "register.{yaml,yml,json}")].first
+        doc = path && read_document(path)
+        doc && Register.from_hash(doc)
+      end
+
+      def load_item(path)
+        Item.from_hash(read_document(path))
+      end
+
+      def load_bindings(path)
+        doc = read_document(path)
+        list = doc.is_a?(Hash) ? doc["bindings"] : doc
+        Array(list).map { |b| ApplicabilityBinding.from_hash(b) }
+      end
+
+      # Reads a raw JSON or YAML document (plain data; YAML timestamps are
+      # permitted and cast to ISO strings by the lutaml DateTime type).
+      def read_document(path)
+        if File.extname(path) == ".json"
+          JSON.parse(File.read(path))
+        else
+          YAML.safe_load(File.read(path),
+                         permitted_classes: [Time, Date, DateTime],
+                         aliases: true)
+        end
+      end
+    end
+  end
+end

data/lib/unidpp/registry/item.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module Unidpp
+  module Registry
+    # A registry item: the single definition (I2 — single definition, many
+    # constraints) of a data element, profile, transform, crypto suite,
+    # trust anchor or unit. Item references are (register, item, version).
+    # Profiles constrain and compose; they never redefine — where regions
+    # regulate differently they register distinct items.
+    #
+    # Profile items embed their ProfileManifest, version-pinned to one of
+    # the item's versions (seam S4: version pinning at the profile↔registry
+    # join).
+    class Item < Lutaml::Model::Serializable
+      ITEM_CLASSES = %w[
+        data-element profile crypto-suite transform trust-anchor unit
+      ].freeze
+
+      class UnknownVersionError < Unidpp::Error; end
+
+      attribute :identifier, :string
+      attribute :register, :string
+      attribute :item_class, :string, values: ITEM_CLASSES
+      attribute :title, :string
+      # ISO 19135 submitting organization for this item.
+      attribute :submitting_organization, :string
+      attribute :versions, ItemVersion, collection: true, default: -> { [] }
+      attribute :manifest, ProfileManifest
+
+      json do
+        map "identifier", to: :identifier
+        map "register", to: :register, render_nil: false
+        map "item_class", to: :item_class
+        map "title", to: :title, render_nil: false
+        map "submitting_organization", to: :submitting_organization, render_nil: false
+        map "versions", to: :versions
+        map "manifest", to: :manifest, render_nil: false
+      end
+
+      yaml do
+        map "identifier", to: :identifier
+        map "register", to: :register, render_nil: false
+        map "item_class", to: :item_class
+        map "title", to: :title, render_nil: false
+        map "submitting_organization", to: :submitting_organization, render_nil: false
+        map "versions", to: :versions
+        map "manifest", to: :manifest, render_nil: false
+      end
+
+      # item_class predicates (profile? / unit? / ...) are generated by
+      # lutaml-model from the item_class value enumeration.
+
+      # @param number [String]
+      # @return [ItemVersion, nil]
+      def version(number)
+        versions.find { |v| v.version == number.to_s }
+      end
+
+      # @param number [String]
+      # @return [ItemVersion]
+      # @raise [UnknownVersionError]
+      def version!(number)
+        version(number) ||
+          raise(UnknownVersionError, "#{identifier} has no version #{number}")
+      end
+
+      # Versions in registration order (by effective_from, then version).
+      #
+      # @return [Array<ItemVersion>]
+      def ordered_versions
+        versions.sort_by do |v|
+          [v.effective_from || DateTime.new(0), v.version.to_s]
+        end
+      end
+
+      # The version currently in force: latest effective version with
+      # status "valid".
+      #
+      # @return [ItemVersion, nil]
+      def current_version
+        reversed = ordered_versions.reverse
+        reversed.find(&:valid?) || reversed.find { |v| !v.retired? }
+      end
+
+      # Follows supersession links from the earliest version carrying one
+      # (or from +from+, when given) to the terminal version.
+      #
+      # @param from [String, nil] version number to start from
+      # @return [Array<ItemVersion>] the chain, in supersession order
+      def supersession_chain(from: nil)
+        start = from ? version!(from) : ordered_versions.first
+        chain = [start]
+        while (next_number = chain.last.superseded_by_version)
+          chain << version!(next_number)
+        end
+        chain
+      end
+
+      # Resolved effective window end: explicit effective_until, else the
+      # successor's effective_from, else open (nil).
+      #
+      # @param version_number [String]
+      # @return [DateTime, nil]
+      def window_until(version_number)
+        v = version!(version_number)
+        return v.effective_until if v.effective_until
+        return nil if v.superseded_by_version.nil?
+
+        version(v.superseded_by_version)&.effective_from
+      end
+
+      # The version in force at time +t+ (point-in-time registry state).
+      #
+      # @param t [Time, DateTime]
+      # @return [ItemVersion, nil]
+      def in_force_at(t)
+        t = t.is_a?(DateTime) ? t : DateTime.parse(t.to_s)
+        ordered_versions
+          .select { |v| v.in_force_at?(t, until_time: window_until(v.version)) }
+          .last
+      end
+
+      # Seam S4 discipline: an embedded manifest must be pinned to a
+      # version of this item.
+      #
+      # @return [Boolean]
+      def manifest_version_pinned?
+        manifest.nil? || !version(manifest.version).nil?
+      end
+    end
+  end
+end

data/lib/unidpp/registry/item_version.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Unidpp
+  module Registry
+    # One version of a registry item with its ISO 19135 lifecycle status.
+    # Versions are immutable once registered; status and supersession
+    # links express the lifecycle (valid / superseded / retired).
+    class ItemVersion < Lutaml::Model::Serializable
+      STATUSES = %w[valid superseded retired].freeze
+
+      attribute :version, :string
+      attribute :status, :string, values: STATUSES
+      # Effective window of this version. An open effective_until is
+      # derived from the successor's effective_from when absent.
+      attribute :effective_from, "Lutaml::Model::Type::DateTime"
+      attribute :effective_until, "Lutaml::Model::Type::DateTime"
+      attribute :registered_at, "Lutaml::Model::Type::DateTime"
+      attribute :superseded_by_version, :string
+      attribute :notes, :string
+
+      json do
+        map "version", to: :version
+        map "status", to: :status
+        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 "superseded_by_version", to: :superseded_by_version, render_nil: false
+        map "notes", to: :notes, render_nil: false
+      end
+
+      yaml do
+        map "version", to: :version
+        map "status", to: :status
+        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 "superseded_by_version", to: :superseded_by_version, render_nil: false
+        map "notes", to: :notes, render_nil: false
+      end
+
+      def valid?
+        status == "valid"
+      end
+
+      def superseded?
+        status == "superseded"
+      end
+
+      def retired?
+        status == "retired"
+      end
+
+      # @param t [Time, DateTime]
+      # @param until_time [DateTime, nil] resolved window end (explicit or
+      #   derived from the successor)
+      # @return [Boolean] this version was in force at +t+
+      def in_force_at?(t, until_time: effective_until)
+        t = t.is_a?(DateTime) ? t : DateTime.parse(t.to_s)
+        return false if effective_from && t < effective_from
+        return false if until_time && t >= until_time
+
+        true
+      end
+    end
+  end
+end

data/lib/unidpp/registry/register.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Unidpp
+  module Registry
+    # Register metadata with ISO 19135 governance roles: the register
+    # owner, register manager and control body for this (sub)register.
+    # FERIN registers federate as siblings — no register is the universal
+    # envelope.
+    class Register < Lutaml::Model::Serializable
+      attribute :register_id, :string   # FERIN register identifier
+      attribute :name, :string
+      attribute :register_owner, :string
+      attribute :register_manager, :string
+      attribute :control_body, :string
+      attribute :homepage, :string
+
+      json do
+        map "register_id", to: :register_id
+        map "name", to: :name, render_nil: false
+        map "register_owner", to: :register_owner, render_nil: false
+        map "register_manager", to: :register_manager, render_nil: false
+        map "control_body", to: :control_body, render_nil: false
+        map "homepage", to: :homepage, render_nil: false
+      end
+
+      yaml do
+        map "register_id", to: :register_id
+        map "name", to: :name, render_nil: false
+        map "register_owner", to: :register_owner, render_nil: false
+        map "register_manager", to: :register_manager, render_nil: false
+        map "control_body", to: :control_body, render_nil: false
+        map "homepage", to: :homepage, render_nil: false
+      end
+    end
+  end
+end

data/lib/unidpp/registry/store.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Unidpp
+  module Registry
+    # Store interface — the seam between the registry client and a source
+    # of register content (local files for tests and offline mirrors; an
+    # HTTP adapter against a live FERIN register endpoint can implement
+    # the same three methods without touching the client).
+    class Store
+      # @return [Array<Item>] all items in the store
+      def items
+        raise NotImplementedError, "#{self.class} must implement #items"
+      end
+
+      # @return [Array<ApplicabilityBinding>] all applicability bindings
+      def bindings
+        raise NotImplementedError, "#{self.class} must implement #bindings"
+      end
+
+      # @return [Register, nil] register metadata when available
+      def register
+        raise NotImplementedError, "#{self.class} must implement #register"
+      end
+    end
+  end
+end

data/lib/unidpp/registry.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Unidpp
+  # FERIN / ISO 19135-style federated registry access (framework layer L3,
+  # seam S4/S5): every data point, profile, transform, crypto suite and
+  # unit is defined ONCE in a register — principal register plus
+  # federated subregisters with 19135 governance roles — and every item
+  # has a lifecycle (valid / superseded / retired) and versioned
+  # supersession chains. Applicability bindings carry effective windows
+  # with retroactivity flags, which is what makes "which profiles applied
+  # at T" answerable as a legal as-of query.
+  module Registry
+    autoload :Register,              "unidpp/registry/register"
+    autoload :ItemVersion,           "unidpp/registry/item_version"
+    autoload :Item,                  "unidpp/registry/item"
+    autoload :ApplicabilityBinding,  "unidpp/registry/applicability"
+    autoload :Store,                 "unidpp/registry/store"
+    autoload :FileStore,             "unidpp/registry/file_store"
+    autoload :Client,                "unidpp/registry/client"
+  end
+end

data/lib/unidpp/verdict.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Unidpp
+  # Verification verdict (I9 / I13): graded, never boolean. A verdict
+  # states which verification *reading* it answers, the *freshness* class
+  # of the underlying state, and a coverage report (which data points the
+  # verdict covers and which are missing).
+  #
+  # The three readings (because law needs all three):
+  #   evidentiary     what could a diligent verifier know at T, given the
+  #                   then-current trust state (protects good-faith actors)
+  #   current_state   fraud voids ab initio — prevents laundering
+  #   cryptographic   signature/chain validity alone
+  #
+  # Freshness verdicts degrade explicitly, never silently:
+  #   fresh            within the profile's freshness window
+  #   stale            past the window; still served, marked
+  #   offline_degraded served from Tier-A carrier / cache, as-of stamped
+  #   unavailable      no current state could be established
+  class Verdict < Lutaml::Model::Serializable
+    READINGS = %w[evidentiary current_state cryptographic].freeze
+    FRESHNESS = %w[fresh stale offline_degraded unavailable].freeze
+
+    attribute :reading, :string, values: READINGS
+    attribute :freshness, :string, values: FRESHNESS
+    attribute :rendered_at, "Lutaml::Model::Type::DateTime"
+    # Coverage report: data point URIs covered by this verdict and still
+    # missing for the profile that asked.
+    attribute :covered, :string, collection: true, default: -> { [] }
+    attribute :missing, :string, collection: true, default: -> { [] }
+    attribute :notes, :string, collection: true, default: -> { [] }
+
+    json do
+      map "reading", to: :reading
+      map "freshness", to: :freshness
+      map "rendered_at", to: :rendered_at, render_nil: false
+      map "covered", to: :covered, render_nil: false
+      map "missing", to: :missing, render_nil: false
+      map "notes", to: :notes, render_nil: false
+    end
+
+    yaml do
+      map "reading", to: :reading
+      map "freshness", to: :freshness
+      map "rendered_at", to: :rendered_at, render_nil: false
+      map "covered", to: :covered, render_nil: false
+      map "missing", to: :missing, render_nil: false
+      map "notes", to: :notes, render_nil: false
+    end
+
+    # Reading predicates (evidentiary? / current_state? / cryptographic?)
+    # are generated by lutaml-model from the reading value enumeration.
+
+    # I13: degradation is explicit — anything not fresh is degraded and
+    # must be marked, never silently passed.
+    def degraded?
+      freshness != "fresh"
+    end
+
+    def complete?
+      missing.empty?
+    end
+
+    # @return [Rational, nil] covered / (covered + missing), nil when empty
+    def coverage_ratio
+      total = covered.size + missing.size
+      return nil if total.zero?
+
+      Rational(covered.size, total)
+    end
+  end
+end

data/lib/unidpp/version.rb

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

data/lib/unidpp.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+# UniDPP — Ruby library for the international Digital Product Passport
+# framework (the UniDPP design framework invariants I1–I14; see https://github.com/unidpp).
+#
+# Loading discipline: this file is the only require point. Every other
+# constant is lazily loaded through autoload entries declared here (and,
+# for the Unidpp::Registry namespace, in unidpp/registry.rb) — no
+# require_relative anywhere inside lib/.
+require "lutaml/model"
+
+module Unidpp
+  class Error < StandardError; end
+
+  autoload :VERSION,         "unidpp/version"
+  autoload :CanonicalJson,   "unidpp/canonical_json"
+  autoload :AnnexB,          "unidpp/annexb"
+  autoload :Gs1,             "unidpp/gs1"
+  autoload :ProductIdentifier, "unidpp/identifier"
+  autoload :ProfileManifest, "unidpp/manifest"
+  autoload :ProfileAxes,     "unidpp/manifest"
+  autoload :TriggerPredicate, "unidpp/manifest"
+  autoload :CryptoSuiteBinding, "unidpp/manifest"
+  autoload :PassportLink,    "unidpp/link"
+  autoload :LinkInterval,    "unidpp/link"
+  autoload :Event,           "unidpp/event"
+  autoload :EventLog,        "unidpp/event_log"
+  autoload :Verdict,         "unidpp/verdict"
+  autoload :Quantity,        "unidpp/quantity"
+  autoload :Registry,        "unidpp/registry"
+end

metadata

@@ -0,0 +1,108 @@
+--- !ruby/object:Gem::Specification
+name: unidpp
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- UniDPP
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: lutaml-model
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.13'
+description: 'Ruby library for the UniDPP international Digital Product Passport framework:
+  scheme-agnostic product identifiers (GS1 Digital Link, ISO/IEC 15459, GB/T 33993-style,
+  URN), profile manifests (jurisdiction x sector x characteristic axes, trigger predicates,
+  capability classes S0-S3, crypto-suite bindings), typed relationship edges with
+  visibility classes, hash-chained append-only event logs with salted commitments,
+  graded-trust verdicts, quantities with registered unit URIs, and a federated-registry
+  client (FERIN/ISO 19135 items, statuses, supersession chains, applicability as-of
+  queries).'
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- lib/unidpp.rb
+- lib/unidpp/annexb.rb
+- lib/unidpp/canonical_json.rb
+- lib/unidpp/event.rb
+- lib/unidpp/event_log.rb
+- lib/unidpp/gs1.rb
+- lib/unidpp/identifier.rb
+- lib/unidpp/link.rb
+- lib/unidpp/manifest.rb
+- lib/unidpp/quantity.rb
+- lib/unidpp/registry.rb
+- lib/unidpp/registry/applicability.rb
+- lib/unidpp/registry/client.rb
+- lib/unidpp/registry/file_store.rb
+- lib/unidpp/registry/item.rb
+- lib/unidpp/registry/item_version.rb
+- lib/unidpp/registry/register.rb
+- lib/unidpp/registry/store.rb
+- lib/unidpp/verdict.rb
+- lib/unidpp/version.rb
+homepage: https://github.com/unidpp/unidpp-rb
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.23
+specification_version: 4
+summary: UniDPP — Digital Product Passport model, event log and FERIN/ISO 19135 registry
+  client
+test_files: []