lora-ruby 0.6.0-x86_64-linux → 0.8.4-x86_64-linux

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d16b151caa8498f6f7f535201b024ae763a77409fe6e00cdfefb73ecdc4134bf
-  data.tar.gz: b77d4d4c60e6f6e4d81ea49d6f66bc11e8373f4efd918599bc99cabb1c733425
+  metadata.gz: d80ff16c35cd0c2c9a41563b78cf6eb4efd920da2ab37d72db9364b3ab1dbcf2
+  data.tar.gz: b05c7f6b6f29cdb116f0f0f6b771074ec613e460905a7a015c8b8705034e6f40
 SHA512:
-  metadata.gz: 0b72af87acb141f9c816ceb921dde8d44857699e41241ea966d8b1d67e08e9d5bf681321d0fa40058f42e4a23e70328f55655285e5d8e32fcb1f2e9791b88f23
-  data.tar.gz: a5111d6e8cc41ad52ee2a06bd8f12512ce4ba9eb49a7de600980cc159608da8adca3c8c72c3a9d018c197e5d56d4bb47dbb23b82e7aa9ffb6281d17c629e397f
+  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.
@@ -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.4" 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.4
 platform: x86_64-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: []