pglpg 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64d4bfb95eeacd8297e72c8dc02b95bcda6354e5c3c157655483c13d78e9b9a8
-  data.tar.gz: c75cbedcd42f7fe07265f8aecfea1e78adc5e44f3651587b069955ea6c47f254
+  metadata.gz: 0ed878f97c7dcf3ffb630de85d798896dcbb6b0729e176ec410eb6383bd4659e
+  data.tar.gz: '055047480e44e5ff29ccaddce6d3ed730397dcffa243541c42e4c1e5b3c607ac'
 SHA512:
-  metadata.gz: 1b0d31c4236eac2f7b3cb22b65d7650c1a01d3687ea5505b44e64b540e54f9d6e880344e2bbc1f90a6bb1512dcfdaad5c06ea0dc58ea621f768e82c50926e513
-  data.tar.gz: a8bcb6da10e7779df9409d7dc5923a0f172177d4d2acb8f695a347adf89019bc1d04b4a5187b8c85560b7043b171bfc0bc464c1256189c4ae43db59d5c4f0a5d
+  metadata.gz: 516ba2fc4c42f933616e5b2ffae77a4c320f6a1bd400dcd332addb5884f19499bd97d8ce8ceebdaafc9ceba3e52ed822abe5c994e2e9aa072b0ec615a2908ecf
+  data.tar.gz: 0707c16c9bc2e84093a9423531eb802460c291f61362f5af788074a356f46c264f83419bc815399360231d943ab3f181f51f09247a24442f5bcb02d77fc04b72

data/CHANGELOG.md

@@ -1,5 +1,162 @@
 # Changelog
 
