pglpg 0.1.0 → 0.3.0

data/lib/pglpg/temporal.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Pglpg
+  # Internal validity metadata, deliberately separate from application columns.
+  module Temporal
+    NAMES = %i[valid_from valid_to].freeze
+    OMITTED = Object.new.freeze
+    MIN = Date.new(1, 1, 1, Date::GREGORIAN).freeze
+    MAX = Date.new(9999, 12, 31, Date::GREGORIAN).freeze
+
+    module_function
+
+    # PostgreSQL dates are proleptic Gregorian calendar dates. Interpret Ruby
+    # Dates by their civil fields, never by timezone or an implicit Time cast.
+    def date(value, error: ValidationError)
+      return nil if value.nil?
+      raise error, "expected an exact Date in 0001-01-01..9999-12-31" unless value.instance_of?(Date)
+
+      begin
+        result = Date.new(value.year, value.month, value.day, Date::GREGORIAN)
+      rescue Date::Error
+        raise error, "invalid Gregorian date"
+      end
+      raise error, "date outside 0001-01-01..9999-12-31" unless (MIN..MAX).cover?(result)
+
+      result.freeze
+    end
+
+    def bounds(type, lower, upper, required: false)
+      supplied = { valid_from: lower, valid_to: upper }.reject { |_, v| v.equal?(OMITTED) }
+      unless type.temporal?
+        raise ArgumentError, "#{type.name} is not temporal" unless supplied.empty?
+        return {}.freeze
+      end
+      raise ArgumentError, "temporal insert/upsert requires valid_from:" if required && lower.equal?(OMITTED)
+
+      result = supplied.transform_values { date(_1) }
+      validate_interval!(result[:valid_from], result[:valid_to])
+      result.freeze
+    end
+
+    def validate_interval!(lower, upper)
+      raise ValidationError, "valid_from must precede valid_to" if lower && upper && lower >= upper
+    end
+  end
+end

data/lib/pglpg/testing/leak_examples.rb

@@ -22,31 +22,36 @@
 # (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|
+  leak_graph = lambda do |visibility, columns, temporal, open|
     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
+      node :Person, open: open do
         property :uid, :string, required: true
         property :name, :string
         property :rank, :integer
-        key :uid
+        property :namespace, :string, required: true
+        key :uid, scope: :namespace
       end
-      node :Project do
+      node :Project, open: open do
         property :uid, :string, required: true
-        property :title, :string
-        key :uid
+        property :title, :string, required: true
+        key :uid, :title
       end
       node :Location do
         property :uid, :string, required: true
         key :uid
       end
-      edge :WORKS_ON, from: :Person, to: :Project do
+      edge :WORKS_ON, from: :Person, to: :Project, temporal: temporal, open: open do
         property :role, :string
+        property :uid, :string, required: true
+        property :batch, :integer, required: true
+        key :uid, :batch
       end
-      edge :BASED_AT, from: :Project, to: :Location
-      edge :KNOWS, from: :Person, to: :Person
+      edge :BASED_AT, from: :Project, to: :Location, temporal: temporal
+      edge :KNOWS, from: :Person, to: :Person, temporal: temporal
+      edge :FRIEND, from: :Person, to: :Person, symmetric: true, temporal: temporal
     end
   end
 
@@ -57,18 +62,36 @@ RSpec.shared_examples "a pglpg visibility policy" do
     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) }
+  # Optional: also exercise temporal validity with the application policy.
+  let(:pglpg_temporal) { false }
+  # Optional: also exercise extra properties through reads/models.
+  let(:pglpg_open_types) { false }
+
+  let(:pglpg_leak_graph) { leak_graph.call(pglpg_visibility, pglpg_columns, pglpg_temporal, pglpg_open_types) }
+  let(:pglpg_seed_graph) { leak_graph.call(Pglpg::Testing::SeeAll, pglpg_columns, pglpg_temporal, pglpg_open_types) }
 
   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:) }
