pglpg 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ed878f97c7dcf3ffb630de85d798896dcbb6b0729e176ec410eb6383bd4659e
-  data.tar.gz: '055047480e44e5ff29ccaddce6d3ed730397dcffa243541c42e4c1e5b3c607ac'
+  metadata.gz: dcdce167b8e343909f06e710fdb65a1833a5cfa3649c85a475050c830a463a0d
+  data.tar.gz: f7725ba5bd6255af98a77875b766ac0e7d3a180f4af7ced79b50446998fbda6d
 SHA512:
-  metadata.gz: 516ba2fc4c42f933616e5b2ffae77a4c320f6a1bd400dcd332addb5884f19499bd97d8ce8ceebdaafc9ceba3e52ed822abe5c994e2e9aa072b0ec615a2908ecf
-  data.tar.gz: 0707c16c9bc2e84093a9423531eb802460c291f61362f5af788074a356f46c264f83419bc815399360231d943ab3f181f51f09247a24442f5bcb02d77fc04b72
+  metadata.gz: e536165dfa69606c33d7c15c4dd77c68878a3be01b6f8b7b097e4effd3597d26a6b65e2dd1c87d2ce5247c588980bebb779af6e674d4e29d84f3efcf05187b22
+  data.tar.gz: 7c6fbe3e465c7134ae05ec5601e61f941462687f60f1dd91242641b1ab22446e44d0f9836c3db4cb2ca6c330f0136ead5cd8c23c305eac300ff9d15374aa645a

data/CHANGELOG.md

@@ -1,5 +1,106 @@
 # Changelog
 
