[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

Every TimeNet error gets one hint: the call or the command that gets the user out of the situation. The SDK names Python calls, and both CLIs name commands and flags.

Details

• An error message states facts only. TimeNetError has a hint, and str() puts it after the message.
• The new private module timenet._hints picks the hint from the facts of the call: the sources, the store, the request and the flags of a command. The client, timenet.build(), plan_build() and publish() use the SDK wording. timenet and timenet-build use the CLI wording.
• A hint names only a call or a command that works in that situation. So it looks at the registries, the installed connectors and the versions that they provide:
  • A release that no source provides names a registry to add. If a connector builds the release, it also names the installed connectors. If no connector package is installed, it names one.
  • A damaged copy in the store names a download from a registry, else a forced build, else a registry to add. A failed transfer gets no hint.
  • A download of the latest version that only a connector provides names the build and the exact version that a registry holds.
  • A version conflict with the store names the copy to delete. A conflict on publish names a new version.
  • A registry that cannot be reached, over HTTP or S3, names the version in the store.
  • A stored manifest that is not valid names the folder to delete.
  • An isolated build that cannot make its environment names --no-isolation or TIMENET_ISOLATION=off.
• TimeNetManifestError and TimeNetIsolationError mark the last two situations. They subclass TimeFFormatError and TimeNetBuildError.
• A registry flag that names no registry (--local-registry, --remote-registry, --publish-to, --dest, --source) is a usage error. It exits with code 2 and names the flag. A bad TIMENET_* variable still exits with code 1 and names the variable.
• timenet-build build --publish-to compares the release in the store with the release in the destination. For another release, it raises TimeNetVersionConflictError before the build. If the store lacks the release and the destination holds the version, the command prints "Nothing to do" and builds nothing. With --force, it builds again, and the publish compares the files.
• The root help of timenet says what the tool does, and timenet-build build --help no longer shows a Raises section.
• Size: about 1880 changed lines: about 1260 in the source and 620 in tests. About 690 are deletions, because the hint helpers of the client, the build CLI and the consumer CLI move into one module.

Design decisions

• The hint is separate from the message. So the SDK and the CLI share one error and differ only in the advice, and a caller can read the facts without the advice.
• One module writes every hint, in both wordings. Before, three places wrote their own, and the CLI showed SDK advice.
• A hint never suggests a command that fails. For example, a damaged manifest gets "delete the folder", because a download or a build reads that manifest first and fails.
• --publish-to without --force trusts a destination that holds the version. A rebuild only to compare costs a full build, so --force makes that check explicit.
• The two new error classes let the hint layer tell these situations apart without parsing messages.

Breaking changes

• Error messages no longer contain remedies. The remedy is in error.hint, which str() shows after the message.
• A registry flag that names no registry exits with code 2, not 1.
• If the store holds another release than the destination, timenet-build build --publish-to raises TimeNetVersionConflictError.
• The message for an empty setting no longer names a flag.

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.

Merge message

feat(hints)!: give every error one hint for the SDK and one for the CLI

Every TimeNet error gets one hint: the call or the command that gets the
user out of the situation. The message states only facts, and str()
shows the hint after it.

- timenet._hints picks the hint from the facts of the call: the sources,
  the local registry, the request and the flags. The SDK names Python
  calls, and both CLIs name commands and flags.
- A hint names only a call or a command that works in that situation.
- TimeNetUnreachableError, TimeNetManifestError, TimeNetOriginError and
  TimeNetIsolationError mark an unreachable registry, an invalid stored
  manifest, an invalid origin record and an isolated build that cannot
  make its environment.
- timenet-build build --publish-to refuses another release in the
  destination before the build.

BREAKING CHANGE: Error messages no longer contain remedies. The remedy
is in error.hint.

BREAKING CHANGE: A registry flag that names no registry is a usage error
and exits with code 2, not 1.

[TimoStoff]

LGTM!

[claude]

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

[claude]

Code review found no issues

No high-confidence issues detected in this change.

[claude]

⚠️ Code review skipped: your organization has reached its API usage limit, so Code Review can't run right now.

An organization admin can review the limit in your organization's usage and billing settings.

Once the limit resets or is raised, someone with write access to this repository can comment @claude review on this pull request to trigger a review.