visiq 0.1.0-x86_64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 002da0e84b12a9803aa799a69cf53d9d31f354b699ceba941ad81a561d0ed936
+  data.tar.gz: acc2f808fe222469b2248ff7755f57bf130bf4ae95444093116dfc700a13fecf
+SHA512:
+  metadata.gz: b496fbf49ca2f4eb7086e4363e02de85edc96a09af7f5e1cdd3fd6e69bb0534b4252bc30a4eb974a2f36b16903b00b654c15eaa77920aca2760ae2843056be86
+  data.tar.gz: 1f6d7560dabe0489a5a6a7f3c2c389a38406fbb22e82fc80559d64cf6e5e0f0c83f813f2b300423871cc9df1dee13ec43d8ecc9a81a7d7f49555525c2683df32

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VisIQ Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,49 @@
+# visiq — VisIQ agent-governance SDK for Ruby
+
+Local, in-process governance decisions for AI agents. ONE compiled Rust core
+(Path B) makes the **same** decisions as the shipped TypeScript SDK
+(`@visiq/harness`), bound to Ruby through the stdlib `Fiddle` FFI. The engine
+ships as **compiled machine code** (closed); the Ruby is thin FFI plumbing only.
+
+- **Local & fast** — every decision is in-process, no network.
+- **Fails closed (G001)** — malformed input, or a core that can't load, denies.
+- **Cross-language parity** — reproduces the exact decisions of the TS/Python/…
+  SDKs from the same core, verified against a shared corpus.
+
+## Install
+
+```bash
+gem install visiq
+```
+
+Native, per-platform "fat" gems are published for macOS (arm64, x86_64) and Linux
+(x86_64, aarch64) — `gem install` selects the one matching your platform and it
+bundles the compiled core. **Ruby ≥ 3.0.**
+
+## Usage
+
+```ruby
+require "visiq"
+
+bundle = load_rules_bundle  # your VisIQ rules bundle (Hash)
+
+# Gate a tool/action call — block unless allowed.
+d = Visiq.gate_action(bundle, tool_name: "wire_transfer", args: { "amount" => 999 }, agent_id: "agent-1")
+block_the_call unless d["allowed"]
+
+# Gate a retrieval — drop on deny/escalate; redact via redactionRules.
+r = Visiq.gate_retrieval(bundle, resource_metadata: { "classification" => "ssn" })
+# r["retrieval"]["action"] ∈ allow | deny | redact | escalate
+```
+
+`Visiq.decide(event, bundle)` returns the full `UnifiedDecision` hash
+(`{"decision","allowed","action","retrieval"}`).
+
+## Overriding the core location
+
+Set `VISIQ_CORE_LIB` to an absolute path to a `libvisiq_core` shared library to
+override the bundled one (e.g. for local development against a fresh build).
+
+## License
+
+MIT © VisIQ Labs. See [LICENSE](./LICENSE).