+## 0.4.0 (2026-11-04)
+
+### Added
+
+- `Context#parse_match(text, params: {})` builds a lazy query from a read-only
+  fixed-length GQL MATCH subset. It uses the Ruby query builder, named value
+  binds, and the caller’s visibility, date mode and execution limits. Malformed
+  query text and invalid parameters report located `Pglpg::ParseError` diagnostics.
+
+## 0.3.0 (2026-11-03)
+
+### Breaking
+
+- Temporal-capable reads require `graph.for(viewer:, as_of: Date)` or
+  `as_of: :any`; omitted/nil mode permits only node-only and statically
+  timeless-only reads. Generic edge Ref lookups in graphs with temporal types
+  require a mode even for missing edges. Date contexts refuse all data writes
+  with `ReadOnlyContext`, including model no-op saves and trusted-writer access.
+- Temporal inserts and every temporal upsert require explicit `valid_from:`
+  presence (nil is unbounded); omitted update bounds preserve stored values.
+  On upsert, an omitted upper bound is nil on insert and preserved on conflict.
+- Enabling temporal types on existing populated tables requires
+  `storage.enable_temporal!(types:, backfill: nil)` in an explicit migration.
+  Reserved `valid_from`/`valid_to` names must first be removed from application
+  declarations. Incompatible legacy columns require an application migration;
+  timestamp values are never silently cast to dates. The helper locks the
+  table and atomically installs metadata/checks plus an optional backfill.
+- Complete-key lookups validate literal component values: nil, arrays and
+  query conditions are refused before SQL, including on existing single/scoped
+  keys. Use `match` for structured property filters.
+- Adopting composite/edge keys or endpoint/property uniqueness requires
+  auditing and backfilling all required components, resolving duplicates and
+  running `storage.sync_constraints!` in the same application transaction.
+  New caller-chosen key forms require the trusted writer; unique components
+  cannot be changed and keyed edge upserts cannot rewire endpoints.
+- Opting a type into `open: true` rejects duplicate String/Symbol aliases for
+  declared fields as well as extras. Closed normalization is unchanged.
+  Openness inherits from any open parent; local false does not close it.
+  Closing/promoting declarations needs explicit data audit/backfill.
+
+### Added
+
+- Explicit `open: true` node and edge properties (ADR-0015), with openness
+  inherited from any open node parent. Closed remains the default. Declared
+  property/key checks, labels, endpoints, visibility and temporal rules remain.
+- Extra properties accept strict JSON-native scalars and flat homogeneous
+  scalar arrays; nil means absent/removal. Invalid names, duplicate aliases,
+  metadata/application-column collisions and unsupported values are refused
+  before the data statement. Open-type alias rejection includes declared
+  fields; closed normalization is unchanged. Extra decoded JSON values,
+  including historical map keys, are deeply frozen.
+- Model `extra_properties` remains read-only and declared saves preserve
+  extras. Query/filter/order/pluck still require declared properties. Openness
+  adds no DDL; closing/promoting types requires explicit application auditing
+  and backfill. Optional `pglpg_open_types` shared leak fixtures cover extras.
+
+- Composite node keys and edge property keys (ADR-0014): `key :a, :b` on
+  required string/integer/boolean/enum properties, with inherited node-key
+  domains and exact edge-type domains. General tuples and single non-string
+  keys require trusted insertion; legacy single-string generation and scoped
+  node occupancy grants retain their behavior. All components are immutable.
+  Unsupported edge scope declarations raise `SchemaError` explicitly.
+- `Context#find_edge(type, **key)` looks up a full edge property key through
+  current visibility on the edge and both endpoints, with the context's date.
+  Complete-key node/edge lookups validate literal values before SQL.
+- `unique: [:p, :q]` enforces a required endpoint/property tuple per edge type.
+  Trusted keyed edge upsert accepts `key:` and requires unchanged endpoints;
+  without a property key, upsert uses endpoint/property uniqueness. Constraints
+  are cumulative and span all dates. Uniqueness properties cannot be updated.
+- Composite/non-string model keys are required attributes, created through
+  `save(writer:)`; generated keys remain unassignable. Composite key readers
+  return frozen maps; legacy node scalar/scoped key readers stay scalar.
+  Adoption requires application backfill/deduplication and transactional
+  `sync_constraints!`; no automatic data migration is performed.
+
+- Context inspection shows an explicitly selected Date or `:any` read mode.
+- Opt-in `temporal: true` edge types (ADR-0013): exact Date metadata,
+  half-open `[valid_from, valid_to)` intervals, nil unbounded, finite dates
+  0001-01-01 through 9999-12-31. DateTime, Time and String are rejected.
+- Context-wide date eligibility on direct edge reads, every pattern and
+  reachability hop, models, lazy associations and eager batches, combined with
+  current visibility before counts, pagination, limits and completeness.
+  Timeless edges remain eligible; `:any` ignores only validity. This is valid
+  time on the stored graph, not historical values or historical permissions.
+- `TemporalModeRequired` and `TemporalMigrationRequired` errors. Generated
+  CHECK digests track explicit temporal enablement; changed/absent or
+  unvalidated checks on populated temporal types require acknowledgement.
+  Omitted backfill preserves bounds, and disabling types retains columns.
+- Edge values expose `temporal?`, `valid_from`, `valid_to`; temporal models
+  have strict metadata attributes, explicit nil assignment tracking and bound
+  pluck support. Lifetime pair uniqueness remains unchanged: gaps require
+  separate non-pair-unique episode Refs; overlaps are allowed.
+- Optional `pglpg_temporal` shared leak-fixture mode, and `bench/temporal.rb`
+  for same-fixture reference comparisons and temporal index experiments.
+
+### Security
+
+- Schema constraint failures use a generic ValidationError without a database
+  cause or stored-row detail. Temporal upsert argument validation is independent
+  of visible, hidden or absent pair occupancy.
+
 ## 0.2.0 (2026-10-30)
 
 ### Breaking

data/README.md

