[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 the timenet-build build command and timenet_connectors.build() onto the coordinator.

Details

The timenet-build build command and timenet_connectors.build() still plan and build through build_one(), next to the coordinator of #652 (TNET-157). A remote --out builds and publishes in one step, and there --force can overwrite a published version.

• The build command and timenet_connectors.build() build through build_release().
• A local --out gets the release in place.
• A remote --out gets the release in two steps. First, the release builds into the default local registry with open_access_only set. So a release that does not declare access open fails before any download. Then copy_release() publishes the release and its payload sources.
• If the remote registry already holds the version, nothing builds, and the command says so on stderr.
• The parents now land in the local registry. Without --fetch-from, a remote --out copies the missing parents from the remote, as before. --fetch-from works with a remote --out too.
• The build command shows its progress with progress_renderer() of feat(build)!: build one prepared release in the built-in backend #653, which shows the copy steps and the build steps. It is the only place that chooses between no output, text lines and live bars.
• --isolation and --no-isolation set the new BuildOptions.isolation, which overrides TIMENET_ISOLATION for the build. The process environment does not change. --quiet also silences the isolated child.
• timenet_connectors.build() accepts only the dataset ID that a card declares. It and the build command take the release that the card declares from builders.declared().

Design decisions

• A remote --out is a local build plus a copy, and the copy never changes a published version. So --force with a remote --out that already holds the version is a usage error, before any download.
• A copy step takes a parent with each payload source at every depth, as copy_release() in feat(registry)!: copy a release between registries #649 does. The old path copied only the direct payload sources. The registry to copy from can hold a payload source without its own payload sources. Then the copy now fails with TimeNetMissingParentError. Every registry must hold the payload sources of every release that it holds.
• With isolation on, the parent shows each copy and build step, and the child shows its own downloads and shards.

Breaking changes

• timenet_connectors.build() raises TimeNetDatasetNotFoundError, not LookupError, for a dataset ID that no card declares, such as timenet/hello_world. For another version, it raises TimeNetVersionUnavailableError, which is a TimeFValidationError.
• --force with a remote --out that already holds the version is now a usage error. Before, it published the version again.

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.
• build_one() and the hidden --pinned-by option of build stay, because the client still uses them through ConnectorBuilder.build(). feat(build)!: run every build through the coordinator #655 moves the client onto the coordinator and removes them.

Merge message

feat(build)!: move the build CLI and build() onto the coordinator

The timenet-build build command and timenet_connectors.build() build
through build_release(), so they share one planner.

- A remote --out builds into the default local registry first, with
  open_access_only set, and then publishes with copy_release(). If the
  remote already holds the version, nothing builds.
- A copy step takes each payload source of a parent at every depth.
  Every registry must hold the payload sources of each of its
  releases.
- --isolation and --no-isolation set BuildOptions.isolation for the
  build and leave the environment unchanged.

BREAKING CHANGE: timenet_connectors.build() raises
TimeNetDatasetNotFoundError instead of LookupError for an unknown
dataset ID.

BREAKING CHANGE: --force with a remote --out that already holds the
version is a usage error. Before, it published the version again.

[claude]

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

[claude]

Code review completed

Nothing new to post: everything this review found is already covered by existing comments on this pull request or didn't merit a separate one.

[claude]

Code review completed

Nothing new to post: everything this review found is already covered by existing comments on this pull request or didn't merit a separate one.