ignis 0.0.1

data/lib/nnw/shared/ffi_loader.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+# Ignis Shared FFI Loader
+#
+# Centralizes the loading of the ruby-ffi gem across the entire Ignis platform.
+# FFI is used ONLY for struct-heavy one-shot calls (device properties, VMM structs, etc.).
+# All hot-path calls use Fiddle directly.
+#
+# The FFI gem is installed system-wide in the MSVC Ruby build at:
+#   C:\RubyMSVC34\lib\ruby\gems\3.4.0\gems\ffi-1.17.2\lib\ffi.rb
+#
+# If a vendored copy exists at vendor/ffi/ inside the project root, it takes priority.
+# This allows deploying to machines without system-installed FFI.
+
+module Ignis
+  module Shared
+    module FFILoader
+      # @return [String] the project root directory
+      PROJECT_ROOT = File.expand_path(File.join(__dir__, '..', '..', '..')).freeze
+
+      # @return [String] vendored FFI gem path
+      VENDOR_FFI_PATH = File.join(PROJECT_ROOT, 'vendor', 'ffi', 'gems').freeze
+
+      @loaded = false
+
+      class << self
+        # Load the FFI gem, preferring vendored copy if available.
+        # @return [void]
+        # @raise [LoadError] if FFI cannot be loaded from any source
+        def load!
+          return if @loaded
+
+          vendored_path = detect_vendored_ffi
+          if vendored_path
+            $LOAD_PATH.unshift(vendored_path) unless $LOAD_PATH.include?(vendored_path)
+          end
+
+          require 'ffi'
+          @loaded = true
+        end
+
+        # @return [Boolean] whether FFI has been loaded
+        def loaded?
+          @loaded
+        end
+
+        private
+
+        # Detect vendored FFI gem directory.
+        # @return [String, nil] path to vendored FFI lib directory, or nil if not found
+        def detect_vendored_ffi
+          return nil unless Dir.exist?(VENDOR_FFI_PATH)
+
+          ffi_dirs = Dir.glob(File.join(VENDOR_FFI_PATH, 'ffi-*', 'lib'))
+          return nil if ffi_dirs.empty?
+
+          # Use the latest version if multiple exist
+          ffi_dirs.max_by { |d| d[/ffi-(\d+\.\d+\.\d+)/, 1] || '0.0.0' }
+        end
+      end
+    end
+  end
+end