@@ -8,21 +8,81 @@ 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.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
+Status: **0.4.0 release candidate**, with a read-only text MATCH parser.
+The latest published version is 0.3.0. 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"
+gem "pglpg", "~> 0.3.0"
 ```
 
 Before 1.0, minor releases may break compatibility. Read the
-[0.2.0 upgrade notes](CHANGELOG.md) before upgrading from 0.1.
+[0.3.0 upgrade notes](CHANGELOG.md) and the migration steps below before
+upgrading from 0.2. Applications still on 0.1 must also apply the 0.2 notes.
+
+After 0.4.0 is published, use `gem "pglpg", "~> 0.4.0"`.
+
+## Upgrade from 0.3
+
+The parser is additive and requires no schema migration. Existing Ruby queries
+keep their behavior. Use text MATCH with named value parameters on an existing
+context:
+
+```ruby
+query = context.parse_match(
+  "MATCH (p:Person) WHERE p.name = $name RETURN p LIMIT 20",
+  params: { name: "Ann" }
+)
+query.to_a
+```
+
+Text supports fixed-length patterns and a subset of read clauses. It uses the
+context's visibility policy, date mode, and execution limits. See the
+[API contract](https://knowen.md/nodes/36329) for the grammar and error codes.
+
+## Upgrade from 0.2
+
+- Choose `as_of: Date` for dated reads or `as_of: :any` for all dates.
+  Omitted mode permits node-only/timeless-only reads; generic edge Ref lookup
+  needs a mode whenever the graph declares a temporal edge type. Dated
+  contexts are read-only, including model saves and trusted-writer access.
+- Temporal inserts and every upsert require explicit `valid_from:` (nil means
+  unbounded). Update omissions preserve bounds; an upsert's omitted upper
+  bound is nil on insert and preserved on conflict.
+- Before enabling temporal traffic on existing tables, finish an explicit
+  `enable_temporal!` migration. Remove conflicting application declarations,
+  audit legacy timestamps and `valid_until` boundaries, and convert them in
+  application migrations without silent truncation. Keep reads/writes disabled
+  during a deploy-then-migrate window. Retained temporal columns make every
+  constraint sync take an edge-table `ACCESS EXCLUSIVE` lock until outer commit;
+  schedule short migration transactions.
+- Adopt new key/uniqueness declarations with an explicit same-connection
+  transaction: backfill required components, resolve duplicates, then call
+  `sync_constraints!`. Composite/non-string keys and endpoint-unique edges
+  require trusted creation. Unique properties are immutable; keyed edge upsert
+  cannot rewire endpoints. Legacy single-string generation/scoped grants and
+  lifetime pair uniqueness retain their rules. Complete-key lookups take
+  literal values; use `match` for condition/array filters.
+- `open: true` is optional and changes no DDL. It rejects duplicate aliases across all
+  submitted properties, reserves structural/validity names even on other
+  element kinds/timeless graphs, and inherits from any open parent. Audit data
+  before closing a type or promoting extras to declarations. Queries and model
+  attributes still require declared properties; low-level writes and model
+  reload manage extras.
+
+Existing timeless, closed schemas with unchanged keys need no migration solely
+for the version bump. Rerun your real-policy leak suite and label-drift checks
+when adopting this minor release.
+
+This release implements a documented standards subset: key components are
+string/integer/boolean/enum, open extras are scalars/flat homogeneous lists,
+and temporal validity is one date interval with current authorization. It does
+not add alternate/overlap keys, open labels, dynamic query/model attributes,
+chained model associations or a GQL parser. Production-like acceptance remains
+separate pre-1.0 work; ordinary checks do not establish managed-plan capacity.
 
 ## Define a graph
 
@@ -57,8 +117,8 @@ 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.
+(`enum` takes `values:`, `list` takes `of:`). Types are closed by default: undeclared
+properties are rejected unless the type opts into open properties. A nil value means the property is absent.
 
 In a migration:
 
@@ -189,6 +249,165 @@ 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).
 
+## Composite and edge keys (0.3.0)
+
+Keys can use a tuple of required string, integer, boolean or enum properties:
+
+```ruby
+node :Document do
+  property :catalog, :string, required: true
+  property :number, :integer, required: true
+  key :catalog, :number
+end
+edge :CITES, from: :Document, to: :Document do
+  property :source, :string, required: true
+  property :external_id, :string, required: true
+  key :source, :external_id
+end
+```
+
+General tuples and single non-string keys require a trusted writer on insert.
+Single string keys retain automatic generation; existing scoped node keys
+retain their explicit occupancy grant. Edge keys are unique within the edge
+type, independently of endpoints. A keyed edge upsert requires the full key
+and the original endpoints; it cannot rewire a relationship.
+
+```ruby
+w = ctx.trusted_writer
+ref = w.upsert_node(:Document, key: { catalog: "main", number: 7 })
+ctx.find_node(:Document, catalog: "main", number: 7)
+w.upsert_edge(:CITES, from: ref, to: other,
+              key: { source: "archive", external_id: "citation-1" })
+ctx.find_edge(:CITES, source: "archive", external_id: "citation-1")
+```
+
+`unique: [:role]` on an edge type adds the required role to its endpoint-pair
+uniqueness tuple. It allows different roles between the same endpoints and
+requires trusted insertion/upsert. A declared `key` and `unique:` can coexist;
+keyed upsert uses the key, and both constraints still apply. All key and
+uniqueness properties are immutable, and uniqueness spans all validity dates.
+Symmetric types use the canonical unordered endpoint pair.
+
+Composite model attributes are required; create with `save(writer: w)` using
+the record's own context's writer. Generated model keys remain unassignable.
+Existing data needs an explicit transactional backfill/deduplication followed
+by `storage.sync_constraints!` on the same connection. No automatic migration
+runs when a declaration is loaded. Other property types, optional uniqueness
+and multiple alternate keys are outside this key API.
+
+## Open properties (0.3.0)
+
+Types stay closed by default. Opt in to extra properties explicitly:
+
+```ruby
+node :Person, open: true do
+  property :uid, :string, required: true
+  key :uid
+end
+edge :MENTIONS, from: :Person, to: :Person, open: true
+
+ref = ctx.insert_node(:Person, properties: { source_note: "archive", scores: [1, 2] })
+ctx.find(ref)[:scores] # => [1, 2], frozen
+ctx.update_node(ref, properties: { source_note: nil }) # removes the extra
+```
+
+An open parent makes its descendants open, including with multiple parents;
+`open: false` on a child does not close an open ancestor. Declared properties,
+keys, endpoints and generated labels retain their rules.
+
+Extras accept strings, integers, finite floats, booleans and flat homogeneous
+scalar arrays (including empty arrays). Nil means absent/removal. Maps, nested
+or mixed arrays, nil array members, Symbols, dates/times, decimals and custom
+objects need explicit application conversion or a declared property type.
+Extra names cannot collide with structural row names, regardless of element
+kind (so even a node extra cannot be named `type`, `source_id` or `target_id`).
+Validity names `valid_from`/`valid_to` are reserved even in wholly timeless
+graphs. Application-column names of that element kind are also reserved.
+Invalid names are refused. On open types, duplicate String/Symbol aliases are
+rejected for every submitted property, including declared properties. Closed
+types retain their existing last-alias normalization.
+
+Queries, ordering, model attributes and `pluck` still require declarations.
+Models expose extras through their read-only `extra_properties`; saving declared
+attributes preserves them. Write extras through `Context`/`Writer` and reload
+the model to refresh its map. No dynamic query casts or model setters are added.
+
+Extras carry application data and gain no automatic tenant/ACL or visibility
+semantics. Existing row/write policies still apply, and write policies can
+inspect submitted extras. Keep security-relevant fields in explicit declarations
+or application columns, with an explicit authorization policy.
+
+Openness alone adds no DDL. Closing a type preserves existing extra data on
+reads and declared-only updates; it refuses resubmitted unknown properties.
+Audit/backfill before closing types or promoting extras to typed declarations.
+Shape validation is at the library write boundary; raw SQL does not gain an
+open/closed constraint. The existing required-property and key checks remain.
+
+## Temporal edges (0.3.0)
+
+Opt in per edge type and use one date across the whole query:
+
+```ruby
+edge :MEMBER_OF, from: :Person, to: :Organization, temporal: true
+
+w = Kg.for(viewer: current_viewer)
+w.insert_edge(:MEMBER_OF, from: ann, to: org,
+              valid_from: Date.new(2020, 1, 1), valid_to: Date.new(2021, 1, 1),
+              attrs: { classification: 1 })
+
+at = Kg.for(viewer: current_viewer, as_of: Date.new(2020, 6, 1))
+at.match.node(:p, ref: ann).out(:MEMBER_OF, :o).to_a
+all_dates = Kg.for(viewer: current_viewer, as_of: :any)
+```
+
+Intervals include the start and exclude the end. Bounds are exact Ruby Dates
+in 0001–9999 or nil for unbounded; unknown/uncertain dates need separate
+application metadata. Required `valid_from:` presence on insert/upsert makes
+all-time intent explicit (`valid_from: nil`). Updates preserve omitted bounds;
+upserts preserve an omitted `valid_to` on conflict but use nil on insert.
+
+Date contexts are read-only, including model saves. Omitting `as_of` permits
+node-only and timeless-only reads; temporal reads raise `TemporalModeRequired`.
+Generic edge `find(ref)` requires a mode whenever the schema has a temporal
+type. `:any` remains writable and always retains current visibility. Dated
+reachability, models and preloads use the same date on every hop. This does not
+reconstruct old values, node existence or past permissions.
+
+`unique: :pair` still spans all dates. Leave/rejoin episodes with a gap need
+separate Refs on a non-pair-unique type; overlaps are allowed.
+
+Run the temporal migration before routing dated reads or temporal writes to the
+updated graph declaration. Loading `temporal: true` does not migrate its tables.
+During a deploy-then-migrate window, keep temporal edge operations disabled
+until the migration commits. Storage helpers report `TemporalMigrationRequired`;
+ordinary reads/writes do not inspect the catalog, so unmigrated operations may
+raise `ActiveRecord::StatementInvalid` with `PG::UndefinedColumn` instead.
+An explicit `:any` read can still work without date columns and does not prove
+that the migration is complete.
+
+For existing tables, remove conflicting application declarations and migrate
+incompatible legacy timestamp columns explicitly before enabling temporal types:
+
+```ruby
+Kg.storage.enable_temporal!(types: [:MEMBER_OF], backfill: ->(connection) {
+  # Explicit application backfill, on this connection, after checks are enabled.
+  # Without a callback, existing bounds are preserved; newly added NULL bounds
+  # deliberately mean all-time. Never invent dates or silently discard times.
+})
+```
+
+The helper locks the edge table, adds missing nullable date columns and runs
+constraint sync/backfill atomically. An outer transaction keeps its work pending
+until commit. Callback errors or invalid intervals roll everything back; the
+callback must not commit or switch connections. Callback idempotency is yours.
+Bare `sync_constraints!` refuses missing columns or unacknowledged populated
+temporal types. Once temporal columns exist, every synchronization takes an
+`ACCESS EXCLUSIVE` edge-table lock, including after the last temporal type is
+disabled and for unrelated schema changes. This blocks edge reads and writes
+until the caller's outer commit; keep the migration transaction short and
+schedule it accordingly. Physical columns remain after temporal types are disabled.
+See [ADR-0013](https://knowen.md/nodes/36532) for the complete contract.
+
 ## Leak specs for your policy
 
 ```ruby

