feat(#1424): self.upstream property for pre-restricted ancestor access

[dimitri-yatsenko]

Summary

T2.2.b of the provenance trinity. Inside `make()`, `self.upstream` exposes a pre-constructed `Diagram.trace(self & key)` so user code can read declared ancestors with provenance-safe, ergonomic syntax.

Closes #1424. Slated for DataJoint 2.3.

Branch dependency

Stacked on `feat/1423-diagram-trace` (#1471). This PR's base is `feat/1423-diagram-trace`, not `master`. Will rebase onto master once #1471 (and its parent #1468) merge.

What's added

Component	File
`AutoPopulate._upstream` (class attr, instance storage)	`src/datajoint/autopopulate.py`
`AutoPopulate.upstream` property — returns the trace inside `make()`, raises with a helpful message outside	`src/datajoint/autopopulate.py`
Wire `self._upstream = Diagram.trace(self & dict(key))` into `_populate_one()` before `make()`; clear in the existing `finally` block	`src/datajoint/autopopulate.py`
5 integration tests covering: basic pre-restricted read, non-ancestor rejection, unset-outside-make error, stale-state cleanup, tripartite-make consistency	`tests/integration/test_autopopulate.py`

Design notes

• Lazy construction: `Diagram.trace(self & dict(key))` only does a graph copy at the `_populate_one` layer. The expensive SQL fetch fires when the user accesses `self.upstream[T].fetch(...)`. Cheap for `make()` bodies that don't use `self.upstream`.
• No `make()` signature change: `self.upstream` is a new attribute on `self`, not a new parameter. Existing `make()` implementations are unaffected.
• Tripartite-safe: `self._upstream` is set once before all three invocation sites (lines 616, 619, 625). All three phases see the same upstream view.
• No stale state: the existing `finally` block (line 716) that resets `_allow_insert` now also resets `_upstream`, so subsequent attribute access raises a clear error rather than silently using a stale trace.

Tests

• 5/5 new upstream tests pass on MySQL.
• 17/17 existing autopopulate tests pass — no regression.

Sequencing

Once this PR merges, T2.2.c (`strict_provenance` config flag, the runtime gate) goes next. It branches off this PR.

Test plan

• 5/5 new tests pass
• 17/17 autopopulate regression tests pass
• CI green (after fix(#1429): cascade through FK chain for part_integrity="cascade" #1468 + feat(#1423): Diagram.trace() for upstream restriction propagation #1471 merge and this PR rebases onto master)

[ttngu207]

The logic here is sound. _upstream is instance-level (not class-level like _allow_insert), set immediately before make() and cleared in a finally that also covers the exception branch, fresh per key and per populate() call, and genuinely tripartite- and multiprocess-safe (constructed once, all three phases read the same object; each worker unpickles its own instance). No leakage across keys or populates. self & dict(key) is the right, non-mutating seed.

One gap worth closing: the two guarantees this design most needs to prove are effectively untested.

• test_upstream_cleared_after_make probes Derived().upstream on a brand-new instance, but populate() runs make() on a throwaway cls() (via TableMeta.__getattribute__). The probe instance's _upstream was never set — it's the class default None — so this test would pass even if the finally: self._upstream = None line were deleted.
• No test lets make() itself raise, so the exception-path cleanup (the whole reason the reset is in finally rather than after make()) has zero coverage.

Suggest a test that captures the populate instance (inst = Derived(); inst.populate(); assert inst.upstream raises) and one that forces an exception through make() then asserts the context is clean. Everything else looks good.