Introduce decoupled query constraints for associations - #58266

Introduce decoupled query_constraints for associations

Reintroduces query_constraints on associations, decoupled from foreign_key.

Motivation

query_constraints is deprecated, and the way to scope a belongs_to by an
extra column (a shard or tenant) today is to list it inside foreign_key as an
array:

belongs_to :post, foreign_key: [:account_id, :post_id]

Active Record treats every column in that array as part of the foreign key, so
the tenant column (account_id) gets nulled on clear and reassigned on set
(see #49671 and #57906).

This change reintroduces query_constraints as a query-only option layered
on top of foreign_key, separate from it. With the shard column expressed as
additive query scope rather than part of the foreign key, it is excluded from
nullification by construction: the column was never one of the things clearing
the association touches.

Mental model

query_constraints declares additional columns to match when querying an
association's targets. They participate in loading, preloading, eager loading,
joins, and association predicates. The foreign key always participates because
an association cannot be queried without it.

• When only foreign_key is given, behavior is unchanged.
• When query_constraints is given, foreign_key handles writes while queries
  match on the foreign key plus the additional columns.
• When query_constraints is given without an explicit foreign_key, the
  foreign key is derived by convention.
• Query constraint columns must be distinct from explicit or derived foreign key
  columns; overlapping configurations raise ArgumentError when the reflection
  is validated.

Nullify / assign behavior: clearing an association nulls only the
foreign_key; query_constraints columns are never written or nulled because
they scope the owner rather than point at the target.

The common case: the foreign key stays conventional

Because query_constraints no longer redefines the foreign key, the common case
only needs to name the additional query column:

# post_id is derived and is the only column written or nulled;
# account_id is added purely to scope queries
belongs_to :post, query_constraints: :account_id

This is equivalent to spelling out the conventional key:

belongs_to :post, foreign_key: :post_id, query_constraints: :account_id

An explicit foreign_key remains available for non-conventional associations.

Two sides of a constraint (advanced)

A column can have a different name on each side. query_constraints accepts
symbols (same name on both sides) and hashes (self_column => target_column):

class BlogPost < ApplicationRecord
  belongs_to :featured_comment,
    class_name: "Comment",
    foreign_key: :featured_comment_id,
    query_constraints: [:blog_id, { id: :blog_post_id }]
  #   :blog_id              -> blog_id on both tables
  #   { id: :blog_post_id } -> BlogPost#id matches Comment#blog_post_id
end

Resulting join keys:

• self (BlogPost) columns: ["blog_id", "id", "featured_comment_id"]
• target (Comment) columns: ["blog_id", "blog_post_id", "id"]

A Hash mapping requires an explicit foreign_key because a foreign key cannot
be derived from a renamed pair.

Implementation

• New reflection methods query_constraints_foreign_key,
  normalized_query_constraints_mapping, and
  join_query_constraints_{primary,foreign}_key /
  join_query_constraints_id_for separate writable keys from query keys.
• Join (join_scope, AssociationScope) and preload paths resolve keys through
  the query-constraint methods, falling back to existing join_* behavior when
  no association query constraints are present.
• foreign_key, active_record_primary_key, and autosave continue to expose and
  write only the explicit or conventionally derived foreign key.
• Array-valued foreign_key options retain their composite writable-key
  semantics; their origin is tracked separately from user-supplied
  query_constraints.
• ThroughReflection, PolymorphicReflection, and RuntimeReflection delegate
  the new methods in lockstep with their join_* counterparts.

Backward compatibility

Existing composite foreign_key: [...] associations, including composite
primary key associations, keep working as today: all columns remain part of the
foreign key and are written and nulled as a unit.

Associations without query_constraints are unchanged. When
query_constraints is present, decoupled behavior applies with either an
explicit or conventionally derived foreign key. Hash mappings still require an
explicit foreign_key.