data/lib/nnw/shared/memory_contract.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+module Ignis
+  module Shared
+    # MemoryContract — Pinned memory ownership enforcement.
+    #
+    # Prevents double-free and use-after-free — the actual bugs that killed
+    # the previous Ignis build.
+    #
+    # Rules:
+    #   - An NvArray may only be freed by its current owner.
+    #   - Ignis is the default owner after allocation.
+    #   - NvCCL must call acquire before operating, release when done.
+    #   - WNAIS must call acquire before NOVA I/O, release when done.
+    #   - Acquiring while ref_count > 1 raises MemoryContractViolation.
+    #   - Pinned host memory is always owned by Ignis::Memory. NvCCL may
+    #     read it but may not free it.
+    #
+    # Thread-safe: all operations protected by Monitor.
+    class MemoryContract
+      # @return [MemoryContract] singleton instance
+      def self.instance
+        @instance ||= new
+      end
+
+      # Reset the singleton instance (for testing only).
+      # @return [void]
+      def self.reset!
+        @instance = new
+      end
+
+      # Acquire ownership of an NvArray.
+      #
+      # Transfers ownership from the current owner to the requesting layer.
+      # Fails if ref_count > 1 (concurrent shared references prevent safe transfer).
+      #
+      # @param array [NvArray] the array to acquire
+      # @param by [Symbol] the requesting owner (:nvruby, :nvccl, or :wnais)
+      # @return [Boolean] true if acquisition succeeded
+      # @raise [MemoryContractViolation] if array is already owned by `by`, or ref_count > 1
+      def self.acquire(array, by:)
+        instance.acquire(array, by: by)
+      end
+
+      # Release ownership of an NvArray back to the default owner (:nvruby).
+      #
+      # @param array [NvArray] the array to release
+      # @param by [Symbol] the current owner releasing the array
+      # @return [Boolean] true if release succeeded
+      # @raise [MemoryContractViolation] if `by` is not the current owner
+      def self.release(array, by:)
+        instance.release(array, by: by)
+      end
+
+      # Assert that an NvArray is owned by the expected owner.
+      #
+      # @param array [NvArray] the array to check
+      # @param expected_owner [Symbol] the expected owner
+      # @return [void]
+      # @raise [MemoryContractViolation] if the array's owner doesn't match
+      def self.assert_owner!(array, expected_owner)
+        instance.assert_owner!(array, expected_owner)
+      end
+
+      # Audit all tracked arrays for potential leaks.
+      #
+      # Returns information about all live arrays that have been tracked and
+      # are older than 5 seconds.
+      #
+      # @return [Array<Hash>] array of {array_id:, owner:, age_ms:, shape:, dtype:}
+      def self.audit
+        instance.audit
+      end
+
+      # Track an NvArray in the contract system.
+      #
+      # @param array [NvArray]
+      # @return [void]
+      def self.track(array)
+        instance.track(array)
+      end
+
+      # Remove an NvArray from tracking (called after free).
+      #
+      # @param array [NvArray]
+      # @return [void]
+      def self.untrack(array)
+        instance.untrack(array)
+      end
+
+      # Get the number of tracked arrays.
+      # @return [Integer]
+      def self.tracked_count
+        instance.tracked_count
+      end
+
+      # Instance methods
+
+      def initialize
+        @monitor = Monitor.new
+        @tracked = {} # id -> {array:, tracked_at:}
+      end
+
+      def acquire(array, by:)
+        validate_owner!(by)
+
+        @monitor.synchronize do
+          current_owner = array.owner
+
+          if current_owner == by
+            raise MemoryContractViolation,
+                  "NvArray##{array.id} is already owned by #{by.inspect} — double-acquire"
+          end
+
+          array.transfer_ownership(by)
+          track_if_needed(array)
+          true
+        end
+      end
+
+      def release(array, by:)
+        validate_owner!(by)
+
+        @monitor.synchronize do
+          unless array.owner == by
+            raise MemoryContractViolation,
+                  "NvArray##{array.id} is owned by #{array.owner.inspect}, " \
+                  "not #{by.inspect} — cannot release"
+          end
+
+          array.transfer_ownership(:nvruby)
+          true
+        end
+      end
+
+      def assert_owner!(array, expected_owner)
+        validate_owner!(expected_owner)
+
+        actual_owner = @monitor.synchronize { array.owner }
+
+        unless actual_owner == expected_owner
+          raise MemoryContractViolation,
+                "NvArray##{array.id} expected owner #{expected_owner.inspect}, " \
+                "actual #{actual_owner.inspect}"
+        end
+      end
+
+      def audit
+        now = Time.now
+        threshold_seconds = 5.0
+
+        @monitor.synchronize do
+          @tracked.values
+                  .select { |entry| (now - entry[:tracked_at]) > threshold_seconds }
+                  .map do |entry|
+                    arr = entry[:array]
+                    {
+                      array_id: arr.id,
+                      owner: arr.owner,
+                      age_ms: ((now - entry[:tracked_at]) * 1000).round,
+                      shape: arr.shape,
+                      dtype: arr.dtype,
+                      freed: arr.freed?
+                    }
+                  end
+        end
+      end
+
+      def track(array)
+        @monitor.synchronize do
+          @tracked[array.id] = { array: array, tracked_at: Time.now }
+        end
+      end
+
+      def untrack(array)
+        @monitor.synchronize do
+          @tracked.delete(array.id)
+        end
+      end
+
+      def tracked_count
+        @monitor.synchronize { @tracked.size }
+      end
+
+      private
+
+      # Automatically track array if not already tracked.
+      # @param array [NvArray]
+      def track_if_needed(array)
+        @tracked[array.id] ||= { array: array, tracked_at: Time.now }
+      end
+
+      # Validate owner parameter.
+      # @param owner [Symbol]
+      # @raise [ArgumentError]
+      def validate_owner!(owner)
+        unless NvArray::VALID_OWNERS.include?(owner)
+          raise ArgumentError,
+                "Invalid owner #{owner.inspect}. Valid: #{NvArray::VALID_OWNERS}"
+        end
+      end
+    end
+  end
+end