data/lib/visiq.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+# VisIQ agent-governance SDK (Ruby) — local, in-process policy decisions.
+#
+# ONE compiled Rust core (Path B) makes the SAME decisions as the shipped
+# TypeScript SDK (`@visiq/harness`). This gem is a thin binding over the core's
+# language-neutral C-ABI seam (`visiq_evaluate`/`visiq_free`) via Ruby's stdlib
+# `Fiddle` — zero runtime gem dependencies. The engine is compiled machine code;
+# the gem ships the shared library CLOSED (the Ruby is only FFI plumbing, no
+# policy). Every decision is local (no network) and fails closed on malformed
+# input (G001).
+#
+#   require "visiq"
+#   d = Visiq.gate_action(bundle, tool_name: "wire_transfer", args: { "amount" => 999 }, agent_id: "a")
+#   block_the_call unless d["allowed"]
+#   r = Visiq.gate_retrieval(bundle, resource_metadata: { "classification" => "ssn" })
+#   # r["retrieval"]["action"] ∈ allow|deny|redact|escalate
+require "fiddle"
+require "json"
+require "rbconfig"
+
+module Visiq
+  VERSION = "0.1.0"
+
+  # Low-level binding to the compiled core over the C-ABI seam.
+  module Core
+    class << self
+      # JSON in, JSON out — the language-neutral FFI seam. Returns a heap C string
+      # the core allocates; we copy it into a Ruby String then hand it back to
+      # `visiq_free` so the core owns both sides of the allocation.
+      def evaluate_json(event_json, bundle_json)
+        ptr = evaluate_fn.call(event_json, bundle_json)
+        str = ptr.to_s
+        free_fn.call(ptr)
+        str
+      end
+
+      private
+
+      def handle
+        @handle ||= begin
+          path = lib_path
+          Fiddle.dlopen(path)
+        rescue Fiddle::DLError => e
+          # A wrong-arch/OS bundled core (e.g. a forced install of a mismatched
+          # platform gem) fails to dlopen. Fail CLOSED with an actionable message,
+          # never a silent allow — the SDK cannot govern without its core (G001).
+          raise "visiq: failed to load the compiled core at #{path} for host " \
+                "#{RbConfig::CONFIG['host_cpu']}-#{RbConfig::CONFIG['host_os']} " \
+                "(#{e.message}). Install the platform-matching `visiq` gem, or set " \
+                "VISIQ_CORE_LIB to a compatible libvisiq_core."
+        end
+      end
+
+      def evaluate_fn
+        @evaluate_fn ||= Fiddle::Function.new(
+          handle["visiq_evaluate"], [Fiddle::TYPE_VOIDP, Fiddle::TYPE_VOIDP], Fiddle::TYPE_VOIDP
+        )
+      end
+
+      def free_fn
+        @free_fn ||= Fiddle::Function.new(handle["visiq_free"], [Fiddle::TYPE_VOIDP], Fiddle::TYPE_VOID)
+      end
+
+      def lib_path
+        env = ENV["VISIQ_CORE_LIB"]
+        return env if env && File.exist?(env)
+
+        ext = case RbConfig::CONFIG["host_os"]
+              when /darwin/ then "dylib"
+              when /mswin|mingw/ then "dll"
+              else "so"
+              end
+        candidates = [
+          # bundled in the published gem (platform-specific), then the dev build:
+          File.join(__dir__, "..", "vendor", "libvisiq_core.#{ext}"),
+          File.join(__dir__, "..", "..", "visiq-core-rs", "target-capi", "release", "libvisiq_core.#{ext}")
+        ]
+        found = candidates.find { |p| File.exist?(p) }
+        raise "visiq: cannot locate libvisiq_core.#{ext} (set VISIQ_CORE_LIB)" unless found
+
+        found
+      end
+    end
+  end
+
+  module_function
+
+  # Evaluate one governed agent event against a rules bundle. Returns the
+  # UnifiedDecision hash: {"decision","allowed","action","retrieval"}.
+  def decide(event, bundle)
+    JSON.parse(Core.evaluate_json(JSON.generate(event), JSON.generate(bundle)))
+  end
+
+  # Gate a tool/action call. Check ["allowed"]; on "mask" apply
+  # ["action"]["argRedactionRules"] to the args before running the tool.
+  def gate_action(bundle, tool_name:, args: nil, agent_id: "agent", target_resource: nil, normalized: nil)
+    event = { "operations" => ["action"], "agentId" => agent_id, "toolName" => tool_name }
+    event["toolArgs"] = args unless args.nil?
+    event["targetResource"] = target_resource unless target_resource.nil?
+    event["normalized"] = normalized unless normalized.nil?
+    decide(event, bundle)
+  end
+
+  # Gate a retrieval. Inspect ["retrieval"]["action"] — drop on deny/escalate,
+  # redact via ["retrieval"]["redactionRules"] — before content reaches the model.
+  def gate_retrieval(bundle, resource_metadata: nil, resource_type: "document", agent_id: "agent", query: nil)
+    event = { "operations" => ["retrieval"], "agentId" => agent_id, "resourceType" => resource_type }
+    event["resourceMetadata"] = resource_metadata unless resource_metadata.nil?
+    event["query"] = query unless query.nil?
+    decide(event, bundle)
+  end
+end

metadata

@@ -0,0 +1,69 @@
+--- !ruby/object:Gem::Specification
+name: visiq
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: x86_64-linux
+authors:
+- VisIQ Labs Team
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-07-08 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: fiddle
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: ONE compiled Rust core (Path B) that reproduces the shipped TypeScript
+  SDK's decisions, bound to Ruby via a stdlib Fiddle FFI. Fully local; fails closed
+  on malformed input (G001). The engine ships as compiled machine code (closed); the
+  Ruby is thin FFI plumbing only.
+email:
+- dev@visiqlabs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- lib/visiq.rb
+- vendor/libvisiq_core.so
+homepage: https://docs.visiqlabs.com
+licenses:
+- MIT
+metadata:
+  rubygems_mfa_required: 'true'
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://docs.visiqlabs.com
+  documentation_uri: https://docs.visiqlabs.com
+  bug_tracker_uri: https://docs.visiqlabs.com/support
+post_install_message:
+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: 3.5.22
+signing_key:
+specification_version: 4
+summary: VisIQ agent-governance SDK — local, in-process policy decisions.
+test_files: []