dosync 0.4.2__tar.gz → 0.4.3__tar.gz

{dosync-0.4.2 → dosync-0.4.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dosync
-Version: 0.4.2
+Version: 0.4.3
 Summary: The semantic layer between AI agents and physical devices
 Author-email: Rodrigo Giuliani <rgiuliani@dosync.dev>
 License-Expression: Apache-2.0

{dosync-0.4.2 → dosync-0.4.3}/dosync/__init__.py

@@ -13,5 +13,5 @@ The two numbers move independently on purpose:
   __version__           this implementation of the hub  (semver)
   __protocol_version__  the wire contract other implementations must match
 """
-__version__ = "0.4.2"
+__version__ = "0.4.3"
 __protocol_version__ = "0.4"

{dosync-0.4.2 → dosync-0.4.3}/dosync/cli.py

@@ -53,6 +53,24 @@ def hub(argv=None) -> None:
     os.environ["DOSYNC_PORT"] = str(args.port)
     os.environ["DOSYNC_HOST"] = args.host
 
+    # Binding to loopback is the right default — a hub reachable from the whole
+    # network because nobody chose that is worse than one that needs a flag. But
+    # the commonest deployment is a headless Raspberry Pi whose operator is on
+    # SSH and wants the dashboard from their laptop, and "Uvicorn running on
+    # http://127.0.0.1" does not tell them why their browser cannot connect.
+    #
+    # Found by installing from PyPI on a clean machine and trying to open the
+    # dashboard from another one. The default does not change; the silence does.
+    if args.host in ("127.0.0.1", "localhost", "::1"):
+        print()
+        print("  Listening on loopback only — reachable from this machine at")
+        print(f"      http://localhost:{args.port}")
+        print("  To reach it from another machine on your network:")
+        print(f"      dosync-hub --host 0.0.0.0 --port {args.port}")
+        print("  (that exposes the hub to your local network; it keeps requiring")
+        print("   a token, and TLS is a separate step — see setup_pki.sh)")
+        print()
+
     uvicorn.run("dosync.server:app", host=args.host, port=args.port,
                 reload=args.reload, log_level=args.log_level)
 

{dosync-0.4.2 → dosync-0.4.3}/dosync/declarative.py

@@ -281,7 +281,8 @@ def load_directory(directory: str = None) -> list[tuple[Any, dict]]:
     the hub running to fix it.
     """
     if directory is None:
-        directory = os.environ.get("DOSYNC_DECLARATIVE_DIR", "declarative")
+        from .paths import resolve_config_dir
+        directory = str(resolve_config_dir("declarative", "DOSYNC_DECLARATIVE_DIR"))
     path = Path(directory)
     if not path.is_dir():
         return []

{dosync-0.4.2 → dosync-0.4.3}/dosync/hub.py

@@ -1639,7 +1639,9 @@ class DoSyncHub:
                         "A rewritten history will not be detectable.", interval)
             return
         if directory is None:
-            directory = os.environ.get("DOSYNC_CHECKPOINT_DIR", "checkpoints")
+            from .paths import resolve_state
+            directory = str(resolve_state("checkpoints", "DOSYNC_CHECKPOINT_DIR",
+                                          create=True))
 
         _export = os.environ.get("DOSYNC_CHECKPOINT_EXPORT_DIR")
         log.info("Audit checkpoints scheduled every %.0fs → %s", interval, directory)
@@ -1699,7 +1701,9 @@ class DoSyncHub:
         from . import audit_backup, cert_signing
 
         if directory is None:
-            directory = os.environ.get("DOSYNC_CHECKPOINT_DIR", "checkpoints")
+            from .paths import resolve_state
+            directory = str(resolve_state("checkpoints", "DOSYNC_CHECKPOINT_DIR",
+                                          create=True))
 
         # The mark must be current before attesting to it.
         self.audit_log.flush_head()
@@ -1832,7 +1836,8 @@ class DoSyncHub:
         if keep <= 0:
             return None
         if directory is None:
-            directory = os.environ.get("DOSYNC_ARCHIVE_DIR", "audit-segments")
+            from .paths import resolve_state
+            directory = str(resolve_state("audit-segments", "DOSYNC_ARCHIVE_DIR", create=True))
 
         entries = self.audit_log.entries()
         if len(entries) <= keep:

dosync-0.4.3/dosync/paths.py

@@ -0,0 +1,224 @@
+"""Where a DoSync deployment keeps its configuration and its state.
+
+Found while preparing to reflash the reference deployment: its configuration
+lived in nine places, four of which the author did not remember existed, and
+three of those were **inside a git clone**. A `git clean -fdx` — a command people
+run to tidy a repository — would have destroyed a 42,000-entry audit chain and
+the CA's private key.
+
+That is worth stating plainly, because it is a contradiction: this protocol
+argues that its evidence survives someone with root access, and until now it did
+not survive someone tidying up. The sophisticated threat was covered and the
+trivial one was not.
+
+Two modes, because there are two ways to install
+------------------------------------------------
+`pipx install dosync` runs as an ordinary user, who cannot write to `/etc` or
+`/var/lib`. A systemd service running as root can and should. Rather than pick
+one and break the other, paths cascade: the user location first, the system
+location second. The same binary serves both, and neither needs configuration to
+work.
+
+    Configuration   ~/.config/dosync/            →  /etc/dosync/
+    State           ~/.local/state/dosync/       →  /var/lib/dosync/
+    PKI             <state>/certs/  (mode 0700)
+
+The split follows the XDG categories, and the deciding question is the one that
+specification asks: *is this datum unique to this machine?* An audit chain and a
+private CA are — they are state. Policies and declarative device files are not;
+they are edited by hand and can be copied between machines, so they are
+configuration.
+
+Compatibility is not optional here
+----------------------------------
+A deployment exists with 42,000 entries and certificates in use. If the hub
+stopped looking where that deployment keeps its data, it would come up tomorrow
+with an empty chain and a fresh CA — and the history this project spent weeks
+protecting would be orphaned in a directory nobody looks at.
+
+So: an explicit variable always wins, an existing database in the working
+directory keeps being used with a warning explaining how to move it, and finding
+data in two places is an error rather than a choice. Choosing wrong there would
+mean writing to one chain while auditing another.
+"""
+import logging
+import os
+from pathlib import Path
+
+log = logging.getLogger("dosync.paths")
+
+#: Set by the packaging or the operator to force system mode. Without it, the
+#: mode is inferred: root implies a system service.
+MODE_ENV = "DOSYNC_INSTALL_MODE"
+
+
+def _running_as_root() -> bool:
+    try:
+        return os.geteuid() == 0
+    except AttributeError:      # pragma: no cover - non-POSIX
+        return False
+
+
+def install_mode() -> str:
+    """`"system"` or `"user"`.
+
+    Inferred from the effective user rather than declared, because the common
+    cases decide themselves: a systemd unit runs as root, `pipx` does not.
+    `DOSYNC_INSTALL_MODE` overrides for the cases that do not — a service
+    running under a dedicated unprivileged account, for instance.
+    """
+    declared = os.environ.get(MODE_ENV, "").strip().lower()
+    if declared in ("system", "user"):
+        return declared
+    return "system" if _running_as_root() else "user"
+
+
+def config_dirs() -> list[Path]:
+    """Where configuration is looked for, in order of preference."""
+    if install_mode() == "system":
+        return [Path("/etc/dosync")]
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    home = Path(xdg) if xdg else Path.home() / ".config"
+    return [home / "dosync", Path("/etc/dosync")]
+
+
+def state_dir() -> Path:
+    """Where this deployment's own data lives — chain, PKI, evidence."""
+    if install_mode() == "system":
+        return Path("/var/lib/dosync")
+    xdg = os.environ.get("XDG_STATE_HOME")
+    home = Path(xdg) if xdg else Path.home() / ".local" / "state"
+    return home / "dosync"
+
+
+def _legacy(name: str) -> Path:
+    """The pre-0.4.3 location: relative to the working directory."""
+    return Path.cwd() / name
+
+
+def resolve_state(name: str, env_var: str = None, create: bool = False) -> Path:
+    """Resolve a state path, honouring an existing deployment above all else.
+
+    Order:
+      1. `env_var`, if set — an operator who said where wins, always.
+      2. The legacy path, **if it already has data**. A running deployment does
+         not lose its chain to an upgrade.
+      3. The state directory.
+
+    Finding data in both the legacy path and the state directory raises, rather
+    than picking. Picking wrong means writing to one chain and auditing another,
+    and the operator is the only one who knows which is current.
+    """
+    if env_var:
+        explicit = os.environ.get(env_var)
+        if explicit:
+            return Path(explicit)
+
+    legacy, modern = _legacy(name), state_dir() / name
+    legacy_has = legacy.exists() and (legacy.is_file() or any(legacy.iterdir()))
+    modern_has = modern.exists() and (modern.is_file() or any(modern.iterdir()))
+
+    if legacy_has and modern_has:
+        raise RuntimeError(
+            f"'{name}' exists in two places and DoSync will not guess which is "
+            f"current:\n    {legacy}\n    {modern}\n"
+            f"Keep one, or set {env_var or 'the matching DOSYNC_* variable'} to "
+            f"say which. Choosing wrong here would mean writing to one and "
+            f"auditing the other.")
+
+    if legacy_has:
+        log.warning(
+            "Using %s from the working directory. Since 0.4.3 this belongs in "
+            "%s — data inside a source tree is one `git clean` from being gone. "
+            "Move it there, or set %s to keep it where it is.",
+            name, modern, env_var or "the matching variable")
+        return legacy
+
+    if create:
+        modern.parent.mkdir(parents=True, exist_ok=True)
+    return modern
+
+
+def resolve_config(name: str, env_var: str = None) -> Path | None:
+    """Find a configuration file, or None if there is none.
+
+    Returns None rather than a non-existent path: absent configuration is a
+    normal state for this protocol — a hub with no deployment policies is
+    conforming — and a caller should not have to distinguish "missing file" from
+    "file that happens not to exist yet".
+    """
+    if env_var:
+        explicit = os.environ.get(env_var)
+        if explicit:
+            return Path(explicit)
+
+    legacy = _legacy(name)
+    if legacy.exists():
+        return legacy
+    for d in config_dirs():
+        candidate = d / name
+        if candidate.exists():
+            return candidate
+    return None
+
+
+def resolve_config_dir(name: str, env_var: str = None) -> Path:
+    """A configuration DIRECTORY — declarative device files, for instance.
+
+    Unlike `resolve_config`, always returns a path: the caller iterates it and
+    an empty or absent directory is a legitimate answer meaning "no declarative
+    devices", not an error.
+    """
+    if env_var:
+        explicit = os.environ.get(env_var)
+        if explicit:
+            return Path(explicit)
+
+    legacy = _legacy(name)
+    if legacy.is_dir() and any(legacy.iterdir()):
+        return legacy
+    for d in config_dirs():
+        candidate = d / name
+        if candidate.is_dir():
+            return candidate
+    return config_dirs()[0] / name
+
+
+def certs_dir() -> Path:
+    """The PKI directory, created 0700 when this call creates it.
+
+    A private key in a directory with whatever permissions it inherited is the
+    kind of detail that is invisible until an audit asks about it.
+    """
+    explicit = os.environ.get("DOSYNC_CERTS_DIR")
+    if explicit:
+        return Path(explicit)
+
+    legacy = _legacy("certs")
+    if legacy.exists() and any(legacy.iterdir()):
+        return legacy
+
+    d = state_dir() / "certs"
+    if not d.exists():
+        d.mkdir(parents=True, exist_ok=True)
+        try:
+            d.chmod(0o700)
+        except OSError as e:        # pragma: no cover - exotic filesystems
+            log.warning("Could not restrict permissions on %s: %s", d, e)
+    return d
+
+
+def describe() -> dict:
+    """Every path this deployment resolved, for the startup log and /v1/status.
+
+    Reported because an operator editing `/etc/dosync/policies.json` while the
+    hub reads `~/.config/dosync/policies.json` believes they are protected by a
+    policy the hub never loaded. Silent divergence between what someone edits
+    and what runs is exactly the failure this project keeps finding.
+    """
+    return {
+        "mode": install_mode(),
+        "config_dirs": [str(d) for d in config_dirs()],
+        "state_dir": str(state_dir()),
+        "certs_dir": str(certs_dir()),
+    }

