pglpg 0.1.0

data/lib/pglpg/schema/node_type.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Pglpg
+  module Schema
+    # A node type: a key label, inherited labels and property types
+    # (GQL node types, PG-Schema inheritance).
+    class NodeType < ElementType
+      # An exclusive, mandatory key on one property (PG-Keys). +generator+
+      # produces values for interactive inserts, which never accept a
+      # caller-chosen key.
+      Key = Struct.new(:property, :declared_on, :generator, keyword_init: true) do
+        def generate(type) = generator.call(type)
+      end
+
+      DEFAULT_KEY_GENERATOR = ->(_type) { SecureRandom.uuid }
+
+      attr_reader :parents, :labels, :key, :ancestors
+
+      def initialize(name, extends: [], abstract: false)
+        super(name)
+        @parents = Array(extends).map { Schema.check_name!(_1, "type") }.freeze
+        @abstract = abstract ? true : false
+        @own_key = nil
+      end
+
+      def abstract? = @abstract
+
+      def key_property(name, generate: nil)
+        raise SchemaError, "#{self.name} declares more than one key" if @own_key
+        raise SchemaError, "key generator for #{self.name} must respond to call" if generate && !generate.respond_to?(:call)
+
+        @own_key = Key.new(property: name.to_sym, declared_on: self.name, generator: generate || DEFAULT_KEY_GENERATOR)
+      end
+
+      def own_key = @own_key
+
+      # Called once the graph type is complete.
+      def resolve!(graph_type, stack = [])
+        return if @resolved
+        raise SchemaError, "inheritance cycle: #{(stack + [name]).join(" < ")}" if stack.include?(name)
+
+        parent_types = parents.map do |p|
+          graph_type.node_types.fetch(p) { raise SchemaError, "#{name} extends unknown node type #{p}" }
+        end
+        parent_types.each { _1.resolve!(graph_type, stack + [name]) }
+
+        @ancestors = parent_types.flat_map { [_1.name, *_1.ancestors] }.uniq.freeze
+        @labels = ([name] + @ancestors).map(&:to_s).sort.freeze
+        @properties = merge_properties(parent_types)
+        @key = resolve_key(parent_types)
+        @resolved = true
+        freeze
+      end
+
+      # True when nodes of this type carry +label+.
+      def label?(label) = labels.include?(label.to_s)
+
+      private
+
+      def merge_properties(parent_types)
+        merged = {}
+        (parent_types.map(&:properties) + [own_properties]).each do |props|
+          props.each do |n, prop|
+            if merged.key?(n) && !merged[n].same_definition?(prop)
+              raise SchemaError, "#{name} inherits conflicting definitions of #{n}"
+            end
+
+            merged[n] = prop
+          end
+        end
+        merged.freeze
+      end
+
+      def resolve_key(parent_types)
+        keys = (parent_types.map(&:key) + [@own_key]).compact.uniq(&:declared_on)
+        raise SchemaError, "#{name} has more than one key (#{keys.map(&:declared_on).join(", ")})" if keys.size > 1
+
+        key = keys.first
+        return nil unless key
+
+        prop = @properties[key.property]
+        raise SchemaError, "key #{key.declared_on}.#{key.property} is not a declared property" unless prop
+        raise SchemaError, "key #{key.declared_on}.#{key.property} must be required" unless prop.required?
+        raise SchemaError, "key #{key.declared_on}.#{key.property} must be a string" unless prop.type == :string
+
+        key
+      end
+    end
+  end
+end