+    person = lambda do |uid, name, rank, attrs|
+      extras = pglpg_open_types ? { source_note: uid, evidence: ["one", "two"] } : {}
+      seed.insert_node(:Person, properties: { uid:, name:, rank:, namespace: attrs == hid ? "hidden" : "visible", **extras }, attrs:)
+    end
+    node = lambda do |type, uid, attrs, **props|
+      extras = pglpg_open_types && type == :Project ? { source_note: uid } : {}
+      seed.insert_node(type, properties: { uid:, **props, **extras }, attrs:)
+    end
+    edge = lambda do |type, from, to, attrs, **props|
+      props = props.merge(uid: "#{from.id}-#{to.id}", batch: 1) if type == :WORKS_ON
+      props = props.merge(source_note: "evidence", evidence: [1, 2]) if pglpg_open_types && type == :WORKS_ON
+      seed.insert_edge(type, from:, to:, properties: props, attrs:, **(pglpg_temporal ? { valid_from: nil } : {}))
+    end
 
+    # Created first, so it has the smallest id: symmetric edges to it are
+    # stored with the hidden node in the source column.
+    h0 = person.("H0", "Abe", 0, hid)
     p1 = person.("P1", "Ann", 1, vis)
     p2 = person.("P2", "Bob", 2, vis)
     p3 = person.("P3", "Cid", 3, vis)
@@ -81,12 +104,16 @@ RSpec.shared_examples "a pglpg visibility policy" do
       edge.(:WORKS_ON, p3, j2, vis, role: "lead"),
       edge.(:BASED_AT, j1, l1, vis),
       edge.(:KNOWS, p1, p2, vis),
-      edge.(:KNOWS, p2, p3, vis)
+      edge.(:KNOWS, p2, p3, vis),
+      edge.(:FRIEND, p2, p1, vis),
+      edge.(:FRIEND, p3, p2, vis)
     ]
     visible_refs = [p1, p2, p3, j1, j2, l1, *visible_edges]
 
-    ctx = pglpg_leak_graph.for(viewer: pglpg_viewer)
+    ctx = pglpg_leak_graph.for(viewer: pglpg_viewer, **(pglpg_temporal ? { as_of: Date.new(2020, 6, 1) } : {}))
     before = Pglpg::Testing.observe(ctx, visible_refs)
+    # Three visible People plus two visible Projects in this fixture.
+    raise "lazy association observations are missing" unless before.keys.count { _1.to_s.start_with?("assoc_") } == 5
     if before[:persons].size != 3 || before[:works_on].size != 3
       raise "the visibility policy hides the visible fixture; check pglpg_visible_attrs"
     end
@@ -96,7 +123,13 @@ RSpec.shared_examples "a pglpg visibility policy" do
     hj = node.(:Project, "HJ", hid, title: "Apollo")
     hl = node.(:Location, "HL", hid)
     hidden_refs = [
-      h1, h2, hj, hl,
+      h0, h1, h2, hj, hl,
+      # symmetric edges: hidden between visible nodes, and visible ones through
+      # hidden nodes stored at either end (a hidden bridge p1 ~ h0 ~ p3)
+      edge.(:FRIEND, p3, p1, hid),
+      edge.(:FRIEND, p1, h0, vis),
+      edge.(:FRIEND, h0, p3, vis),
+      edge.(:FRIEND, p2, h1, vis),
       # hidden edges between visible nodes
       edge.(:WORKS_ON, p3, j1, hid, role: "lead"),
       edge.(:KNOWS, p3, p1, hid),
@@ -112,10 +145,26 @@ RSpec.shared_examples "a pglpg visibility policy" do
       edge.(:KNOWS, h1, h2, hid)
     ]
 
+    if pglpg_temporal
+      # Visible but ineligible edges must be just as unobservable as hidden
+      # data, including expired shortcuts and a disjoint-time bridge.
+      [[p1, p3], [p3, p2]].each do |from, to|
+        hidden_refs << seed.insert_edge(:KNOWS, from:, to:, attrs: vis, valid_from: nil, valid_to: Date.new(2020, 6, 1))
+      end
+      hidden_refs << seed.insert_edge(:FRIEND, from: p1, to: p3, attrs: vis, valid_from: Date.new(2020, 6, 2))
+      hidden_refs << seed.insert_edge(:WORKS_ON, from: p1, to: j2, properties: { uid: "expired", batch: 1 }, attrs: vis, valid_from: nil, valid_to: Date.new(2020, 6, 1))
+    end
+
     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
