[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 client onto the coordinator, so that every build runs through build_release(), and removes the old build path.

Details

After #654, the client is the last caller of the old build path (TNET-157). It still builds through ConnectorBuilder.build() and build_one(), so the builder protocol keeps two ways to build.

• The client builds a missing version and a missing payload source with build_release(). It maps its fetch_from and auto_build onto build_release(), with build_parents set.
• A version that the connector does not declare raises TimeNetVersionUnavailableError before the build starts.
• The isolated child of a client build prints its shards and downloads to stderr, as before.
• The BuilderBackend protocol loses knows(), declared_version() and the old build(). build_prepared() is now build(), so a backend implements dataset_ids(), card() and build(). The hidden command keeps its name, build-prepared-release. ConnectorBuilder.card() returns None for a spelling that no card declares.
• run_isolated(), build_one() and its helpers, prepare_parents() and the hidden --pinned-by option of build go away.
• timenet.engine.publish_pipeline() goes away too. open_parents() takes the LocalRegistry that the build writes to.
• put_dataset(force=True) on a remote or S3 registry raises TimeFValidationError before it uploads, because a published version never changes.
• timenet_connectors.builder imports none of its modules. So loading the backend through its entry point loads neither Typer nor the console of the CLI. A test makes sure of that.
• About 1350 of the 1730 changed lines are deletions.

Design decisions

• Each backend builds every release that it claims, the requested release too. build_one() always built the requested release on the built-in path. So a subclass of ConnectorBuilder that overrides build() now builds all of its releases through it.
• The client copies a parent like the build command does, with each payload source at every depth.
• The import test does not check rich, because httpx loads rich whenever rich is installed.

Breaking changes

• BuilderBackend no longer has knows() and declared_version(), and build() takes (release, store, *, force, pinned_by, options). A backend of another package must implement dataset_ids(), card() and the new build().
• timenet.engine.publish_pipeline() is gone. Build with run_pipeline(), then publish with copy_release().
• open_parents() takes a LocalRegistry. It no longer opens parents from a remote registry.
• put_dataset(force=True) on a remote or S3 registry raises TimeFValidationError.
• timenet_connectors.builder no longer exports app and main. Import them from timenet_connectors.builder.cli.
• The hidden --pinned-by option of timenet-build build is gone.
• timenet_connectors.discovery.has_connector() is gone, because nothing calls it now.
• TimeNet.open() and TimeNet.load() raise TimeNetVersionUnavailableError for a version that the connector does not declare. It is a TimeNetDatasetNotFoundError, as before.

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.
• The mapping of fetch_from and auto_build onto build_release() in _obtain() and _prepare() is thin glue. "Client reads on the coordinator" replaces it with the entry machinery.

Merge message

feat(build)!: run every build through the coordinator

The client builds through build_release() too, so the old build path
goes away and a backend has one way to build.

- The client maps fetch_from and auto_build onto build_release(), and
  copies parents with each payload source at every depth.
- Each backend builds every release that it claims, the requested
  release too.
- put_dataset(force=True) on a remote or S3 registry refuses before it
  uploads, because a published version never changes.
- Loading the backend through its entry point loads neither Typer nor
  the console of the CLI.

BREAKING CHANGE: BuilderBackend loses knows() and declared_version(),
and build() takes (release, store, *, force, pinned_by, options).

BREAKING CHANGE: run_isolated(), build_one(), prepare_parents(),
publish_pipeline(), has_connector() and the hidden --pinned-by option
of timenet-build build are gone.

BREAKING CHANGE: open_parents() takes a LocalRegistry, and
timenet_connectors.builder no longer exports app and main.

[TimoStoff]

Why can't they all be like this 😍

[claude]

I reviewed this PR and found no bugs. It is a large breaking change to the public builder protocol, the client's build path and the remote put_dataset behaviour, so a human should still look at it. New commits were also pushed after the existing approval.

What was reviewed:

• _obtain and _prepare in client.py now go through build_release(). A pinned version is passed as id@ version and "latest" sentinels are passed as a bare ID. The payload-source builds still get their pinned_by pins.
• plan_parents/_locate now take only a LocalRegistry. Because the output is always local, the old remote-output guard and the requires_open_access handling are no longer needed. LazyReadRegistry.put_dataset(force=True) raises before it stages anything.
• run_isolated_build and _run_build in env.py: with the child's stdout sent to DEVNULL, reading stderr inline cannot deadlock. I also checked the candidate concern that third-party backends still on the old build() signature would get a TypeError. I ruled it out because the PR declares that protocol break.

Extended reasoning...

The change touches 25 files across timenet and timenet-connectors, about 350 lines added and 1,280 removed. It removes knows(), declared_version(), build_one(), run_isolated(), prepare_parents(), publish_pipeline() and has_connector(), and changes the BuilderBackend.build() signature. It also routes the client's missing-version and payload-source builds through coordinator.build_release(), and makes put_dataset(force=True) refuse on remote and S3 registries. The only security-relevant surface is the subprocess call in env.py, which still runs a fixed argument vector, plus the existing open-access checks. I deferred because of the size and the breaking changes to the public and plugin API, and because commits landed after the human approval.

[claude]

Code review found no issues

No high-confidence issues detected in this change.

[claude]

Code review found no issues

No high-confidence issues detected in this change.