+## 0.2.0 (2026-10-30)
+
+### Breaking
+
+- Symmetric edge types use `both`; `out` and `in` reject them, and `both`
+  rejects directed types. After adding a symmetric type, run
+  `Kg.storage.sync_constraints!` to install its canonical-endpoint constraint.
+- Adopting scoped keys requires a required string scope property, both scope
+  and key in lookups and trusted upserts, and a transactional backfill with
+  `sync_constraints!` on the same connection. Interactive caller-chosen scoped
+  keys require an explicit `key_scope_allowed` occupancy grant. Existing
+  unscoped key declarations keep their contract.
+
+### Security
+
+- Database constraint failures on refused writes no longer expose the original
+  database exception through `Exception#cause`, including unscoped writes.
+
+### Added
+
+- Scoped keys (ADR-0012): `key :uid, scope: :namespace` enforces a required
+  string namespace/key pair across the declaring type and subtypes. Interactive
+  caller-chosen keys require an explicit `key_scope_allowed` grant to learn
+  occupancy within that graph/domain/scope, including hidden collisions. The
+  grant gives no row access and has no SQL-time revocation guarantee. Trusted
+  upserts and `find_node` require both parts; scope and key remain immutable.
+  Existing schemas require a transactional backfill and constraint migration.
+
+- Add `with_associations` to model relations for batched, visibility-aware eager loading (ADR-0011). Preloaded associations are materialized reads and can become stale; reload, save, or destroy clears that instance's cache. Each batch uses a separate database snapshot and raises `TooManyRows` when its distinct owner–target pairs exceed `max_rows`.
+
+- Model layer, reads (ADR-0010; `require "pglpg/model"`):
+  - `Pglpg::Model::Node` and `Pglpg::Model::Edge` are ActiveModel classes
+    bound to a graph and a schema type with `graph Kg, type: :Person`. Their
+    attributes are the type's properties and the graph's application
+    columns. Assignment is strict: no form coercion.
+  - Declaring a model rejects a second model for the same type (a class of
+    the same name replaces it, for code reloading), a property named like an
+    application column or a model method, and a model extending another
+    model off the schema's inheritance.
+  - `Model.in(ctx)` returns a `Pglpg::Model::Relation` with `where`, `order`,
+    `limit`, `offset`, `count`, `exists?`, `first` and `find_by`. It compiles
+    to a `Pglpg::Query`, so visibility, ordering, `max_rows` and timeouts
+    apply as there. Edge relations return each symmetric edge once.
+  - `Relation#find(ref)` takes a `Ref` or its String form and raises
+    `Pglpg::Model::RecordNotFound` for a missing, hidden or wrong-type
+    element alike.
+  - A node loads as the model registered for its concrete type, else as the
+    queried model; `schema_type` names the stored type and
+    `extra_properties` holds properties the model doesn't declare.
+  - The shared leak suite observes models, relations and `find`.
+- Model layer, writes (ADR-0010):
+  - `Relation#new` / `#build`, `#create` and `#create!` build records bound
+    to the relation's context. Edge records take `source:` and `target:` (a
+    node Ref or model); they can't change once stored.
+  - `save` / `save!` validate, then insert a new record or update only its
+    changed attributes through the context's guarded write API. `save`
+    returns false on validation errors; `save!` raises
+    `Pglpg::Model::RecordInvalid`. Refusals, timeouts and database errors
+    raise, and changes survive any failure. Without changes, no statement
+    runs.
+  - Schema validations: property values, required properties and required
+    columns. Keys are generated: an assigned key is an error on create, a
+    changed key on update. Abstract types can't be created.
+  - `save(writer:)` and `destroy(writer:)` accept only the record's own
+    context's trusted writer (`ArgumentError` otherwise), for trusted-only
+    writes such as pair-unique edges; it never permits assigning a key.
+  - `destroy` deletes an edge, or a node through the trusted writer only;
+    `destroyed?`.
+  - `reload` replaces attributes, timestamps and the dirty baseline, and
+    raises `RecordNotFound` without changing the record when the element
+    is missing or hidden.
+  - After a create, generated keys and timestamps are unknown until
+    `reload`. A caller's rollback is not tracked.
+- Model layer, associations (ADR-0010 §5):
+  - `has_many name, :out | :in | :both, edge:, label: nil, model: nil` on a
+    node model defines a method returning a `Pglpg::Model::AssociationRelation`.
+    `:both` is for symmetric types, `:out` / `:in` for directed ones. The
+    target label defaults to the edge type's other endpoint and the model to
+    the one registered for it. Declaring checks the direction, that the
+    owner can be an endpoint, and name clashes; associations are inherited.
+  - A target query returns each visible target once: duplicates are removed
+    before `order`, `limit`, `offset`, `count` and `exists?`. `rel_where`
+    filters on edge properties ("at least one matching visible edge");
+    `rel_order` raises there.
+  - `with_rel` returns a `Pglpg::Model::BindingRelation`: one
+    `[target, edge]` pair per matching edge, counted and paginated as pairs,
+    with `rel_order`. It must come before `order`, `limit` or `offset`.
+    `each_with_rel` enumerates it. Edges load as the registered edge model.
+  - Associations need a saved owner, start from it (so its visibility
+    applies) and can't build records yet.
+  - The shared leak suite observes every association of every visible owner:
+    targets, counts, `exists?`, `first`, pagination, `rel_where` and pairs.
+- Model layer, `pluck` (ADR-0010 §5):
+  - `Relation#pluck(*names)` returns attribute values (or `:id`, `:ref`) per
+    element, in the relation's order: a value for one name, an Array for
+    several. Elements are chosen first and projected afterwards, so two
+    targets with equal values give two values.
+  - `BindingRelation#pluck(*names, rel: [])` gives one entry per pair:
+    the target's names, then the edge's `rel` names.
+  - Unknown names raise `ArgumentError` before any query runs; `max_rows`
+    applies as for `to_a`.
+  - The shared leak suite also observes `pluck` on relations, associations
+    and pairs.
+- `Context#reachable(from:, via:, max_depth:, max_nodes:, direction: :out, deadline: nil)`
+  returns a `Pglpg::Reachability`: visible nodes with their minimum depth,
+  ordered by depth then id, plus `complete` and `stopped_at_depth`.
+  - Runs as one recursive CTE that computes one BFS level per step (ADR-0009),
+    so it sees one snapshot at any isolation level.
+  - The start node is never returned; a hidden start and a missing one give
+    the same empty, complete result.
+  - `direction:` follows the `match` rule from ADR-0008, and a `via` list may
+    not mix directed and symmetric types.
+  - `max_nodes` may not exceed `max_rows`. `deadline` (seconds) can only
+    shorten the configured `statement_timeout`.
+  - The shared leak suite observes `reachable` from every visible node.
+- `Context#read` takes a `timeout:` in milliseconds (internal), and every read
+  now runs in a savepoint, also with `statement_timeout: nil`. A timeout set
+  by the session itself no longer leaves the caller's transaction aborted.
+- The shared leak suite keeps its `reachable` budgets within `max_rows`.
+- The benchmark is rebuilt for CI (task 36367): seeded, versioned 1m,
+  hub-heavy and 10m fixtures with a manifest. Its cells cover viewers L2 and
+  L4, with starts each viewer can see, and include `reachable`. It gates
+  per-cell bounds in `bench/bounds.yml`, and compares buffers and latency
+  with a baseline revision. Buffers come from JSON plans and fail closed, and
+  a self-test proves that the gate fails. `bench/run.rb` is replaced by
+  `bench/measure.rb` and `bench/gate.rb`. A new `bench.yml` workflow runs the
+  full fixtures. The CI benchmark step no longer hides a failure behind
+  `tee`.
+- Symmetric edge types (ADR-0008): `edge name, from:, to:, symmetric: true`,
+  with `allow_self_loops: true` to permit self-loops (off by default).
+  - Each edge is stored once with `source_id < target_id` (`<=` with self-loops),
+    enforced by a generated `CHECK`; `sync_constraints!` adds it. Writes accept
+    the endpoints in either order, and `WriteRequest#from` / `#to` carry the
+    canonical order. `unique: :pair` covers the unordered pair.
+  - One endpoint carries `from` and the other `to`, in either order.
+  - `Query#both` follows a symmetric edge from either end (GQL `~[ ]~`). With
+    no endpoint fixed, each edge binds once per orientation (once for a
+    self-loop); use `return(:edge).distinct` to list edges once.
+  - **Breaking:** `out` and `in` raise `ArgumentError` for symmetric types, and
+    `both` raises it for directed types. `symmetric:` no longer raises
+    `SchemaError`.
+  - `Edge#symmetric?` and `Edge#other(ref)`.
+  - The shared leak suite adds symmetric cases: hidden bridges and hidden
+    nodes stored at either end of an edge.
+- The benchmark adds symmetric 1- and 2-hop shapes and checks the buffers of
+  the symmetric hub query.
+
+### Fixed
+
+- Storage DDL is atomic: `sync_constraints!` and the entire `create!` operation
+  use a transaction on their supplied connection, or a savepoint in an existing
+  ActiveRecord transaction. A failed call restores its DDL and leaves a healthy
+  caller transaction usable. Outside a transaction, each call commits its own
+  transaction. Application backfills still need an explicit outer transaction
+  on the same connection to be rolled back with a failed schema transition.
+
+
 ## 0.1.0 (2026-10-28)
 
 First version, following the accepted 0.1 baseline (knowen.md bb topic 145).

