lora-ruby 0.5.6-x86_64-linux → 0.8.4-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 155820b5ff90f8828c11df7dd6ce3950b0601e2e374ea8353af9222db282c6f3
-  data.tar.gz: d856048cb887c4cbefac9bbe7f4e72af2fb22eae82c6488d5140edd22fe952b9
+  metadata.gz: d80ff16c35cd0c2c9a41563b78cf6eb4efd920da2ab37d72db9364b3ab1dbcf2
+  data.tar.gz: b05c7f6b6f29cdb116f0f0f6b771074ec613e460905a7a015c8b8705034e6f40
 SHA512:
-  metadata.gz: 06b481a3cdc376c01bdb2e8933974d6c736a48963a81ed78107f1547efadc3634983471fe4e8da8d07089f42715c92a8c0d2a4f854be78ede0c01b605e74d149
-  data.tar.gz: 1a55006ecb781a0ac2ecdd37a75c89eb9d7571a31f7836d5d78b94bedb7e4fa9ce8406df609b77f00f9e61a2cae289c13b4515b0f59bfe49b01a8a5ad33fd669
+  metadata.gz: '028fa90d227cd7b2a97be8c07675ed8991afbec05b22009569373226277cab3548b6a84ee516ee0fa2f8ce045e79b634b175a33de7b73ae02ea631a45cb3998e'
+  data.tar.gz: 1f687e32046ead1c082932c4571e38f2da7bb12f4aa5d08f858a17dead2a9fc5c05aa385320cb73dd4854fc7a15dd96c5426018c2c8a5051d188cb6989284a00

data/README.md

@@ -1,6 +1,6 @@
 # lora-ruby
 