+    expect(ctx.find_node(:Person, namespace: "hidden", uid: "H1")).to be_nil
+
+    models = Pglpg::Testing.leak_models(pglpg_leak_graph)
+    [h0, h1, h2].each do |ref|
+      expect { models[:Person].in(ctx).find(ref) }.to raise_error(Pglpg::Model::RecordNotFound), "#{ref} is visible"
+    end
+    expect { models[:Project].in(ctx).find(hj) }.to raise_error(Pglpg::Model::RecordNotFound), "#{hj} is visible"
   end
 end

data/lib/pglpg/testing.rb

@@ -35,7 +35,12 @@ module Pglpg
         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) }
+        cid_knows: -> { m.().node(:p, :Person, name: "Cid").out(:KNOWS, :q) },
+        friends: -> { m.().node(:p, :Person).both(:FRIEND, :q, :Person, edge: :f) },
+        friend_edges: -> { m.().node(:p, :Person).both(:FRIEND, :q, edge: :f).return(:f).distinct },
+        friend_chain: -> { m.().node(:a, :Person).both(:FRIEND, :b).both(:FRIEND, :c) },
+        ann_friends: -> { m.().node(:p, :Person, name: "Ann").both(:FRIEND, :q) },
+        friends_page: -> { m.().node(:p, :Person).both(:FRIEND, :q).limit(2).offset(1) }
       }
       out = {}
       queries.each do |name, q|
@@ -44,12 +49,135 @@ module Pglpg
         out[:"#{name}_exists"] = q.().exists?
         out[:"#{name}_first"] = q.().first&.transform_values { element_data(_1) }
       end
