Make key_source restrict-only: add key_source_restriction, deprecate parent-redefining overrides

[dimitri-yatsenko]

Summary

Make key_source a restrict-only surface. Today key_source can be overridden freely, including in ways that redefine the parent join — and that is the source of subtle, hard-to-diagnose bugs. Introduce a first-class key_source_restriction that applies a restriction to the default key_source without changing the parents, and steer users (and the docs) toward it.

Background

key_source defaults to the join of the tables referenced by the foreign keys in a computed/imported table's primary key (Autopopulate → Key Source Calculation). populate() iterates over it, passing each key to make(key).

The default is almost always correct. In practice, the only legitimate reason to modify it is to restrict it — compute a subset of the default source (e.g. a completion barrier that fires only when all members of a batch have results). Restricting keeps the parents and the grain intact; each make(key) still receives a fully-formed primary key.

Overriding key_source to redefine the parent join — dropping a parent, adding one, or reconstructing the key from an aggregate — is a different and dangerous operation: it can change or drop primary-key attributes, so make(key) receives a key that is missing attributes or has attributes the table's primary key doesn't declare. The downstream effects (partial inserts, mismatched keys, silent miscomputation) are hard to reason about, and the framework was not designed for it.

Proposal

1. Introduce key_source_restriction — a declared restriction applied to the default key_source. It may be any valid DataJoint restriction, including a restriction by another table (a dependency visible in key_source but not necessarily as a formal FK edge). The computed source is default_key_source & key_source_restriction; the parents and grain are never changed.
2. Deprecate user-facing redefinition of key_source. Treat key_source as an internal of the auto-populate machinery. Emit a warning when a subclass overrides key_source in a way that changes the parent join.
3. Batching is a master–part concern, not a key_source concern. A run/cohort-level batch should be a master keyed on the batch with per-member results on a part — consistent with the DataJoint 2 rule that an auto-populated table introduces no new dimension (only its parts may). This removes the historical "batch by overriding key_source" motivation.

Rollout (per the 2026-07-24 design discussion)

• 2.4: add key_source_restriction; begin warning on parent-redefining key_source overrides.
• Docs now: remove key_source-override guidance/recommendations from the documentation; document key_source_restriction as the supported way to narrow a source.
• Later: make key_source restriction-only (the override path removed as a user surface).

Docs task (coordinated)

datajoint-docs: pull any recommendation to override key_source, and document key_source_restriction + the "batch via master–part" guidance. (Autopopulate spec §2 and the how-to pages.)

cc @MilagrosMarin @ttngu207