-Ruby bindings for the [Lora](../../README.md) graph engine.
+Ruby bindings for the [Lora](../../../README.md) graph engine.
 Ships a native extension built with [Magnus](https://github.com/matsadler/magnus)
 on top of [`rb-sys`](https://github.com/oxidize-rb/rb-sys) so the Rust
 engine runs in-process — no separate server, no socket hop.
@@ -76,10 +76,13 @@ binding's `lora_python.Database` and because it mirrors the
 ## Public API
 
 ```ruby
-LoraRuby::Database.create(wal_dir = nil)  # -> Database
-LoraRuby::Database.new(wal_dir = nil)     # -> Database  (alias of .create)
+LoraRuby::Database.create(database_name = nil, options = nil)  # -> Database
+LoraRuby::Database.new(database_name = nil, options = nil)     # -> Database
+LoraRuby::Database.open_wal(wal_dir, options = nil)            # -> Database
 
 db.execute(query, params = nil)       # -> { "columns" => [...], "rows" => [...] }
+db.explain(query, params = nil)       # -> plan Hash; never executes
+db.profile(query, params = nil)       # -> { "plan" => ..., "metrics" => ... }; PROFILE executes writes
 db.clear                              # -> nil
 db.node_count                         # -> Integer
 db.relationship_count                 # -> Integer
@@ -101,6 +104,37 @@ Hash keys on the output are always **strings**, matching the `lora-node`,
 symbol or string keys — both work for param names and for tagged
 constructor Hashes like `point`/`date`/...
 
+### Explain & Profile
+
+`db.explain` and `db.profile` are first-class methods alongside
+`db.execute`. They are intentionally *separate calls*, not a flag on
+`execute`, so plan inspection and runtime metrics must be requested
+explicitly.
+
+```ruby
+plan = db.explain(
+  "MATCH (p:Person) WHERE p.name = $name RETURN p",
+  { "name" => "Alice" }
+)
+plan["shape"]           # => "readOnly"
+plan["tree"]["operator"]
+
+profile = db.profile(
+  "MATCH (p:Person) WHERE p.name = $name RETURN p",
+  { "name" => "Alice" }
+)
+profile["metrics"]["total_elapsed_ns"]
+profile["metrics"]["per_operator"]   # per-step inclusive timing
+```
+
+`explain` never invokes the executor — calling it on a mutating query
+(`CREATE`, `MERGE`, `SET`, `DELETE`, `REMOVE`) leaves the graph
+untouched.
+
+> **`profile` executes the query for real.** Mutating queries are
+> persisted exactly as in `execute`. Use `explain` to inspect a
+> mutating plan without running it.
+
 ## Typed value model
 
 Identical contract to the other bindings:
@@ -156,16 +190,25 @@ replays committed writes before returning the handle.
 Call `db.close` before reopening the same archive inside one
 process.
 
-This first Ruby persistence slice intentionally stays small: the
-binding exposes archive-backed initialization plus the existing snapshot
-APIs, but not checkpoint, truncate, status, or sync-mode controls.
+For explicit WAL directories with managed snapshots, use `open_wal`:
+
+```ruby
+db = LoraRuby::Database.open_wal(
+  "./data/wal",
+  snapshot_dir: "./data/snapshots",
+  snapshot_every_commits: 1000,
+  snapshot_keep_old: 2,
+)
+```
+
+`snapshot_options` accepts the same compression/encryption options as
+`save_snapshot`.
 
 ## Concurrency (GVL release)
 
 `Database#execute` calls `rb_thread_call_without_gvl`, so other Ruby
-threads run while the engine is busy. Concurrent queries against the
-same `Database` serialise on an internal `Mutex`; parallel queries
-against **different** `Database` instances have no shared state.
+threads run while the engine is busy. Auto-commit reads can overlap on engine
+snapshots; write commits and explicit read-write transactions serialize.
 
 The engine has no cancellation hook, so we pass a `NULL` unblock
 function. A thread interrupted mid-query (`Thread#kill`) will observe
@@ -175,7 +218,7 @@ if you rely on cooperative cancellation.
 ## Local development
 
 ```bash
-cd crates/lora-ruby
+cd crates/bindings/lora-ruby
 bundle install
 bundle exec rake compile        # cargo build → lib/lora_ruby/lora_ruby.<ext>
 bundle exec rake test           # minitest
@@ -190,7 +233,7 @@ precompiled platform gem.
 
 ```
 lora-database (Rust, embedded)
-   └── crates/lora-ruby/                (gem root + cargo crate)
+   └── crates/bindings/lora-ruby/                (gem root + cargo crate)
           ├── Cargo.toml                 Rust workspace member
           ├── extconf.rb                 rb-sys / mkmf entry point
           ├── src/lib.rs                 <- Magnus / rb-sys bindings

data/lib/lora_ruby/types.rb

@@ -7,7 +7,7 @@ module LoraRuby
   # - Scalars pass through as Ruby natives (`nil`, `true`, `false`,
   #   `Integer`, `Float`, `String`).
   # - Lists and maps come back as `Array` / `Hash` (string keys).
-  # - Graph, temporal, and spatial values come back as plain `Hash`es
+  # - Graph, temporal, spatial, vector, and binary values come back as plain `Hash`es
   #   with a `"kind"` discriminator.
   #
   # If you want to narrow a value explicitly, use the `node?` / `point?`
@@ -56,6 +56,21 @@ module LoraRuby
       }
     end
 
+    # ------------------------------------------------------------------
+    # Binary / blob constructor — segmented bytes. The native extension
+    # accepts each segment as a Ruby String and preserves segment
+    # boundaries in WAL/snapshot storage.
+    # ------------------------------------------------------------------
+
+    def binary(segments)
+      copied = segments.map { |segment| segment.b.dup }
+      {
+        "kind"     => "binary",
+        "length"   => copied.sum(&:bytesize),
+        "segments" => copied,
+      }
+    end
+
     # ------------------------------------------------------------------
     # Spatial constructors — mirrors lora_python.cartesian / wgs84.
     # `cartesian(1, 2)` returns a 2D cartesian point; use `cartesian_3d`
@@ -122,6 +137,7 @@ module LoraRuby
     def path?(v)         = tagged?(v, "path")
     def point?(v)        = tagged?(v, "point")
     def vector?(v)       = tagged?(v, "vector")
+    def binary?(v)       = tagged?(v, "binary")
 
     def temporal?(v)
       return false unless v.is_a?(Hash)

data/lib/lora_ruby/version.rb

@@ -10,5 +10,5 @@ module LoraRuby
   # Guard against redefinition so re-requiring this file (or loading
   # both paths) doesn't emit a "warning: already initialized constant"
   # when the native extension loads second with the identical value.
-  VERSION = "0.5.6" unless const_defined?(:VERSION)
+  VERSION = "0.8.4" unless const_defined?(:VERSION)
 end

data/lib/lora_ruby.rb

@@ -32,8 +32,8 @@ module LoraRuby
   %i[
     date time localtime datetime localdatetime duration
     cartesian cartesian_3d wgs84 wgs84_3d
-    vector
-    node? relationship? path? point? temporal? vector?
+    vector binary
+    node? relationship? path? point? temporal? vector? binary?
   ].each do |m|
     define_singleton_method(m) do |*args, **kwargs|
       if kwargs.empty?

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lora-ruby
 version: !ruby/object:Gem::Version
-  version: 0.5.6
+  version: 0.8.4
 platform: x86_64-linux
 authors:
 - LoraDB, Inc.
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-04-27 00:00:00.000000000 Z
+date: 2026-05-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
@@ -73,9 +73,9 @@ licenses:
 - BUSL-1.1
 metadata:
   homepage_uri: https://github.com/lora-db/lora
-  source_code_uri: https://github.com/lora-db/lora/tree/main/crates/lora-ruby
+  source_code_uri: https://github.com/lora-db/lora/tree/main/crates/bindings/lora-ruby
   bug_tracker_uri: https://github.com/lora-db/lora/issues
-  documentation_uri: https://github.com/lora-db/lora/blob/main/crates/lora-ruby/README.md
+  documentation_uri: https://github.com/lora-db/lora/blob/main/crates/bindings/lora-ruby/README.md
   rubygems_mfa_required: 'true'
 post_install_message: 
 rdoc_options: []