+      reach = {
+        knows: { via: %i[KNOWS] },
+        knows_in: { via: %i[KNOWS], direction: :in },
+        friends: { via: %i[FRIEND], direction: :both },
+        works: { via: %i[WORKS_ON BASED_AT] },
+        works_in: { via: %i[WORKS_ON BASED_AT], direction: :in },
+        knows_capped: { via: %i[KNOWS], max_nodes: 1 },
+        friends_capped: { via: %i[FRIEND], direction: :both, max_nodes: 1 }
+      }
+      # Within the application's row cap, which may be smaller than 10.
+      budget = [10, Pglpg.configuration.max_rows].min
+      reach.each do |name, args|
+        out[:"reach_#{name}"] = refs.select(&:node?).map do |ref|
+          r = ctx.reachable(from: ref, max_depth: 3, max_nodes: budget, **args)
+          [r.nodes.map { |node, depth| [node.id, depth] }, r.complete, r.stopped_at_depth]
+        end
+      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[:find_node] = %w[P1 P2 P3 H1].map { element_data(ctx.find_node(:Person, namespace: _1 == "H1" ? "hidden" : "visible", uid: _1)) }
+      out[:find_composite_node] = [["J1", "Apollo"], ["J2", "Gemini"], ["HJ", "Apollo"]].map do |uid, title|
+        element_data(ctx.find_node(:Project, uid:, title:))
+      end
+      persons = refs.select(&:node?).select { ctx.find(_1)&.key_label == :Person }
+      projects = refs.select(&:node?).select { ctx.find(_1)&.key_label == :Project }
+      out[:find_edge] = persons.product(projects).map do |person, project|
+        element_data(ctx.find_edge(:WORKS_ON, uid: "#{person.id}-#{project.id}", batch: 1))
+      end
+      out[:find_expired_edge] = element_data(ctx.find_edge(:WORKS_ON, uid: "expired", batch: 1)) if ctx.as_of.instance_of?(Date)
+      out.merge(observe_models(ctx, refs))
+    end
+
+    # The same observations through the model layer (ADR-0010).
+    def observe_models(ctx, refs)
+      models = leak_models(ctx.graph)
+      relations = {
+        persons: -> { models[:Person].in(ctx).order(:name) },
+        ranked: -> { models[:Person].in(ctx).where(rank: Pglpg.gte(2)).order(rank: :desc) },
+        persons_page: -> { models[:Person].in(ctx).order(:name).limit(2).offset(1) },
+        projects: -> { models[:Project].in(ctx) },
+        works_on: -> { models[:WORKS_ON].in(ctx).order(:role) },
+        leads: -> { models[:WORKS_ON].in(ctx).where(role: "lead") },
+        knows: -> { models[:KNOWS].in(ctx) },
+        friends: -> { models[:FRIEND].in(ctx) },
+        friends_page: -> { models[:FRIEND].in(ctx).limit(1).offset(1) }
+      }
+      out = {}
+      relations.each do |name, r|
+        out[:"model_#{name}"] = r.().map { model_data(_1) }
+        out[:"model_#{name}_count"] = r.().count
+        out[:"model_#{name}_exists"] = r.().exists?
+        out[:"model_#{name}_first"] = model_data(r.().first)
+        out[:"model_#{name}_pluck"] = r.().pluck(:id, *r.().model.attribute_names)
+      end
+      out[:model_find_by] = %w[P1 P2 P3 H1].map { model_data(models[:Person].in(ctx).find_by(uid: _1)) }
+      out[:model_find] = refs.map do |ref|
+        model = ref.node? ? models[:Person] : models[:WORKS_ON]
+        model_data(model.in(ctx).find(ref))
+      rescue Pglpg::Model::RecordNotFound
+        nil
+      end
+      out.merge!(observe_associations(ctx, models))
+      owners = models[:Person].in(ctx).with_associations(:known, :known_by, :friends, :projects).to_a +
+               models[:Project].in(ctx).with_associations(:people).to_a
+      eager = observe_associations(ctx, models, owners)
+      eager.each { |name, value| raise "preload differs from lazy #{name}" unless value == out.fetch(name) }
+      out[:eager_associations] = eager
+      nested = models[:Person].in(ctx).with_associations(friends: :friends, projects: :people)
+      out[:eager_nested] = nested.map do |owner|
+        [owner.uid, { friends: :friends, projects: :people }.map do |name, child|
+          owner.public_send(name).map do |target|
+            cached = target.public_send(child).map { model_data(_1) }
+            lazy = target.class.in(ctx).find(target.ref).public_send(child).map { model_data(_1) }
+            raise "nested preload differs from lazy #{name}.#{child}" unless cached == lazy
+
+            [model_data(target), cached]
+          end
+        end]
+      end
       out
     end
 
+    # Association target and binding queries from every visible owner.
+    def observe_associations(ctx, models, owners = nil)
+      pair = ->((node, edge)) { [model_data(node), model_data(edge)] }
+      owners ||= models[:Person].in(ctx).order(:uid).to_a + models[:Project].in(ctx).order(:uid).to_a
+      owners.to_h do |owner|
+        data = owner.class.associations.keys.to_h do |name|
+          targets = -> { owner.public_send(name) }
+          [name, {
+            rows: targets.().map { model_data(_1) },
+            count: targets.().count,
+            exists: targets.().exists?,
+            first: model_data(targets.().first),
+            page: targets.().limit(1).offset(1).map { model_data(_1) },
+            pairs: targets.().with_rel.map(&pair),
+            pairs_count: targets.().with_rel.count,
+            pairs_page: targets.().with_rel.limit(1).offset(1).map(&pair),
+            pluck: targets.().pluck(:id, *targets.().model.attribute_names),
+            pairs_pluck: targets.().with_rel.pluck(:id, rel: [:id, *models.fetch(owner.class.associations[name].edge_type).attribute_names])
+          }]
+        end
+        data[:leads] = owner.projects.rel_where(role: "lead").map { model_data(_1) } if owner.respond_to?(:projects)
+        [:"assoc_#{owner.uid}", data]
+      end
+    end
+
+    def model_data(record)
+      return nil if record.nil?
+
+      data = [record.class.schema_type.name, record.id, record.attributes, record.extra_properties]
+      data + (record.is_a?(Pglpg::Model::Edge) ? [record.source.id, record.target.id] : [record.labels])
+    end
+
+    # One model per type of the leak graph, built once per graph.
+    def leak_models(leak_graph)
+      (@leak_models ||= ObjectSpace::WeakKeyMap.new)[leak_graph] ||=
+        %i[Person Project WORKS_ON KNOWS FRIEND].to_h do |type|
+          base = leak_graph.type.node_types.key?(type) ? Pglpg::Model::Node : Pglpg::Model::Edge
+          [type, Class.new(base) { graph(leak_graph, type:) }]
+        end.tap do |models|
+          models[:Person].has_many :projects, :out, edge: :WORKS_ON
+          models[:Person].has_many :known, :out, edge: :KNOWS
+          models[:Person].has_many :known_by, :in, edge: :KNOWS
+          models[:Person].has_many :friends, :both, edge: :FRIEND
+          models[:Project].has_many :people, :in, edge: :WORKS_ON
+        end
+    end
+
     def element_data(element)
       case element
       when nil then nil
