pglpg 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64d4bfb95eeacd8297e72c8dc02b95bcda6354e5c3c157655483c13d78e9b9a8
-  data.tar.gz: c75cbedcd42f7fe07265f8aecfea1e78adc5e44f3651587b069955ea6c47f254
+  metadata.gz: 61a05d0f91dc037aefaaf82fa99143eae9a3c2742dd2308adcffa0d364b2f6fc
+  data.tar.gz: 1286500cadead4a337382e5bba4a5ec60bc861bcec88bfb04c07856aadaa4cf3
 SHA512:
-  metadata.gz: 1b0d31c4236eac2f7b3cb22b65d7650c1a01d3687ea5505b44e64b540e54f9d6e880344e2bbc1f90a6bb1512dcfdaad5c06ea0dc58ea621f768e82c50926e513
-  data.tar.gz: a8bcb6da10e7779df9409d7dc5923a0f172177d4d2acb8f695a347adf89019bc1d04b4a5187b8c85560b7043b171bfc0bc464c1256189c4ae43db59d5c4f0a5d
+  metadata.gz: c76e6ed407cbb7ef56cc9e79999cad98c91d67e7f46b08b2aba548c197cd52409b6d70ae83b029e032c9c3dcda1594a3825241727a0da45c91a553c456bead57
+  data.tar.gz: 5c4c89d4af4a6f57988a734cc0d154b9b9c96a8dea5a15c51b7ab3802078f27d5468e7f42c6e98a6698befca2cb58c9ce7e5c9cc44e0482470d157951100a804

data/CHANGELOG.md

@@ -1,5 +1,254 @@
 # Changelog
 
+## 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
+
+- 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,65 @@ 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.3.0 release candidate; not yet published.** The latest published
+version is 0.2.0. This candidate includes temporal edges, composite/edge keys
+and explicit open properties. 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 0.3.0 publication:
+
+```ruby
+gem "pglpg", "~> 0.3.0"
+```
+
+Before 1.0, minor releases may break compatibility. Read the
+[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.
+
+## 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 candidate 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
 
 ```ruby
@@ -36,12 +91,17 @@ 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.
+(`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:
 
@@ -118,6 +178,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 +189,208 @@ 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).
+
+## Composite and edge keys (0.3.0 candidate)
+
+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 candidate)
+
+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 candidate)
+
+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/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