data/README.md

@@ -8,10 +8,22 @@ ordinary tables, written inside your own transactions. Every query applies
 your visibility policy to every node and edge on every hop, so hidden records
 never act as bridges and never show up in counts or limits.
 
-Status: **0.1, pre-release.** The design and its decisions live in the
+Status: **0.2.0 release candidate.** Publication awaits the
+[release gate](https://knowen.md/nodes/36368) and maintainer review. The design and its decisions live in the
 [pglpg.md](https://knowen.md/nodes/36325) knowledge base. Requires Ruby ≥ 4.0,
 ActiveRecord ≥ 8.1 and PostgreSQL ≥ 18: the versions CI tests.
 
+## Install
+
+After publication:
+
+```ruby
+gem "pglpg", "~> 0.2.0"
+```
+
+Before 1.0, minor releases may break compatibility. Read the
+[0.2.0 upgrade notes](CHANGELOG.md) before upgrading from 0.1.
+
 ## Define a graph
 
 ```ruby
@@ -36,9 +48,14 @@ Kg = Pglpg::Graph.define(:kg) do
     property :role, :string
   end
   edge :KNOWS, from: :Person, to: :Person
+  edge :FRIEND, from: :Person, to: :Person, symmetric: true  # undirected
 end
 ```
 
+A `symmetric: true` edge type is undirected: each edge is stored once, smaller
+node id first, and writes accept the endpoints in either order. Self-loops are
+refused unless the type sets `allow_self_loops: true`.
+
 Property types: `string integer float decimal boolean date datetime enum list`
 (`enum` takes `values:`, `list` takes `of:`). Types are closed: undeclared
 properties are rejected. A nil value means the property is absent.
@@ -118,6 +135,10 @@ rows.first[:q]   # => #<Pglpg::Node ...>
 g.find(ref)                         # visible node or edge, else nil
 g.find_node(:Person, uid: "PER-12")
 query.count; query.exists?; query.first; query.distinct; query.explain(analyze: true)
+
+# Symmetric edge types use both (out and in refuse them). Each edge binds once
+# per orientation, so list edges once with return(:f).distinct.
+g.match.node(:p, ref: ann).both(:FRIEND, :q, :Person, edge: :f)
 ```
 
 Conditions are structured only: a value (equality), an array (one of), nil
@@ -125,6 +146,49 @@ Conditions are structured only: a value (equality), an array (one of), nil
 raise `Pglpg::TooManyRows` beyond `max_rows` (default 1000); reads run under
 `statement_timeout` (default 5 s) and raise `Pglpg::QueryTimeout`.
 
+## Reachability
+
+```ruby
+r = g.reachable(from: ann, via: %i[KNOWS], max_depth: 3, max_nodes: 500, deadline: 2.0)
+r.nodes             # => [[ref, 1], [ref, 1], [ref, 2], …]  by depth, then id
+r.complete?         # false when more visible nodes are reachable within max_depth
+r.stopped_at_depth  # depth of the last returned node when incomplete, else nil
+
+g.reachable(from: ann, via: %i[KNOWS], direction: :in, max_depth: 2, max_nodes: 100)
+g.reachable(from: ann, via: %i[FRIEND], direction: :both, max_depth: 2, max_nodes: 100)
+```
+
+Each visible node comes once, at its minimum depth; the start node never does.
+Hidden nodes and edges are never traversed, and a hidden or missing start gives
+an empty, complete result. `via` lists edge types that may be followed at any
+hop. `direction:` follows the same rule as `match`: `:both` takes only
+symmetric types, `:out` (the default) and `:in` only directed ones.
+`max_nodes` may not exceed `max_rows`.
+
+The traversal is one SQL statement (ADR-0009), so it sees one snapshot at any
+isolation level. `deadline` is in seconds and can only shorten the configured
+`statement_timeout`; with no timeout configured it applies alone. Running out
+of time raises `Pglpg::QueryTimeout` and leaves your transaction usable.
+
+## Models and eager loading
+
+`require "pglpg/model"` adds optional ActiveModel records bound to a graph and
+schema type. Context-bound relations support reads, guarded saves, associations,
+`pluck` and visibility-aware batched eager loading with `with_associations`.
+See the [API contract](https://knowen.md/nodes/36329) for examples, cache lifetime
+and row limits.
+
+## Scoped keys
+
+A type can declare `key :uid, scope: :namespace` when both properties are
+required strings. Uniqueness covers the scope/key pair across the type and its
+subtypes. `find_node` and trusted upserts require both values. An interactive
+caller-chosen key needs an explicit `key_scope_allowed` grant: it permits
+learning occupancy in that scope, including hidden collisions, without granting
+row access. Scope and key are immutable. Existing data needs a transactional
+backfill and constraint migration; see the
+[API contract](https://knowen.md/nodes/36329).
+
 ## Leak specs for your policy
 
 ```ruby

data/lib/pglpg/configuration.rb

@@ -2,7 +2,7 @@
 
 module Pglpg
   # Global settings. Each graph can override visibility, write_policy and
-  # trusted_writer_allowed when it is defined.
+  # trusted_writer_allowed and key_scope_allowed when it is defined.
   class Configuration
     # Required. An object with +node(table, viewer)+ and +edge(table, viewer)+,
     # each returning an Arel condition on the given Arel::Table.
@@ -16,6 +16,9 @@ module Pglpg
     # may be used for that context. Unset means the capability is never granted.
     attr_accessor :trusted_writer_allowed
 
+    # Explicit permission to learn key occupancy in a scoped key domain.
+    attr_accessor :key_scope_allowed
+
     # The ActiveRecord class whose connection pglpg uses.
     attr_accessor :connection_class
 

data/lib/pglpg/context.rb

@@ -40,14 +40,25 @@ module Pglpg
     # The visible node of +type+ (or a subtype) with the given key, or nil.
     #   ctx.find_node(:Person, uid: "PER-12")
     def find_node(type, **key)
+      key = key.transform_keys(&:to_sym)
       node_type = graph.type.node_type!(type)
-      unless node_type.key && key.keys == [node_type.key.property]
-        raise ArgumentError, "#{type} is looked up by #{node_type.key&.property.inspect}"
+      unless node_type.key && key.keys.sort == node_type.key.properties.sort
+        raise ArgumentError, "#{type} is looked up by #{node_type.key&.properties.inspect}"
       end
 
       match.node(:n, type, **key).first&.fetch(:n)
     end
 
+    # Visible nodes reachable from +from+ within +max_depth+ hops over the
+    # edge types in +via+, each with its minimum depth (a Reachability).
+    # Hidden nodes and edges are never traversed. The traversal is one
+    # statement; +deadline+ (seconds) can only shorten the configured
+    # statement timeout. See ADR-0009.
+    #   ctx.reachable(from: ref, via: %i[KNOWS], max_depth: 3, max_nodes: 500)
+    def reachable(from:, via:, max_depth:, max_nodes:, direction: :out, deadline: nil)
+      Reachable.new(self, from:, via:, direction:, max_depth:, max_nodes:, deadline:).call
+    end
+
     def insert_node(type, properties: {}, attrs: {}) = writer.insert_node(type, properties:, attrs:)
 
     def update_node(ref, properties: {}, attrs: {}) = writer.update_node(ref, properties:, attrs:)
@@ -88,13 +99,15 @@ module Pglpg
       sql << ")"
     end
 
-    # Runs a read under the configured statement timeout.
-    def read(sql)
+    # Runs a read under +timeout+ (ms; default: the configured statement
+    # timeout). nil leaves the session's timeout as it is. The read always
+    # runs in a savepoint, so a timeout (ours or the session's) never leaves
+    # the caller's transaction aborted.
+    def read(sql, timeout: Pglpg.configuration.statement_timeout)
       graph.with_connection do |c|
-        timeout = Pglpg.configuration.statement_timeout
-        next c.select_all(sql.to_s, "Pglpg", sql.binds).to_a if timeout.nil?
-
         c.transaction(requires_new: true) do
+          next c.select_all(sql.to_s, "Pglpg", sql.binds).to_a if timeout.nil?
+
           previous = c.select_value("SELECT current_setting('statement_timeout')")
           c.select_value("SELECT set_config('statement_timeout', '#{Integer(timeout)}', true)")
           rows = c.select_all(sql.to_s, "Pglpg", sql.binds).to_a

data/lib/pglpg/element.rb

@@ -31,11 +31,13 @@ module Pglpg
     def inspect = "#<Pglpg::Node #{ref} #{key_label} #{properties.inspect}>"
   end
 
-  # An edge read from the graph. Values are frozen.
+  # An edge read from the graph. Values are frozen. For a symmetric edge type,
+  # source and target are the stored (canonical) endpoints and carry no
+  # direction; use #other to walk from one end to the other.
   class Edge
     attr_reader :ref, :type, :source, :target, :properties, :attrs, :created_at, :updated_at
 
-    def initialize(ref:, type:, source:, target:, properties:, attrs:, created_at:, updated_at:)
+    def initialize(ref:, type:, source:, target:, properties:, attrs:, created_at:, updated_at:, symmetric: false)
       @ref = ref
       @type = type
       @source = source
@@ -44,6 +46,7 @@ module Pglpg
       @attrs = attrs
       @created_at = created_at
       @updated_at = updated_at
+      @symmetric = symmetric
       freeze
     end
 
@@ -51,12 +54,22 @@ module Pglpg
 
     def [](name) = properties[name.to_sym]
 
+    def symmetric? = @symmetric
+
+    # The endpoint opposite +ref+ (the same node for a self-loop).
+    def other(ref)
+      return target if ref == source
+      return source if ref == target
+
+      raise ArgumentError, "#{ref} is not an endpoint of #{self.ref}"
+    end
+
     def ==(other) = other.is_a?(Edge) && other.ref == ref
 
     alias eql? ==
 
     def hash = ref.hash
 
-    def inspect = "#<Pglpg::Edge #{ref} #{type} #{source.id}->#{target.id} #{properties.inspect}>"
+    def inspect = "#<Pglpg::Edge #{ref} #{type} #{source.id}#{symmetric? ? "--" : "->"}#{target.id} #{properties.inspect}>"
   end
 end

data/lib/pglpg/graph.rb

@@ -18,15 +18,15 @@ module Pglpg
     attr_reader :name, :type, :storage
 
     def self.define(name, nodes_table: nil, edges_table: nil, visibility: nil, write_policy: nil,
-                    trusted_writer_allowed: nil, connection_class: nil, &block)
+                    trusted_writer_allowed: nil, key_scope_allowed: nil, connection_class: nil, &block)
       type = Schema::GraphType.new
       Schema::Builder.new(type).instance_eval(&block) if block
       type.resolve!
       new(name, type, nodes_table: nodes_table || "#{name}_nodes", edges_table: edges_table || "#{name}_edges",
-                      visibility:, write_policy:, trusted_writer_allowed:, connection_class:)
+                      visibility:, write_policy:, trusted_writer_allowed:, key_scope_allowed:, connection_class:)
     end
 