@@ -61,4 +189,5 @@ module Pglpg
   end
 end
 
+require_relative "model"
 require_relative "testing/leak_examples" if defined?(RSpec)

data/lib/pglpg/version.rb

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

data/lib/pglpg/writer.rb

@@ -8,14 +8,20 @@ module Pglpg
   #   target:    the Ref being changed (update and delete), else nil
   #   from, to:  endpoint Refs for edge inserts and upserts
   #   key:       the key for upserts
-  WriteRequest = Data.define(:viewer, :operation, :type, :target, :from, :to, :key, :properties, :attrs, :trusted)
+  # Scope-wide occupancy permission, distinct from write or read access.
+  KeyScopeRequest = Data.define(:context, :domain, :scope)
+
+  WriteRequest = Data.define(:viewer, :operation, :type, :target, :from, :to, :key, :properties, :attrs, :trusted, :validity, :validity_supplied)
 
   # Compiles writes into single statements. Visibility of the existing row,
   # the policy's conditions on it and endpoint checks all run inside the
   # statement, so they hold against the row the statement actually touches,
   # even under concurrent writes.
   class Writer
+    attr_reader :context
+
     def initialize(context, trusted:)
+      context.writable!
       @context = context
       @graph = context.graph
       @trusted = trusted
@@ -23,17 +29,17 @@ module Pglpg
 
     def insert_node(type, properties: {}, attrs: {})
       node_type = concrete_node_type!(type)
-      props = properties.transform_keys(&:to_sym)
-      if (key = node_type.key)
-        if props.key?(key.property)
-          raise ArgumentError, "#{node_type.name}.#{key.property} is a key and is generated" unless @trusted
-        else
-          props[key.property] = key.generate(node_type.name)
-        end
-      end
+      props = prepare_key(node_type, properties)
+      key = node_type.key
       json = node_type.encode_properties(props)
       cols = encode_attrs(@graph.type.node_columns, attrs, insert: true)
       authorize!(:insert_node, node_type.name, properties: props, attrs:)
+      if key&.scope && !@trusted && properties.keys.map(&:to_sym).include?(key.property)
+        scope = { key.scope => props.fetch(key.scope).dup.freeze }.freeze
+        request = KeyScopeRequest.new(context:, domain: key.declared_on, scope:)
+        allowed = @graph.key_scope_allowed
+        raise WriteRejected unless allowed.respond_to?(:call) && allowed.call(request) == true
+      end
 
       sql = new_sql
       insert_node_values(sql, node_type, json, cols)
@@ -45,8 +51,8 @@ module Pglpg
       @graph.check_ref!(ref, :node)
       node = @context.find(ref) or raise WriteRejected
       node_type = @graph.type.node_type!(node.key_label)
-      props = properties.transform_keys(&:to_sym)
-      raise ArgumentError, "keys cannot be changed" if node_type.key && props.key?(node_type.key.property)
+      props = node_type.normalize_properties(properties)
+      raise ArgumentError, "keys cannot be changed" if node_type.key && (props.keys & node_type.key.properties).any?
 
       json = node_type.encode_properties(props, partial: true)
       cols = encode_attrs(@graph.type.node_columns, attrs, insert: false)