data/lib/pglpg/schema/property.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+require "bigdecimal"
+require "date"
+require "time"
+
+module Pglpg
+  module Schema
+    # A declared property: name, value type and whether it is required.
+    # Values are stored in the +properties+ jsonb column. A nil value means the
+    # property is absent, as in GQL.
+    class Property
+      SCALAR_TYPES = %i[string integer float decimal boolean date datetime enum].freeze
+      TYPES = (SCALAR_TYPES + %i[list]).freeze
+
+      # jsonb_typeof of a stored value, per type.
+      JSON_TYPES = {
+        string: "string", integer: "number", float: "number", decimal: "string",
+        boolean: "boolean", date: "string", datetime: "string", enum: "string", list: "array"
+      }.freeze
+
+      # SQL cast used to compare a stored value (extracted as text).
+      SQL_CASTS = {
+        string: "text", integer: "numeric", float: "double precision", decimal: "numeric",
+        boolean: "boolean", date: "date", datetime: "timestamptz", enum: "text"
+      }.freeze
+
+      attr_reader :name, :type, :values, :of
+
+      def initialize(name, type, required: false, values: nil, of: nil)
+        @name = name.to_sym
+        @type = type.to_sym
+        @required = required ? true : false
+        @values = values&.map(&:to_s)&.freeze
+        @of = of&.to_sym
+        check!
+        freeze
+      end
+
+      def required? = @required
+
+      def json_type = JSON_TYPES.fetch(type)
+
+      def sql_cast = SQL_CASTS.fetch(type)
+
+      def comparable? = type != :list
+
+      def same_definition?(other)
+        other.type == type && other.required? == required? && other.values == values && other.of == of
+      end
+
+      # Validates a Ruby value and returns its JSON form. nil stays nil.
+      def encode(value)
+        return nil if value.nil?
+        return encode_scalar(type, value) unless type == :list
+        raise ValidationError, "#{name} must be an Array" unless value.is_a?(Array)
+
+        value.map do |v|
+          raise ValidationError, "#{name} must not contain nil" if v.nil?
+
+          encode_scalar(of, v)
+        end
+      end
+
+      # Turns a stored JSON value back into Ruby.
+      def decode(json)
+        return nil if json.nil?
+        return decode_scalar(type, json) unless type == :list
+
+        json.map { |v| decode_scalar(of, v) }
+      end
+
+      private
+
+      def check!
+        raise SchemaError, "unknown property type #{type.inspect} for #{name}" unless TYPES.include?(type)
+        if type == :enum && (values.nil? || values.empty?)
+          raise SchemaError, "enum property #{name} needs values:"
+        end
+        return unless type == :list
+        return if SCALAR_TYPES.include?(of) && of != :enum
+
+        raise SchemaError, "list property #{name} needs of: with a scalar type"
+      end
+
+      def encode_scalar(t, v)
+        case t
+        when :string
+          return v if v.is_a?(String)
+        when :integer
+          return v if v.is_a?(Integer)
+        when :float
+          return v.to_f if v.is_a?(Numeric) && !v.is_a?(BigDecimal) && v.to_f.finite?
+        when :decimal
+          return v.to_s("F") if v.is_a?(BigDecimal) && v.finite?
+          return BigDecimal(v).to_s("F") if v.is_a?(Integer)
+        when :boolean
+          return v if [true, false].include?(v)
+        when :date
+          return v.iso8601 if v.instance_of?(Date)
+        when :datetime
+          return v.to_time.utc.iso8601(6) if v.is_a?(Time) || v.is_a?(DateTime) || time_with_zone?(v)
+        when :enum
+          return v.to_s if (v.is_a?(String) || v.is_a?(Symbol)) && values.include?(v.to_s)
+        end
+        raise ValidationError, "invalid #{t} value for #{name}: #{v.inspect}"
+      end
+
+      def time_with_zone?(v)
+        defined?(ActiveSupport::TimeWithZone) && v.is_a?(ActiveSupport::TimeWithZone)
+      end
+
+      def decode_scalar(t, v)
+        case t
+        when :decimal then BigDecimal(v)
+        when :date then Date.iso8601(v)
+        when :datetime then Time.iso8601(v)
+        else v
+        end
+      end
+    end
+  end
+end