data/lib/pglpg/context.rb

@@ -4,17 +4,20 @@ module Pglpg
   # A graph seen by one viewer. Created by Graph#for; immutable. Every query
   # and write built from it applies the graph's policies for this viewer.
   class Context
-    attr_reader :graph, :viewer
+    attr_reader :graph, :viewer, :as_of
 
-    def initialize(graph, viewer)
+    def initialize(graph, viewer, as_of: nil)
       @graph = graph
       @viewer = viewer
+      @as_of = as_of.equal?(:any) ? :any : Temporal.date(as_of, error: ArgumentError)
       freeze
     end
 
     # Starts a fixed-length pattern query.
     def match = Query.new(self)
 
+    def parse_match(text, params: {}) = MatchParser.new(self, text, params).parse
+
     # The visible node or edge behind +ref+, or nil. A hidden element and a
     # missing one look the same.
     def find(ref)
@@ -23,6 +26,7 @@ module Pglpg
       graph.check_ref!(ref, ref.kind)
       return match.node(:n, ref:).first&.fetch(:n) if ref.node?
 
+      temporal_mode!(graph.type.edge_types.values)
       sql = Sql.new(graph.connection)
       e = "e"
       sql << "SELECT to_jsonb(e) AS e FROM " << table_sql(graph.edges_table) << " AS e"