@@ -70,10 +76,10 @@ module Pglpg
       node_type = concrete_node_type!(type)
       node_key = node_type.key or raise ArgumentError, "#{node_type.name} has no key"
       key = key.transform_keys(&:to_sym)
-      raise ArgumentError, "#{node_type.name} is upserted by #{node_key.property.inspect}" unless key.keys == [node_key.property]
+      node_key.validate_values!(node_type, key)
 
-      props = properties.transform_keys(&:to_sym)
-      raise ArgumentError, "pass the key in key:, not properties:" if props.key?(node_key.property)
+      props = node_type.normalize_properties(properties)
+      raise ArgumentError, "pass the key in key:, not properties:" if (props.keys & node_key.properties).any?
 
       props = props.merge(key)
       json = node_type.encode_properties(props)
@@ -82,8 +88,9 @@ module Pglpg
 
       sql = new_sql
       insert_node_values(sql, node_type, json, cols)
-      sql << " ON CONFLICT ((properties->>"
-      sql.literal(node_key.property) << ")) WHERE labels @> ARRAY["
+      sql << " ON CONFLICT ("
+      sql << node_key.expressions(@graph.connection).join(", ")
+      sql << ") WHERE labels @> ARRAY["
       sql.literal(node_key.declared_on) << "]::text[] DO UPDATE SET "
       set_properties(sql, "tgt.properties", json, null_keys(props), excluded: true)
       set_columns(sql, cols, excluded: true)
@@ -110,32 +117,50 @@ module Pglpg
       true
     end
 
-    def insert_edge(type, from:, to:, properties: {}, attrs: {})
+    def insert_edge(type, from:, to:, properties: {}, attrs: {}, valid_from: Temporal::OMITTED, valid_to: Temporal::OMITTED)
       edge_type = @graph.type.edge_type!(type)
-      if edge_type.unique_pair? && !@trusted
-        raise ArgumentError, "#{edge_type.name} is unique per pair; write it through the trusted writer"
+      if edge_type.unique_tuple? && !@trusted
+        raise ArgumentError, "#{edge_type.name} is unique per pair or property tuple; write it through the trusted writer"
       end
 
-      write_edge(:insert_edge, edge_type, from, to, properties, attrs)
+      write_edge(:insert_edge, edge_type, from, to, properties, attrs, valid_from, valid_to)
     end
 
-    # Trusted only, for edge types declared unique: :pair.
-    def upsert_edge(type, from:, to:, properties: {}, attrs: {})
+    # Trusted only. A declared edge key takes precedence as conflict arbiter;
+    # otherwise the endpoint/property tuple is used.
+    def upsert_edge(type, from:, to:, key: nil, properties: {}, attrs: {}, valid_from: Temporal::OMITTED, valid_to: Temporal::OMITTED)
       trusted!(:upsert_edge)
       edge_type = @graph.type.edge_type!(type)
-      raise ArgumentError, "#{edge_type.name} is not unique per pair; use insert_edge" unless edge_type.unique_pair?
-
-      write_edge(:upsert_edge, edge_type, from, to, properties, attrs)
+      if edge_type.key
+        raise ArgumentError, "#{edge_type.name} requires key:" unless key.is_a?(Hash)
+
+        key = key.transform_keys(&:to_sym)
+        edge_type.key.validate_values!(edge_type, key)
+        properties = edge_type.normalize_properties(properties)
+        raise ArgumentError, "pass the key in key:, not properties:" if (properties.keys & edge_type.key.properties).any?
+
+        properties = properties.merge(key)
+      else
+        raise ArgumentError, "#{edge_type.name} has no property key" unless key.nil?
+        raise ArgumentError, "#{edge_type.name} is not unique; use insert_edge" unless edge_type.unique_tuple?
+      end
+      write_edge(:upsert_edge, edge_type, from, to, properties, attrs, valid_from, valid_to, key:)
     end
 
-    def update_edge(ref, properties: {}, attrs: {})
+    def update_edge(ref, properties: {}, attrs: {}, valid_from: Temporal::OMITTED, valid_to: Temporal::OMITTED)
       @graph.check_ref!(ref, :edge)