data/lib/pglpg/sql.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "pg"
+
+module Pglpg
+  # Builds one SQL statement with numbered bind parameters. It doubles as an
+  # Arel collector, so policy conditions (Arel nodes) compile straight into
+  # the statement and keep their own binds.
+  class Sql
+    ARRAY_ENCODER = PG::TextEncoder::Array.new
+
+    attr_reader :binds
+    attr_accessor :preparable, :retryable
+
+    def initialize(connection)
+      @connection = connection
+      @parts = []
+      @binds = []
+    end
+
+    def <<(str)
+      @parts << str
+      self
+    end
+
+    # Appends a bound value, optionally with a cast: "$3::jsonb".
+    def bind(value, cast = nil)
+      add_bind(ActiveRecord::Relation::QueryAttribute.new("", value, ActiveModel::Type::Value.new))
+      self << "::#{cast}" if cast
+      self
+    end
+
+    def bind_json(value) = bind(JSON.generate(value), "jsonb")
+
+    def bind_text_array(values) = bind(ARRAY_ENCODER.encode(values.map(&:to_s)), "text[]")
+
+    def ident(name) = self << @connection.quote_column_name(name.to_s)
+
+    def table(name) = self << @connection.quote_table_name(name.to_s)
+
+    # A schema-defined string (type or label name) as a SQL literal. Used where
+    # PostgreSQL needs a constant, such as ON CONFLICT index inference.
+    def literal(str) = self << @connection.quote(str.to_s)
+
+    # Compiles an Arel node into the statement.
+    def arel(node)
+      @connection.visitor.compile(node, self)
+      self
+    end
+
+    # Arel collector interface.
+    def add_bind(attribute, &)
+      @binds << attribute
+      self << "$#{@binds.size}"
+    end
+
+    def add_binds(attributes, _proc_for_binds = nil, &)
+      attributes.each_with_index do |attribute, i|
+        self << ", " if i.positive?
+        add_bind(attribute)
+      end
+      self
+    end
+
+    def value = self
+
+    # Puts +str+ before the statement built so far (binds keep their numbers).
+    def prepend(str)
+      @parts.unshift(str)
+      self
+    end
+
+    def to_s = @parts.join
+  end
+end