@@ -33,6 +37,7 @@ module Pglpg
       sql << " WHERE e.id = "
       sql.bind(ref.id, "bigint") << " AND "
       append_edge_visible(sql, e)
+      append_temporal(sql, e, graph.type.edge_types.values)
       row = read(sql).first
       row && graph.build_edge(JSON.parse(row["e"]))
     end
@@ -42,13 +47,25 @@ module Pglpg
     def find_node(type, **key)
       key = key.transform_keys(&:to_sym)
       node_type = graph.type.node_type!(type)
-      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
+      raise ArgumentError, "#{type} has no key" unless node_type.key
 
+      node_type.key.validate_values!(node_type, key)
       match.node(:n, type, **key).first&.fetch(:n)
     end
 
+    # Lookup by an exact edge property key. Compiler guards apply to the
+    # edge, both endpoints and the context's selected date.
+    def find_edge(type, **key)
+      edge_type = graph.type.edge_type!(type)
+      raise ArgumentError, "#{type} has no property key" unless edge_type.key
+
+      key = key.transform_keys(&:to_sym)
+      edge_type.key.validate_values!(edge_type, key)
+      query = match.node(:s)
+      query = query.public_send(edge_type.symmetric? ? :both : :out, type, :t, edge: :e)
+      query.where(e: key).return(:e).first&.fetch(:e)
+    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
@@ -63,9 +80,9 @@ module Pglpg
 
     def update_node(ref, properties: {}, attrs: {}) = writer.update_node(ref, properties:, attrs:)
 