-      edge = @context.find(ref) or raise WriteRejected
+      edge = @graph.for(viewer: @context.viewer, as_of: :any).find(ref) or raise WriteRejected
       edge_type = @graph.type.edge_type!(edge.type)
-      props = properties.transform_keys(&:to_sym)
+      validity = Temporal.bounds(edge_type, valid_from, valid_to)
+      Temporal.validate_interval!(validity.fetch(:valid_from, edge.valid_from), validity.fetch(:valid_to, edge.valid_to))
+      props = edge_type.normalize_properties(properties)
+      if (props.keys & edge_type.immutable_properties).any?
+        raise ArgumentError, "key and uniqueness properties cannot be changed"
+      end
       json = edge_type.encode_properties(props, partial: true)
       cols = encode_attrs(@graph.type.edge_columns, attrs, insert: false)
-      request = authorize!(:update_edge, edge_type.name, target: ref, properties: props, attrs:)
+      cols += validity_columns(validity)
+      request = authorize!(:update_edge, edge_type.name, target: ref, properties: props, attrs:, validity:)
 
       sql = new_sql
       sql << "UPDATE " << table(@graph.edges_table) << " AS tgt SET "
@@ -149,7 +174,7 @@ module Pglpg
 
     def delete_edge(ref)
       @graph.check_ref!(ref, :edge)
-      edge = @context.find(ref) or raise WriteRejected
+      edge = @graph.for(viewer: @context.viewer, as_of: :any).find(ref) or raise WriteRejected
       request = authorize!(:delete_edge, edge.type, target: ref)
 
       sql = new_sql
@@ -163,13 +188,24 @@ module Pglpg
 
     private
 
-    def write_edge(operation, edge_type, from, to, properties, attrs)
+    def write_edge(operation, edge_type, from, to, properties, attrs, valid_from, valid_to, key: nil)
+      validity = Temporal.bounds(edge_type, valid_from, valid_to, required: true)
       @graph.check_ref!(from, :node)
       @graph.check_ref!(to, :node)
-      props = properties.transform_keys(&:to_sym)
+      if edge_type.symmetric?
+        if from.id == to.id && !edge_type.allow_self_loops?
+          raise ArgumentError, "#{edge_type.name} does not allow self-loops"
+        end
+
+        # Stored in canonical orientation, so either order names the same pair.
+        from, to = to, from if from.id > to.id
+      end
+      props = prepare_key(edge_type, properties)
       json = edge_type.encode_properties(props)
       cols = encode_attrs(@graph.type.edge_columns, attrs, insert: true)
-      request = authorize!(operation, edge_type.name, from:, to:, properties: props, attrs:)
+      update_cols = cols + validity_columns(validity)
+      cols += validity_columns(edge_type.temporal? ? { valid_from: nil, valid_to: nil }.merge(validity) : {})
+      request = authorize!(operation, edge_type.name, from:, to:, key:, properties: props, attrs:, validity:)
 
       sql = new_sql
       sql << "INSERT INTO " << table(@graph.edges_table) << " AS tgt (type, source_id, target_id, properties"
@@ -183,26 +219,69 @@ module Pglpg
       end
       sql << " FROM " << table(@graph.nodes_table) << " AS s, " << table(@graph.nodes_table) << " AS t WHERE s.id = "
       sql.bind(from.id, "bigint") << " AND t.id = "
-      sql.bind(to.id, "bigint") << " AND s.labels @> "
-      sql.bind_text_array([edge_type.from]) << " AND t.labels @> "
-      sql.bind_text_array([edge_type.to]) << " AND "
+      sql.bind(to.id, "bigint") << " AND ("
+      endpoint_labels(sql, edge_type.from, edge_type.to)
+      if edge_type.symmetric? && edge_type.from != edge_type.to
+        # Either endpoint may carry either label.
+        sql << " OR "
+        endpoint_labels(sql, edge_type.to, edge_type.from)
+      end
+      sql << ") AND "
       @context.append_node_visible(sql, "s")
       sql << " AND "
       @context.append_node_visible(sql, "t")
       # Endpoints stay locked against concurrent change until commit.
       sql << " FOR SHARE OF s, t"
       if operation == :upsert_edge