-    def initialize(name, type, nodes_table:, edges_table:, visibility:, write_policy:, trusted_writer_allowed:,
+    def initialize(name, type, nodes_table:, edges_table:, visibility:, write_policy:, trusted_writer_allowed:, key_scope_allowed:,
                    connection_class:)
       @name = Schema.check_name!(name, "graph")
       @type = type
@@ -34,6 +34,7 @@ module Pglpg
       @visibility = visibility
       @write_policy = write_policy
       @trusted_writer_allowed = trusted_writer_allowed
+      @key_scope_allowed = key_scope_allowed
       @connection_class = connection_class
       freeze
     end
@@ -77,6 +78,8 @@ module Pglpg
 
     def trusted_writer_allowed = @trusted_writer_allowed || Pglpg.configuration.trusted_writer_allowed
 
+    def key_scope_allowed = @key_scope_allowed.nil? ? Pglpg.configuration.key_scope_allowed : @key_scope_allowed
+
     def connection_class = @connection_class || Pglpg.configuration.connection_class || ActiveRecord::Base
 
     def with_connection(&) = connection_class.with_connection(&)
@@ -111,7 +114,8 @@ module Pglpg
         source: ref(:node, row["source_id"]), target: ref(:node, row["target_id"]),
         properties: edge_type ? edge_type.decode_properties(row["properties"]) : row["properties"].transform_keys(&:to_sym).freeze,
         attrs: decode_attrs(type.edge_columns, row),
-        created_at: Time.iso8601(row["created_at"]), updated_at: Time.iso8601(row["updated_at"])
+        created_at: Time.iso8601(row["created_at"]), updated_at: Time.iso8601(row["updated_at"]),
+        symmetric: edge_type&.symmetric? || false
       )
     end