{dosync-0.4.2 → dosync-0.4.3}/dosync/policy_config.py

@@ -249,4 +249,6 @@ def configured_path() -> str | None:
     common state — not an error. The reference hub ships with NO deployment
     policies, because the protocol has no opinion about your house.
     """
-    return os.environ.get("DOSYNC_POLICIES") or None
+    from .paths import resolve_config
+    found = resolve_config("policies.json", "DOSYNC_POLICIES")
+    return str(found) if found else None

{dosync-0.4.2 → dosync-0.4.3}/dosync/security.py

@@ -61,7 +61,8 @@ log = logging.getLogger("dosync.security")
 
 # ── Configuración ─────────────────────────────────────────────────────────────
 
-CERTS_DIR       = Path(os.environ.get("DOSYNC_CERTS_DIR", "certs"))
+from .paths import certs_dir as _certs_dir
+CERTS_DIR       = _certs_dir()
 CA_KEY_PATH     = CERTS_DIR / "ca.key"
 CA_CERT_PATH    = CERTS_DIR / "ca.crt"
 HUB_KEY_PATH    = CERTS_DIR / "hub.key"

{dosync-0.4.2 → dosync-0.4.3}/dosync/server.py

@@ -65,7 +65,12 @@ def _resolve_db_path() -> str:
             "DOSYNC_DB_PATH is a deprecated alias for DOSYNC_DB — using %s. "
             "Rename the variable to DOSYNC_DB.", alias)
         return alias
-    return "dosync.db"
+    # No explicit setting: resolve through the deployment layout, which keeps an
+    # existing database in the working directory rather than starting a new one
+    # beside it. A hub that came up with an empty chain after an upgrade would
+    # lose exactly the history this protocol exists to protect.
+    from dosync.paths import resolve_state
+    return str(resolve_state("dosync.db", "DOSYNC_DB", create=True))
 
 
 # ── Estado global del hub ─────────────────────────────────────────────────────
@@ -732,6 +737,7 @@ async def lifespan(app: FastAPI):
     try:
         from dosync.adapters.declarative import DeclarativeAdapter
         from dosync.declarative import load_directory
+        from dosync.paths import resolve_config_dir
 
         _declared = load_directory()
         if _declared:
@@ -751,7 +757,7 @@ async def lifespan(app: FastAPI):
                 hub.register_device(_manifest)
             log.info("Declarative adapters: %d device(s) registered from %s",
                      len(_declared),
-                     os.environ.get("DOSYNC_DECLARATIVE_DIR", "declarative"))
+                     str(resolve_config_dir("declarative", "DOSYNC_DECLARATIVE_DIR")))
 
         # A device whose file is gone must not keep answering intents. It is
         # QUARANTINED rather than deleted: a directory that failed to mount looks

{dosync-0.4.2 → dosync-0.4.3}/dosync.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dosync
-Version: 0.4.2
+Version: 0.4.3
 Summary: The semantic layer between AI agents and physical devices
 Author-email: Rodrigo Giuliani <rgiuliani@dosync.dev>
 License-Expression: Apache-2.0

{dosync-0.4.2 → dosync-0.4.3}/dosync.egg-info/SOURCES.txt

@@ -28,6 +28,7 @@ dosync/models.py
 dosync/operation_guards.py
 dosync/operation_supervisor.py
 dosync/operations.py
+dosync/paths.py
 dosync/plugins.py
 dosync/policies.py
 dosync/policy_config.py
@@ -79,6 +80,7 @@ tests/test_db.py
 tests/test_declarative_adapters.py
 tests/test_declarative_quarantine.py
 tests/test_deployment_env_contract.py
+tests/test_deployment_layout.py
 tests/test_device_health.py
 tests/test_device_heartbeat.py
 tests/test_direct_action_governance.py

dosync-0.4.3/tests/test_deployment_layout.py

@@ -0,0 +1,209 @@
+"""Where a deployment keeps its configuration and its state (2026-08-08).
+
+Found while preparing to reflash the reference hub: its configuration lived in
+nine places, four of which the author did not remember existed, and three of
+those were inside a git clone. A `git clean -fdx` would have destroyed a
+42,000-entry audit chain and the CA's private key.
+
+Worth naming as the contradiction it was: this protocol argues that its evidence
+survives someone with root access, and it did not survive someone tidying a
+repository. The sophisticated threat was covered and the trivial one was not.
+
+The rules below are the panel's, and each exists because getting it wrong has a
+specific cost.
+"""
+import os
+from pathlib import Path
+
+import pytest
+
+from dosync import paths
+
+REPO = Path(__file__).resolve().parent.parent
+
+
+@pytest.fixture
+def clean_env(tmp_path, monkeypatch):
+    """A deployment rooted entirely under tmp_path, in user mode."""
+    monkeypatch.setenv("DOSYNC_INSTALL_MODE", "user")
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "cfg"))
+    monkeypatch.setenv("XDG_STATE_HOME", str(tmp_path / "state"))
+    for v in ("DOSYNC_DB", "DOSYNC_CERTS_DIR", "DOSYNC_POLICIES",
+              "DOSYNC_CHECKPOINT_DIR", "DOSYNC_ARCHIVE_DIR",
+              "DOSYNC_DECLARATIVE_DIR"):
+        monkeypatch.delenv(v, raising=False)
+    work = tmp_path / "work"
+    work.mkdir()
+    monkeypatch.chdir(work)
+    return tmp_path, work
+
+
+# ── The two modes ───────────────────────────────────────────────────────────
+
+def test_user_and_system_modes_resolve_differently(monkeypatch):
+    """`pipx` installs as an ordinary user who cannot write to /etc or
+    /var/lib; a systemd unit runs as root and should use them. Picking one
+    layout would have broken the other."""
+    monkeypatch.setenv("DOSYNC_INSTALL_MODE", "system")
+    assert paths.state_dir() == Path("/var/lib/dosync")
+    assert Path("/etc/dosync") in paths.config_dirs()
+
+    monkeypatch.setenv("DOSYNC_INSTALL_MODE", "user")
+    monkeypatch.setenv("XDG_STATE_HOME", "/tmp/xdg-state")
+    assert paths.state_dir() == Path("/tmp/xdg-state/dosync")
+
+
+def test_config_cascades_from_user_to_system(clean_env, monkeypatch):
+    """User location first, system second — so a per-user install finds its own
+    file, and falls back to a system-wide default when there is none."""
+    tmp, _ = clean_env
+    dirs = paths.config_dirs()
+    assert dirs[0] == tmp / "cfg" / "dosync"
+    assert dirs[-1] == Path("/etc/dosync")
+
+
+# ── Compatibility: the rule that protects the existing deployment ───────────
+
+def test_an_explicit_variable_always_wins(clean_env, monkeypatch):
+    """An operator who said where wins over any inference. Every existing
+    deployment is configured this way and must be unaffected."""
+    monkeypatch.setenv("DOSYNC_DB", "/tmp/chosen.db")
+    assert paths.resolve_state("dosync.db", "DOSYNC_DB") == Path("/tmp/chosen.db")
+
+
+def test_an_existing_database_in_the_working_directory_keeps_being_used(clean_env):
+    """The rule that matters most. A running deployment with 42,000 entries must
+    not come up with an empty chain because the layout changed — that would lose
+    exactly the history this protocol exists to protect."""
+    _, work = clean_env
+    (work / "dosync.db").write_text("existing deployment")
+
+    assert paths.resolve_state("dosync.db", "DOSYNC_DB") == work / "dosync.db"
+
+
+def test_the_legacy_path_is_used_with_a_warning_not_silently(clean_env, caplog):
+    """Using it quietly would leave the operator unaware their data sits inside
+    a source tree."""
+    import logging
+
+    _, work = clean_env
+    (work / "dosync.db").write_text("x")
+    with caplog.at_level(logging.WARNING):
+        paths.resolve_state("dosync.db", "DOSYNC_DB")
+    assert any("git clean" in str(r.msg) or "working directory" in str(r.msg)
+               for r in caplog.records)
+
+
+def test_data_in_two_places_is_an_error_not_a_choice(clean_env):
+    """Choosing wrong means writing to one chain and auditing the other, and
+    only the operator knows which is current."""
+    tmp, work = clean_env
+    (work / "dosync.db").write_text("old")
+    modern = paths.state_dir()
+    modern.mkdir(parents=True, exist_ok=True)
+    (modern / "dosync.db").write_text("new")
+
+    with pytest.raises(RuntimeError) as e:
+        paths.resolve_state("dosync.db", "DOSYNC_DB")
+    assert "will not guess" in str(e.value)
+    assert str(work) in str(e.value) and str(modern) in str(e.value), \
+        "the error must name both paths — the operator has to go look at them"
+
+
+def test_a_clean_install_uses_the_state_directory(clean_env):
+    tmp, _ = clean_env
+    p = paths.resolve_state("dosync.db", "DOSYNC_DB")
+    assert str(p).startswith(str(paths.state_dir()))
+
+
+# ── PKI ─────────────────────────────────────────────────────────────────────
+
+def test_the_pki_directory_is_created_private(clean_env):
+    """A private key in a directory with whatever permissions it inherited is
+    the kind of detail nobody notices until an audit asks."""
+    d = paths.certs_dir()
+    assert d.exists()
+    assert oct(d.stat().st_mode)[-3:] == "700", \
+        f"certs directory is {oct(d.stat().st_mode)[-3:]}, expected 700"
+
+
+def test_existing_certificates_are_not_abandoned(clean_env):
+    """Regenerating a CA orphans every device certificate issued from it, and
+    invalidates the certificate an operator installed on their laptop."""
+    _, work = clean_env
+    legacy = work / "certs"
+    legacy.mkdir()
+    (legacy / "ca.crt").write_text("existing CA")
+
+    assert paths.certs_dir() == legacy
+
+
+# ── Visibility ──────────────────────────────────────────────────────────────
+
+def test_the_hub_can_report_which_paths_it_resolved(clean_env):
+    """An operator editing /etc/dosync/policies.json while the hub reads
+    ~/.config/dosync/policies.json believes they are protected by a policy the
+    hub never loaded. Silent divergence between what is edited and what runs is
+    the failure this project keeps finding."""
+    d = paths.describe()
+    assert set(d) == {"mode", "config_dirs", "state_dir", "certs_dir"}
+    assert d["mode"] in ("user", "system")
+
+
+def test_configuration_is_found_in_the_config_directory(clean_env):
+    tmp, _ = clean_env
+    cfg = tmp / "cfg" / "dosync"
+    cfg.mkdir(parents=True)
+    (cfg / "policies.json").write_text("{}")
+
+    assert paths.resolve_config("policies.json", "DOSYNC_POLICIES") == \
+        cfg / "policies.json"
+
+
+def test_absent_configuration_is_none_not_a_missing_path(clean_env):
+    """A hub with no deployment policies is conforming — absence is a normal
+    state and callers should not have to tell it from a path that happens not to
+    exist."""
+    assert paths.resolve_config("policies.json", "DOSYNC_POLICIES") is None
+
+
+# ── Found by installing from PyPI on a clean machine (2026-08-08) ───────────
+
+def test_the_hub_says_when_it_is_only_reachable_locally():
+    """The commonest deployment is a headless Raspberry Pi whose operator is on
+    SSH and wants the dashboard from their laptop. Binding to loopback is the
+    right default — a hub reachable from the whole network because nobody chose
+    that is worse than one needing a flag — but `Uvicorn running on
+    http://127.0.0.1` does not tell them why their browser cannot connect.
+
+    The default does not change. The silence does.
+    """
+    import inspect
+
+    from dosync import cli
+
+    src = inspect.getsource(cli)
+    assert "loopback only" in src
+    assert "--host 0.0.0.0" in src, "and must say exactly how to change it"
+    assert 'default=os.environ.get("DOSYNC_HOST", "127.0.0.1")' in src, \
+        "the safe default must stay"
+
+
+def test_the_published_version_and_the_source_version_cannot_silently_diverge():
+    """`paths.py` was added under 0.4.2 while 0.4.2 was already on PyPI — two
+    different artefacts with one number. Anyone reporting a bug "in 0.4.2" would
+    leave us unable to tell which one they have.
+
+    This pins the specific mistake: the version must move when behaviour does.
+    """
+    import re
+
+    import dosync
+
+    changelog = (REPO / "CHANGELOG.md").read_text()
+    versions = re.findall(r"^## \[([0-9]+\.[0-9]+\.[0-9]+)\]", changelog, re.M)
+
+    assert dosync.__version__ in versions or dosync.__version__ > max(versions), (
+        f"version {dosync.__version__} is neither released nor ahead of the "
+        f"latest changelog entry {max(versions)} — a behaviour change under an "
+        f"already-published number produces two artefacts with one name")