-        sql << " ON CONFLICT (source_id, target_id) WHERE type = "
+        expressions = if edge_type.key
+                        edge_type.key.expressions(@graph.connection)
+                      else
+                        ["source_id", "target_id", *(edge_type.pair_key&.expressions(@graph.connection) || [])]
+                      end
+        sql << " ON CONFLICT (" << expressions.join(", ") << ") WHERE type = "
         sql.literal(edge_type.name) << " DO UPDATE SET "
         set_properties(sql, "tgt.properties", json, null_keys(props), excluded: true)
-        set_columns(sql, cols, excluded: true)
-        sql << " WHERE "
+        set_columns(sql, update_cols, excluded: true)
+        # A property key must never redirect an existing relationship. Pair
+        # properties are immutable too, including when a global key arbitrates.
+        sql << " WHERE tgt.source_id = EXCLUDED.source_id AND tgt.target_id = EXCLUDED.target_id"
+        edge_type.unique_pair_properties.each do |property|
+          sql << " AND tgt.properties->"
+          sql.literal(property) << " = EXCLUDED.properties->"
+          sql.literal(property)
+        end
+        sql << " AND "
         existing_row(sql, :edge, request)
       end
       sql << " RETURNING id"
       ref(:edge, write(sql))
     end
 
+    def prepare_key(type, properties)
+      props = type.normalize_properties(properties)
+      key = type.key
+      return props unless key
+      unless key.generated?
+        raise ArgumentError, "#{type.name} has a caller-chosen key; use the trusted writer" unless @trusted
+
+        return props
+      end
+      if props.key?(key.property)
+        unless @trusted || (type.is_a?(Schema::NodeType) && key.scope)
+          raise ArgumentError, "#{type.name}.#{key.property} is a key and is generated"
+        end
+      else
+        props[key.property] = key.generate(type.name)
+      end
+      props
+    end
+
+    def endpoint_labels(sql, source_label, target_label)
+      sql << "(s.labels @> "
+      sql.bind_text_array([source_label]) << " AND t.labels @> "
+      sql.bind_text_array([target_label]) << ")"
+    end
+
     def insert_node_values(sql, node_type, json, cols)
       sql << "INSERT INTO " << table(@graph.nodes_table) << " AS tgt (key_label, labels, properties"
       cols.each { |c, _| sql << ", " << ident(c.name) }
@@ -265,12 +344,17 @@ module Pglpg
       end
     end
 
+    def validity_columns(validity)
+      validity.map { |name, value| [Schema::Column.new(name, :date), value&.iso8601] }
+    end
+
     def null_keys(props) = props.select { |_, v| v.nil? }.keys.map(&:to_s)
 
-    def authorize!(operation, type, target: nil, from: nil, to: nil, key: nil, properties: {}, attrs: {})
+    def authorize!(operation, type, target: nil, from: nil, to: nil, key: nil, properties: {}, attrs: {}, validity: {}.freeze)
       request = WriteRequest.new(viewer: @context.viewer, operation:, type: type.to_sym, target:, from:, to:, key:,
                                  properties: properties.freeze, attrs: attrs.transform_keys(&:to_sym).freeze,
-                                 trusted: @trusted)
+                                 trusted: @trusted, validity:,
+                                 validity_supplied: Temporal::NAMES.to_h { [_1, validity.key?(_1)] }.freeze)
       raise WriteRejected unless @graph.write_policy.authorize?(request) == true
 
       request
@@ -312,8 +396,8 @@ module Pglpg
       id.to_i
     rescue ActiveRecord::StatementInvalid => e
       case e.cause
-      when PG::UniqueViolation, PG::ForeignKeyViolation, PG::RestrictViolation then raise WriteRejected
-      when PG::NotNullViolation, PG::CheckViolation then raise ValidationError, e.message
+      when PG::UniqueViolation, PG::ForeignKeyViolation, PG::RestrictViolation then raise WriteRejected, cause: nil
+      when PG::NotNullViolation, PG::CheckViolation then raise ValidationError, "write violates schema constraints", cause: nil
       else raise
       end
     end