[karhu]

The Stack

This stack covers refactoring the internal logic of how releases are resolved during read, download & build, in particular also in the context of parent releases / parent datasets. On top of that it refactors the public TimeNet APIs and CLI interfaces around these actions, to streamline the behavior across them.

This PR

Moves open(), load() and open_torch() of the client onto read_release().

Details

The client still opens a release through its own steps: _prepare(), _obtain() and _require_open() (TNET-157). #659 adds the read coordinator. This PR moves the client onto it.

• open(), load() and open_torch() read through read_release(). A read opens each release where it is and copies nothing.
• A local client asks its own registry first, then the registry that fetch_from names. If auto_build is set, it then asks the installed connectors. A remote client asks only its own registry and never builds.
• _read_sources() maps fetch_from and auto_build onto that list of sources.
• The error hints still name the two keywords. A missing release or payload source names each keyword that the call did not use. An access error on a local client with auto_build=False names auto_build=True.
• _prepare(), _obtain() and _require_open() go away, and so does the before_fetch callback of prepare_local_copy(), which had no other caller.

Design decisions

• The client reads in place, as the design asks. A copy into the local registry is the job of download(), which a later PR moves onto the same list.
• Hints name a keyword only on a local client. A remote client cannot use fetch_from and never builds, so its errors name no keyword, except its hint to build the dataset locally.

Breaking changes

• open(fetch_from=...) reads in place and copies nothing into the local registry.
• A damaged local copy raises TimeNetFileError also with fetch_from, and the error has no repair hint.
• "latest" (org/name@latest) is the highest version across the local registry, fetch_from and, with auto_build, the installed connectors. So a read can build a newer version that a connector declares.
• Without a version, open(), load() and open_torch() read the newest version of the first source that serves the dataset. With @latest, they ask every source, so each registry must be reachable.
• A payload source that the local registry lacks is read from fetch_from in place.
• If auto_build is set, a registry that lists a release without serving it falls through to a build, also for a read.
• The before_fetch argument of prepare_local_copy() is gone.

Stack

• docs: update the docs for the build coordinator #683
• feat(hints)!: give every error one hint for the SDK and one for the CLI #698
• feat(cache)!: record where each release in the local registry comes from #674
• feat(client)!: list and search every source #673
• feat(client)!: replace get() with get_manifest() and get_card() #672
• feat(build)!: build into the local registry, publish with --publish-to #671
• feat!: add timenet.build() and publish() #670
• feat(cli)!: take --local-registry, --remote-registry and --auto-build #669
• feat(config)!: make the default list of sources from three variables #668
• test: isolate every test from the real home and guard it #667
• feat(client)!: download releases into the local registry #662
• feat(client)!: take an ordered list of sources #661
• 👉 feat(client)!: read releases through the coordinator #660
• feat(coordinator)!: plan and run reads through the list of sources #659
• feat(coordinator)!: plan parents through an ordered list of sources #658
• feat(sources)!: resolve a release through an ordered list of sources #657
• feat(build)!: run every build through the coordinator #655
• feat(build)!: move the build CLI and build() onto the coordinator #654
• feat(build)!: build one prepared release in the built-in backend #653
• feat(coordinator)!: plan and run builds through build_release #652
• refactor(coordinator)!: name the plan step type Step #651
• feat(registry)!: copy a release between registries #649
• feat(registry)!: publish a local release with put_release #648
• refactor(build)!: let the connector choose the values backend #646

Changes later in the stack:

• docs: update the docs for the build coordinator #683 holds the doc changes of this PR.
• _read_sources(), _missing_hint() and the auto_build=True access hint are thin glue. The next PR replaces them with TimeNet(sources=[...]).

Merge message

feat(client)!: read releases through the coordinator

open(), load() and open_torch() read through read_release(), so a read
opens each release in place and copies nothing.

- A local client asks its own registry, then fetch_from, and then the
  installed connectors if auto_build is set. A remote client asks only
  its own registry and never builds.
- Error hints name each keyword that the call did not use.

BREAKING CHANGE: open(fetch_from=...) reads in place and no longer
copies into the local registry. A payload source that the local
registry lacks is also read from fetch_from in place.

BREAKING CHANGE: "latest" takes the highest version of every source,
so each registry must be reachable. With auto_build, the read can
build a newer version that a connector declares.

BREAKING CHANGE: A damaged local copy raises TimeNetFileError also
with fetch_from. prepare_local_copy() loses before_fetch.

[claude]

Findings marked 🟡 are optional suggestions and need no follow-up push.

[claude]

No new blocking issues. 1 optional suggestion (a nit or a note on pre-existing code) was found and not posted. Nothing in this review needs a push before merging.

[claude]

Code review found no issues

No high-confidence issues detected in this change.