data/lib/pglpg/storage.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Pglpg
+  # The two tables of a graph, their indexes and the constraints generated
+  # from the graph type.
+  #
+  #   Kg.storage.create!          # in a migration: tables, indexes, constraints
+  #   Kg.storage.sync_constraints! # after a graph type change
+  #   Kg.storage.relabel!         # after inherited labels change
+  #   Kg.storage.label_drift      # => {} when stored labels match the schema
+  class Storage
+    NAME_LIMIT = 63
+    MIN_SERVER_VERSION = 180_000
+
+    attr_reader :graph, :nodes_table, :edges_table
+
+    def initialize(graph, nodes_table:, edges_table:)
+      @graph = graph
+      @nodes_table = nodes_table.to_s
+      @edges_table = edges_table.to_s
+    end
+
+    def create!(connection = graph.connection)
+      if connection.database_version < MIN_SERVER_VERSION
+        raise ConfigurationError, "pglpg needs PostgreSQL 18 or later"
+      end
+
+      tables_sql(connection).each { connection.execute(_1) }
+      sync_constraints!(connection)
+    end
+
+    def drop!(connection = graph.connection)
+      connection.execute("DROP TABLE IF EXISTS #{q(connection, edges_table)}, #{q(connection, nodes_table)}")
+    end
+
+    def tables_sql(connection = graph.connection)
+      n = q(connection, nodes_table)
+      e = q(connection, edges_table)
+      [
+        <<~SQL,
+          CREATE TABLE #{n} (
+            id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+            key_label text NOT NULL,
+            labels text[] NOT NULL,
+            properties jsonb NOT NULL DEFAULT '{}',
+            #{columns_sql(connection, type.node_columns)}created_at timestamptz NOT NULL DEFAULT now(),
+            updated_at timestamptz NOT NULL DEFAULT now(),
+            CHECK (labels @> ARRAY[key_label]),
+            CHECK (jsonb_typeof(properties) = 'object')
+          )
+        SQL
+        <<~SQL,
+          CREATE TABLE #{e} (
+            id bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+            type text NOT NULL,
+            source_id bigint NOT NULL REFERENCES #{n} (id) ON DELETE RESTRICT,
+            target_id bigint NOT NULL REFERENCES #{n} (id) ON DELETE RESTRICT,
+            properties jsonb NOT NULL DEFAULT '{}',
+            #{columns_sql(connection, type.edge_columns)}created_at timestamptz NOT NULL DEFAULT now(),
+            updated_at timestamptz NOT NULL DEFAULT now(),
+            CHECK (jsonb_typeof(properties) = 'object')
+          )
+        SQL
+        "CREATE INDEX #{q(connection, "#{nodes_table}_labels")} ON #{n} USING gin (labels)",
+        "CREATE INDEX #{q(connection, "#{nodes_table}_properties")} ON #{n} USING gin (properties jsonb_path_ops)",
+        "CREATE INDEX #{q(connection, "#{edges_table}_source")} ON #{e} (source_id, type) INCLUDE (#{covering(connection, "target_id")})",
+        "CREATE INDEX #{q(connection, "#{edges_table}_target")} ON #{e} (target_id, type) INCLUDE (#{covering(connection, "source_id")})",
+        "CREATE INDEX #{q(connection, "#{edges_table}_properties")} ON #{e} USING gin (properties jsonb_path_ops)"
+      ]
+    end
+
+    # The constraints the graph type requires, by name. Names carry a digest
+    # of the definition, so a changed definition gets a new name.
+    def constraints(connection = graph.connection)
+      list = []
+      n = q(connection, nodes_table)
+      e = q(connection, edges_table)
+
+      type.node_types.each_value do |t|
+        has_label = "labels @> ARRAY[#{connection.quote(t.name.to_s)}]::text[]"
+        if (key = t.own_key)
+          list << [:index, nodes_table, "key_#{t.name}_#{key.property}",
+                   "ON #{n} ((properties->>#{connection.quote(key.property.to_s)})) WHERE #{has_label}"]
+        end
+        t.own_properties.each_value.select(&:required?).each do |p|
+          list << [:check, nodes_table, "req_#{t.name}_#{p.name}", "NOT (#{has_label}) OR #{typed_check(connection, p)}"]
+        end
+      end
+
+      type.edge_types.each_value do |t|
+        is_type = "type = #{connection.quote(t.name.to_s)}"
+        list << [:index, edges_table, "pair_#{t.name}", "ON #{e} (source_id, target_id) WHERE #{is_type}"] if t.unique_pair?
+        t.own_properties.each_value.select(&:required?).each do |p|
+          list << [:check, edges_table, "req_#{t.name}_#{p.name}", "NOT (#{is_type}) OR #{typed_check(connection, p)}"]
+        end
+      end
+
+      list.to_h do |kind, table, label, body|
+        name = constraint_name(table, label, body)
+        sql = if kind == :index
+                "CREATE UNIQUE INDEX #{q(connection, name)} #{body}"
+              else
+                "ALTER TABLE #{q(connection, table)} ADD CONSTRAINT #{q(connection, name)} CHECK (#{body})"
+              end
+        [name, { kind:, table:, sql: }]
+      end
+    end
+
+    # Adds missing generated constraints and drops stale ones.
+    def sync_constraints!(connection = graph.connection)
+      wanted = constraints(connection)
+      existing = existing_constraints(connection)
+      (existing.keys - wanted.keys).each do |name|
+        info = existing[name]
+        if info[:kind] == :index
+          connection.execute("DROP INDEX #{q(connection, name)}")
+        else
+          connection.execute("ALTER TABLE #{q(connection, info[:table])} DROP CONSTRAINT #{q(connection, name)}")
+        end
+      end
+      (wanted.keys - existing.keys).each { connection.execute(wanted[_1][:sql]) }
+      nil
+    end
+
+    # Rewrites stored label sets to match the graph type.
+    def relabel!(connection = graph.connection)
+      return 0 if concrete_types.empty?
+
+      connection.exec_update(<<~SQL, "Pglpg relabel")
+        UPDATE #{q(connection, nodes_table)} AS n SET labels = v.labels
+        FROM (VALUES #{label_values(connection)}) AS v(key_label, labels)
+        WHERE n.key_label = v.key_label AND n.labels IS DISTINCT FROM v.labels
+      SQL
+    end
+
+    # Stored nodes whose labels disagree with the graph type, counted by key
+    # label. Rows of unknown or abstract types count as drift too.
+    def label_drift(connection = graph.connection)
+      values = concrete_types.empty? ? "SELECT NULL::text, NULL::text[] WHERE false" : "VALUES #{label_values(connection)}"
+      connection.select_rows(<<~SQL, "Pglpg label drift").to_h { |label, count| [label.to_sym, count.to_i] }
+        SELECT n.key_label, count(*) FROM #{q(connection, nodes_table)} AS n
+        LEFT JOIN (#{values}) AS v(key_label, labels) ON v.key_label = n.key_label
+        WHERE v.labels IS NULL OR n.labels IS DISTINCT FROM v.labels
+        GROUP BY n.key_label ORDER BY n.key_label
+      SQL
+    end
+
+    private
+
+    def type = graph.type
+
+    def q(connection, name) = connection.quote_table_name(name)
+
+    def concrete_types = type.node_types.values.reject(&:abstract?)
+
+    def label_values(connection)
+      concrete_types.map do |t|
+        "(#{connection.quote(t.name.to_s)}, ARRAY[#{t.labels.map { connection.quote(_1) }.join(", ")}]::text[])"
+      end.join(", ")
+    end
+
+    # Edge columns declared covering: true (typically what the visibility
+    # policy filters on) ride along in the traversal indexes.
+    def covering(connection, endpoint)
+      [endpoint, *type.edge_columns.each_value.select(&:covering?).map { connection.quote_column_name(_1.name) }].join(", ")
+    end
+
+    def columns_sql(connection, columns)
+      columns.each_value.map do |c|
+        sql = +"#{connection.quote_column_name(c.name)} #{c.sql_type(connection)}"
+        sql << " NOT NULL" unless c.null?
+        sql << " DEFAULT #{connection.quote(c.options[:default])}" if c.default?
+        "#{sql},\n  "
+      end.join
+    end
+
+    # Rejects a missing key, JSON null and the wrong JSON type: a CHECK passes
+    # on NULL, so the comparison is wrapped in IS TRUE.
+    def typed_check(connection, prop)
+      "(jsonb_typeof(properties->#{connection.quote(prop.name.to_s)}) = #{connection.quote(prop.json_type)}) IS TRUE"
+    end
+
+    def constraint_name(table, label, body)
+      digest = Digest::SHA256.hexdigest(body)[0, 8]
+      base = "pglpg_#{table}_#{label}"
+      base = base[0, NAME_LIMIT - digest.size - 1]
+      "#{base}_#{digest}"
+    end
+
+    def existing_constraints(connection)
+      prefixes = [nodes_table, edges_table].map { "pglpg\\_#{_1.gsub("_", "\\_")}\\_%" }
+      rows = connection.select_rows(<<~SQL, "Pglpg constraints")
+        SELECT c.conname, 'check', t.relname FROM pg_constraint c JOIN pg_class t ON t.oid = c.conrelid
+        WHERE t.relname IN (#{connection.quote(nodes_table)}, #{connection.quote(edges_table)})
+          AND t.relnamespace = to_regnamespace(current_schema())
+          AND (c.conname LIKE #{connection.quote(prefixes[0])} OR c.conname LIKE #{connection.quote(prefixes[1])})
+        UNION ALL
+        SELECT i.indexname, 'index', i.tablename FROM pg_indexes i
+        WHERE i.tablename IN (#{connection.quote(nodes_table)}, #{connection.quote(edges_table)})
+          AND i.schemaname = current_schema()
+          AND (i.indexname LIKE #{connection.quote(prefixes[0])} OR i.indexname LIKE #{connection.quote(prefixes[1])})
+      SQL
+      rows.to_h { |name, kind, table| [name, { kind: kind.to_sym, table: }] }
+    end
+  end
+end

data/lib/pglpg/testing/leak_examples.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+# Shared leak specs for an application's visibility policy.
+#
+#   require "pglpg/testing"
+#
+#   RSpec.describe MyApp::ClearancePolicy do
+#     it_behaves_like "a pglpg visibility policy" do
+#       let(:pglpg_visibility)    { MyApp::ClearancePolicy }
+#       let(:pglpg_viewer)        { MyApp::Viewer.new(clearance: 2) }
+#       let(:pglpg_columns)       { { classification: [:integer, { null: false }] } }
+#       let(:pglpg_visible_attrs) { { classification: 1 } }  # visible to the viewer
+#       let(:pglpg_hidden_attrs)  { { classification: 4 } }  # hidden from the viewer
+#     end
+#   end
+#
+# The suite builds its own small graph with the given application columns in
+# temporary tables, inside a transaction that is rolled back. It is
+# metamorphic: it records what the viewer can observe on a visible fixture,
+# adds hidden nodes and edges (hidden bridges, hidden edges between visible
+# nodes, visible edges to hidden nodes), and checks that every observation
+# (rows, order, counts, exists?, first, pagination, lookups) is unchanged.
+# Execution time and timeouts are outside this guarantee.
+RSpec.shared_examples "a pglpg visibility policy" do
+  leak_graph = lambda do |visibility, columns|
+    Pglpg::Graph.define(:pglpg_leak, nodes_table: "pglpg_leak_nodes", edges_table: "pglpg_leak_edges",
+                                     visibility:, write_policy: Pglpg::Testing::AllowAll,
+                                     trusted_writer_allowed: ->(_context) { true }) do
+      columns.each { |name, (type, options)| column(name, type, **(options || {})) }
+      node :Person do
+        property :uid, :string, required: true
+        property :name, :string
+        property :rank, :integer
+        key :uid
+      end
+      node :Project do
+        property :uid, :string, required: true
+        property :title, :string
+        key :uid
+      end
+      node :Location do
+        property :uid, :string, required: true
+        key :uid
+      end
+      edge :WORKS_ON, from: :Person, to: :Project do
+        property :role, :string
+      end
+      edge :BASED_AT, from: :Project, to: :Location
+      edge :KNOWS, from: :Person, to: :Person
+    end
+  end
+
+  around do |example|
+    ActiveRecord::Base.transaction(requires_new: true) do
+      example.run
+      raise ActiveRecord::Rollback
+    end
+  end
+
+  let(:pglpg_leak_graph) { leak_graph.call(pglpg_visibility, pglpg_columns) }
+  let(:pglpg_seed_graph) { leak_graph.call(Pglpg::Testing::SeeAll, pglpg_columns) }
+
+  it "keeps every observation unchanged when hidden data is added" do
+    pglpg_leak_graph.storage.create!
+    seed = pglpg_seed_graph.for(viewer: nil).trusted_writer
+    vis = pglpg_visible_attrs
+    hid = pglpg_hidden_attrs
+    person = ->(uid, name, rank, attrs) { seed.insert_node(:Person, properties: { uid:, name:, rank: }, attrs:) }
+    node = ->(type, uid, attrs, **props) { seed.insert_node(type, properties: { uid:, **props }, attrs:) }
+    edge = ->(type, from, to, attrs, **props) { seed.insert_edge(type, from:, to:, properties: props, attrs:) }
+
+    p1 = person.("P1", "Ann", 1, vis)
+    p2 = person.("P2", "Bob", 2, vis)
+    p3 = person.("P3", "Cid", 3, vis)
+    j1 = node.(:Project, "J1", vis, title: "Apollo")
+    j2 = node.(:Project, "J2", vis, title: "Gemini")
+    l1 = node.(:Location, "L1", vis)
+    visible_edges = [
+      edge.(:WORKS_ON, p1, j1, vis, role: "lead"),
+      edge.(:WORKS_ON, p2, j1, vis, role: "dev"),
+      edge.(:WORKS_ON, p3, j2, vis, role: "lead"),
+      edge.(:BASED_AT, j1, l1, vis),
+      edge.(:KNOWS, p1, p2, vis),
+      edge.(:KNOWS, p2, p3, vis)
+    ]
+    visible_refs = [p1, p2, p3, j1, j2, l1, *visible_edges]
+
+    ctx = pglpg_leak_graph.for(viewer: pglpg_viewer)
+    before = Pglpg::Testing.observe(ctx, visible_refs)
+    if before[:persons].size != 3 || before[:works_on].size != 3
+      raise "the visibility policy hides the visible fixture; check pglpg_visible_attrs"
+    end
+
+    h1 = person.("H1", "Ann", 1, hid)
+    h2 = person.("H2", "Zed", 5, hid)
+    hj = node.(:Project, "HJ", hid, title: "Apollo")
+    hl = node.(:Location, "HL", hid)
+    hidden_refs = [
+      h1, h2, hj, hl,
+      # hidden edges between visible nodes
+      edge.(:WORKS_ON, p3, j1, hid, role: "lead"),
+      edge.(:KNOWS, p3, p1, hid),
+      edge.(:BASED_AT, j2, l1, hid),
+      # visible edges touching hidden nodes, including a hidden bridge p3 -> h1 -> p1
+      edge.(:WORKS_ON, p1, hj, vis, role: "lead"),
+      edge.(:BASED_AT, j2, hl, vis),
+      edge.(:KNOWS, p3, h1, vis),
+      edge.(:KNOWS, h1, p1, vis),
+      edge.(:KNOWS, h2, p2, vis),
+      edge.(:WORKS_ON, h2, j2, vis, role: "dev"),
+      # hidden edge between hidden nodes
+      edge.(:KNOWS, h1, h2, hid)
+    ]
+
+    after = Pglpg::Testing.observe(ctx, visible_refs)
+    before.each_key { |name| expect(after[name]).to eq(before[name]), "observation #{name} changed" }
+
+    hidden_refs.each { |ref| expect(ctx.find(ref)).to be_nil, "#{ref} is visible" }
+    expect(ctx.find_node(:Person, uid: "H1")).to be_nil
+  end
+end

data/lib/pglpg/testing.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Pglpg
+  # Helpers for the shared leak specs (see testing/leak_examples.rb).
+  module Testing
+    # Sees everything; used only to seed fixtures.
+    module SeeAll
+      def self.node(_table, _viewer) = Arel.sql("TRUE")
+
+      def self.edge(_table, _viewer) = Arel.sql("TRUE")
+    end
+
+    # Allows every write; used only to seed fixtures.
+    module AllowAll
+      def self.authorize?(_request) = true
+    end
+
+    module_function
+
+    # Everything the viewer can observe through the query API on the leak
+    # graph, as plain data.
+    def observe(ctx, refs)
+      m = -> { ctx.match }
+      queries = {
+        persons: -> { m.().node(:p, :Person).order(p: :name) },
+        works_on: -> { m.().node(:p, :Person).out(:WORKS_ON, :j, :Project, edge: :w) },
+        two_hops: -> { m.().node(:p, :Person).out(:WORKS_ON, :j, :Project).out(:BASED_AT, :l, :Location) },
+        knows_chain: -> { m.().node(:a, :Person).out(:KNOWS, :b, :Person).out(:KNOWS, :c, :Person) },
+        inbound: -> { m.().node(:l, :Location).in(:BASED_AT, :j, :Project).in(:WORKS_ON, :p, :Person) },
+        branch: -> { m.().node(:j, :Project).in(:WORKS_ON, :p, :Person).out(:BASED_AT, :l, :Location, from: :j) },
+        unlabeled: -> { m.().node(:x).out(:KNOWS, :y) },
+        leads: -> { m.().node(:p, :Person).out(:WORKS_ON, :j, :Project, edge: :w).where(w: { role: "lead" }) },
+        ranked: -> { m.().node(:p, :Person).where(p: { rank: Pglpg.gte(2) }) },
+        by_title: -> { m.().node(:j, :Project, title: "Apollo").in(:WORKS_ON, :p, :Person) },
+        projects: -> { m.().node(:p, :Person).out(:WORKS_ON, :j, :Project).return(:j).distinct },
+        page: -> { m.().node(:p, :Person).out(:WORKS_ON, :j, :Project).limit(2).offset(1) },
+        ann: -> { m.().node(:p, :Person, name: "Ann").out(:WORKS_ON, :j, :Project) },
+        cid_knows: -> { m.().node(:p, :Person, name: "Cid").out(:KNOWS, :q) }
+      }
+      out = {}
+      queries.each do |name, q|
+        out[name] = q.().to_a.map { |row| row.transform_values { element_data(_1) } }
+        out[:"#{name}_count"] = q.().count
+        out[:"#{name}_exists"] = q.().exists?
+        out[:"#{name}_first"] = q.().first&.transform_values { element_data(_1) }
+      end
+      out[:last_by_name] = element_data(m.().node(:p, :Person).order(p: { name: :desc }).first&.fetch(:p))
+      out[:find] = refs.map { element_data(ctx.find(_1)) }
+      out[:find_node] = %w[P1 P2 P3 H1].map { element_data(ctx.find_node(:Person, uid: _1)) }
+      out
+    end
+
+    def element_data(element)
+      case element
+      when nil then nil
+      when Pglpg::Node then [:node, element.id, element.key_label, element.labels, element.properties, element.attrs]
+      when Pglpg::Edge
+        [:edge, element.id, element.type, element.source.id, element.target.id, element.properties, element.attrs]
+      end
+    end
+  end
+end
+
+require_relative "testing/leak_examples" if defined?(RSpec)

data/lib/pglpg/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Pglpg
+  VERSION = "0.1.0"
+end