lora-ruby 0.6.0-aarch64-linux → 0.8.5-aarch64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 625e87d729f6f0fe8cd122e0a87a4d2908445f9d5e4880177e2113e980d7a790
-  data.tar.gz: a3f3a29409f5d880a1f28a4e495a19414e2eb863bef9f59969485e4f249b6c16
+  metadata.gz: a128139ba04d8466e73a34ef354cc3a84099132ada4e557234c5f1920c4277ec
+  data.tar.gz: d3e675fb05ee688d489f141b255c1b03583bad37de896c18d0b39ca2cd43deef
 SHA512:
-  metadata.gz: 9041a08d3fec37fd16976e1ff2baa5f11e46cae0f3a2548656538ef845641be5c6cfdc0a8c1f4f806ec3974e4085d881e71ebf2cc901719c92dfb60e6b947f76
-  data.tar.gz: f2d582b1624f6293ecb8a72b175c80d1e9243b6f2f8866c313eb12675b5777e4e19596b98795ff51c0455147246598a56e10a27ba87f60b754e47b9e23990a88
+  metadata.gz: 20c93a57f4d488569210ed3c6d238af1dede85c90081dacb6bb76da3be8088455158e8a029a2063164ce6cae43464b352223845e8d3569472a4aa428ebc7241d
+  data.tar.gz: cf6b661c909a4302b2ececd6dce2ef392ed1fdc43662d9626e2e66a3eb01e0ba905c93b54a0029a76bb24834ade38d5b1cc802456a84c1143c31361b13680f80

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.
@@ -81,6 +81,8 @@ 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
@@ -102,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:
@@ -174,9 +207,8 @@ db = LoraRuby::Database.open_wal(
 ## 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
@@ -186,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
@@ -201,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/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.6.0" unless const_defined?(:VERSION)
+  VERSION = "0.8.5" unless const_defined?(:VERSION)
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: lora-ruby
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.8.5
 platform: aarch64-linux
 authors:
 - LoraDB, Inc.
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2026-04-29 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: []