-    def insert_edge(type, from:, to:, properties: {}, attrs: {}) = writer.insert_edge(type, from:, to:, properties:, attrs:)
+    def insert_edge(type, from:, to:, properties: {}, attrs: {}, **validity) = writer.insert_edge(type, from:, to:, properties:, attrs:, **validity)
 
-    def update_edge(ref, properties: {}, attrs: {}) = writer.update_edge(ref, properties:, attrs:)
+    def update_edge(ref, properties: {}, attrs: {}, **validity) = writer.update_edge(ref, properties:, attrs:, **validity)
 
     def delete_edge(ref) = writer.delete_edge(ref)
 
@@ -74,13 +91,43 @@ module Pglpg
     # callable approves this context. It does not bypass validation, the
     # write policy or endpoint checks.
     def trusted_writer
+      writable!
       allowed = graph.trusted_writer_allowed
       raise NotTrusted, "trusted writer not granted" unless allowed.respond_to?(:call) && allowed.call(self) == true
 
       Writer.new(self, trusted: true)
     end
 
-    def inspect = "#<Pglpg::Context #{graph.name} viewer=#{viewer.inspect}>"
+    def inspect
+      value = as_of.instance_of?(Date) ? as_of.iso8601 : as_of.inspect
+      mode = " as_of=#{value}" unless as_of.nil?
+      "#<Pglpg::Context #{graph.name} viewer=#{viewer.inspect}#{mode}>"
+    end
+
+    def writable!
+      raise ReadOnlyContext, "dated contexts are read-only" if as_of.instance_of?(Date)
+    end
+
+    def temporal_mode!(types)
+      if as_of.nil? && types.any?(&:temporal?)
+        raise TemporalModeRequired, "temporal reads require as_of: Date or :any"
+      end
+    end
+
+    # Appended alongside visibility, before every join/expansion/terminal.
+    def append_temporal(sql, name, types)
+      temporal_mode!(types)
+      temporal = types.select(&:temporal?)
+      return unless as_of.instance_of?(Date) && temporal.any?
+
+      sql << " AND ("
+      if temporal.size != types.size
+        sql << name << ".type <> ALL("
+        sql.bind_text_array(temporal.map(&:name)) << ") OR "
+      end
+      sql << "daterange(" << name << ".valid_from, " << name << ".valid_to, '[)') @> "
+      sql.bind(as_of.iso8601, "date") << ")"
+    end
 
     # -- internal ------------------------------------------------------------
 

data/lib/pglpg/element.rb

@@ -37,7 +37,7 @@ module Pglpg
   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:, symmetric: false)
+    def initialize(ref:, type:, source:, target:, properties:, attrs:, created_at:, updated_at:, symmetric: false, temporal: false, valid_from: nil, valid_to: nil)
       @ref = ref
       @type = type
       @source = source
@@ -46,6 +46,9 @@ module Pglpg
       @attrs = attrs
       @created_at = created_at
       @updated_at = updated_at
+      @temporal = temporal
+      @valid_from = valid_from
+      @valid_to = valid_to
       @symmetric = symmetric
       freeze
     end
@@ -54,6 +57,10 @@ module Pglpg
 
     def [](name) = properties[name.to_sym]
 
+    attr_reader :valid_from, :valid_to
+
+    def temporal? = @temporal
+
     def symmetric? = @symmetric
 
     # The endpoint opposite +ref+ (the same node for a self-loop).

data/lib/pglpg/errors.rb

@@ -4,12 +4,31 @@ module Pglpg
   # Base class for every error pglpg raises.
   class Error < StandardError; end
 
+  # Text MATCH errors report byte positions in the submitted query.
+  class ParseError < Error
+    attr_reader :code, :position, :line, :column, :token
+
+    def initialize(message, code:, text:, position:, token:)
+      @code = code
+      @position = position
+      prefix = text.byteslice(0, position).b
+      @line = prefix.count("\n") + 1
+      @column = position - (prefix.rindex("\n") || -1)
+      @token = token&.freeze
+      super("#{message} at line #{line}, column #{column}")
+    end
+  end
+
   # The graph type declaration is invalid.
   class SchemaError < Error; end
 
   # pglpg is used without a required policy or setting.
   class ConfigurationError < Error; end
 
+  class ReadOnlyContext < Error; end
+  class TemporalModeRequired < Error; end
+  class TemporalMigrationRequired < Error; end
+
   # A Ref belongs to another graph or is the wrong kind of element.
   class InvalidRef < Error; end
 

data/lib/pglpg/graph.rb

@@ -41,8 +41,8 @@ module Pglpg
 
     # The only entry point for queries and writes. The returned context is
     # immutable and carries the viewer to everything built from it.
-    def for(viewer:)
-      Context.new(self, viewer)
+    def for(viewer:, as_of: nil)
+      Context.new(self, viewer, as_of:)
     end
 
     def ref(kind, id) = Ref.new(graph: name, kind:, id:)
@@ -115,6 +115,9 @@ module Pglpg
         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"]),
+        temporal: edge_type&.temporal? || false,
+        valid_from: edge_type&.temporal? && row["valid_from"] ? Date.iso8601(row["valid_from"], Date::GREGORIAN).freeze : nil,
+        valid_to: edge_type&.temporal? && row["valid_to"] ? Date.iso8601(row["valid_to"], Date::GREGORIAN).freeze : nil,
         symmetric: edge_type&.symmetric? || false
       )
     end