Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

feat(artifacts): register everything Switch publishes, not just what it versions (CHOO-1865)

Louis Amaudruzae8ca6bd65bb
diff --git a/RELEASING.md b/RELEASING.md
index 936b8b53a..55b0fad64 100644
--- a/RELEASING.md
+++ b/RELEASING.md
@@ -22,19 +22,35 @@ Never derive one from the other.
### What is, and is not, separately versioned
-The **operator dashboard** (`gateway/`), the **Helm chart**, and the **standalone
-compose artifact** have no version of their own. They ship inside the switch-core
-release and are stamped with its version at package time, which is what lets a
-single tag pin the whole stack. They are documented as part of switch-core in
-`CHANGELOG.md` rather than given sections of their own.
-
-Do not give any of them a version without also giving it a release of its own —
-a version nobody publishes independently is a number that drifts from reality,
-which is exactly what `Chart.yaml` did while it claimed `0.2.1`.
+The **operator dashboard** (`gateway/`), the **setup image**, the **Helm chart**,
+and the **standalone compose artifact** have no version of their own. They ship
+inside the switch-core release and are stamped with its version at package time,
+which is what lets a single tag pin the whole stack. They appear in
+`artifacts.yaml` with `version_from: switch-core` — listed, because a registry
+claiming to be the single source of truth cannot be silent about things we
+publish, and `version_from` states "no version of its own" as data rather than
+leaving it to be inferred from an absence.
+
+Do not give any of them a version of their own without also giving it a release
+of its own — a version nobody publishes independently is a number that drifts
+from reality, which is exactly what `Chart.yaml` did while it claimed `0.2.1`.
The separately-versioned artifacts are switch-core, switchdash, the
agent-runtime package, the sidecar, and the two connector plugins.
+### A known gap: the Helm chart has no contract
+
+`values.yaml` is a real consumer-facing interface — operators write a values
+file against its keys and pin the chart version — so a breaking change there is
+as disruptive as renaming a compose service. It carries no contract anyway,
+because a contract needs two sides that declare and nothing first-party consumes
+the chart; the other side is a human-maintained values file.
+
+A one-sided contract is a revision nobody compares, so this is left as a
+documented gap rather than covered by a number that would only look like
+coverage. Until it is closed, **treat a values-schema change as a breaking
+change and say so in the changelog** — nothing will catch it for you.
+
### Bumping a contract
When you change an interface named in `artifacts.yaml`, raise that artifact's
diff --git a/artifacts.yaml b/artifacts.yaml
index b49b79c5c..0bf2389d6 100644
--- a/artifacts.yaml
+++ b/artifacts.yaml
@@ -29,6 +29,21 @@
# An artifact with no `declared_in` has no such home — nothing but this file
# declares it, so this file is its source and the constant is generated.
#
+# ── About `version_from` ─────────────────────────────────────────────────────
+#
+# Some things Switch publishes have no version of their own: they ship inside
+# another artifact's release and are stamped with its version at package time,
+# which is what lets a single tag pin the whole stack. `version_from` names the
+# artifact they inherit from.
+#
+# They are listed here rather than left out, because a registry that claims to
+# be the single source of truth cannot be silent about things we publish. And
+# `version_from` states the fact — "this has no version of its own" — as data
+# rather than leaving it to be inferred from an absence. Nothing duplicates a
+# number, so nothing can drift.
+#
+# Exactly one of `version` or `version_from` per artifact.
+#
# ── Contract revisions ───────────────────────────────────────────────────────
#
# speaks — the newest revision the artifact implements
@@ -47,6 +62,7 @@ artifacts:
description: The backend service, and the gateway API it serves.
version: 0.12.3
declared_in: core/pyproject.toml
+ published_as: switch-core
switchdash:
description: The desktop app.
@@ -76,6 +92,39 @@ artifacts:
only source and the constant is generated from it.
version: 1.8.0
+ # ── Published under the switch-core release ────────────────────────────────
+ # No version of their own: `helm package` and the image build stamp them with
+ # the switch-core release version, so one tag pins the whole stack.
+
+ gateway:
+ description: The operator dashboard image.
+ version_from: switch-core
+ published_as: gateway
+
+ setup:
+ description: The collaboration-bridge seeder image.
+ version_from: switch-core
+ published_as: setup
+
+ helm-chart:
+ description: >-
+ The Kubernetes chart. Its values.yaml is a consumer-facing interface —
+ operators write a values file against those keys and pin the chart
+ version — but nothing first-party consumes it, so there is no second side
+ to declare a contract against. A breaking values change is therefore
+ invisible to this model today; that gap is deliberate and belongs with
+ the rest of Part 2, not papered over with a revision nobody compares.
+ version_from: switch-core
+ published_as: charts/switch
+
+ compose:
+ description: >-
+ The standalone compose file, published as an OCI artifact. Unlike the
+ chart this one has a real peer — switchdash's local-server mode drives it
+ — so it does carry a contract, below.
+ version_from: switch-core
+ published_as: standalone-compose
+
switch-connector:
description: The Claude Code connector plugin.
version: 0.7.8
diff --git a/core/switch_core/artifacts.py b/core/switch_core/artifacts.py
index 07d5446ef..16ddad7a1 100644
--- a/core/switch_core/artifacts.py
+++ b/core/switch_core/artifacts.py
@@ -24,6 +24,10 @@ ARTIFACT_VERSIONS: Final[dict[str, str]] = {
"switchdash": "0.19.2",
"agent-runtime": "0.1.5",
"sidecar": "1.8.0",
+ "gateway": "0.12.3",
+ "setup": "0.12.3",
+ "helm-chart": "0.12.3",
+ "compose": "0.12.3",
"switch-connector": "0.7.8",
"switch-connector-codex": "0.2.0",
}
diff --git a/core/tests/test_gen_artifacts.py b/core/tests/test_gen_artifacts.py
index 98cfd4a5c..ee6aad754 100644
--- a/core/tests/test_gen_artifacts.py
+++ b/core/tests/test_gen_artifacts.py
@@ -107,6 +107,23 @@ def test_the_switchdash_pin_is_not_wired_to_switch_cores_version() -> None:
assert "switch-core" in switchdash.pins
+def test_every_contract_peer_is_an_artifact_the_registry_knows() -> None:
+ """The two halves must agree about what an artifact is.
+
+ `compose` was a peer on stack-compose while the artifacts section had never
+ heard of it, so the same name resolved in one half and threw in the other.
+ """
+ named_in_contracts = {peer for peers in CONTRACTS.values() for peer in peers}
+ assert named_in_contracts <= set(ARTIFACT_VERSIONS)
+
+
+def test_everything_published_under_the_switch_core_tag_shares_its_version() -> None:
+ """One tag pins the whole stack, so these are stamped rather than declared."""
+ core = ARTIFACT_VERSIONS["switch-core"]
+ for stamped in ("gateway", "setup", "helm-chart", "compose"):
+ assert ARTIFACT_VERSIONS[stamped] == core
+
+
def test_the_sidecar_has_no_declared_in_so_the_registry_owns_it() -> None:
"""Nothing else declares the sidecar's version — it is deployed, not published."""
registry = gen.load_registry()
@@ -171,6 +188,94 @@ def test_registry_rejects_a_two_part_version(
gen.load_registry()
+def test_registry_rejects_both_version_and_version_from(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """An artifact either has its own version or inherits one. Never both."""
+ _write_registry(
+ tmp_path,
+ monkeypatch,
+ artifacts={
+ "base": {"description": "d", "version": "1.0.0"},
+ "demo": {"description": "d", "version": "2.0.0", "version_from": "base"},
+ },
+ contracts={
+ "demo-contract": {
+ "description": "d",
+ "artifacts": {"demo": {"speaks": 1, "accepts": 1}},
+ }
+ },
+ )
+ with pytest.raises(ValueError, match="exactly one of"):
+ gen.load_registry()
+
+
+def test_registry_rejects_neither_version_nor_version_from(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ _write_registry(tmp_path, monkeypatch, artifacts={"demo": {"description": "d"}})
+ with pytest.raises(ValueError, match="exactly one of"):
+ gen.load_registry()
+
+
+def test_an_inherited_version_resolves_to_its_source(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ _write_registry(
+ tmp_path,
+ monkeypatch,
+ artifacts={
+ "base": {"description": "d", "version": "3.4.5"},
+ "derived": {"description": "d", "version_from": "base"},
+ },
+ contracts={
+ "demo-contract": {
+ "description": "d",
+ "artifacts": {"derived": {"speaks": 1, "accepts": 1}},
+ }
+ },
+ )
+ registry = gen.load_registry()
+ derived = next(a for a in registry.artifacts if a.name == "derived")
+ assert derived.version == "3.4.5"
+
+
+def test_registry_rejects_inheriting_from_something_unknown(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ _write_registry(
+ tmp_path,
+ monkeypatch,
+ artifacts={"demo": {"description": "d", "version_from": "nowhere"}},
+ contracts={
+ "demo-contract": {
+ "description": "d",
+ "artifacts": {"demo": {"speaks": 1, "accepts": 1}},
+ }
+ },
+ )
+ with pytest.raises(ValueError, match="not an artifact in this registry"):
+ gen.load_registry()
+
+
+def test_registry_rejects_a_contract_peer_it_does_not_know(
+ tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+ """The check that would have caught `compose` being in one half only."""
+ _write_registry(
+ tmp_path,
+ monkeypatch,
+ contracts={
+ "demo-contract": {
+ "description": "d",
+ "artifacts": {"a-stranger": {"speaks": 1, "accepts": 1}},
+ }
+ },
+ )
+ with pytest.raises(ValueError, match="not in the artifacts section"):
+ gen.load_registry()
+
+
def test_registry_rejects_a_pin_of_something_it_does_not_know(
tmp_path: Path, monkeypatch: pytest.MonkeyPatch
) -> None:
diff --git a/dash/packages/shared/src/artifacts.ts b/dash/packages/shared/src/artifacts.ts
index db6108372..9d8d683f8 100644
--- a/dash/packages/shared/src/artifacts.ts
+++ b/dash/packages/shared/src/artifacts.ts
@@ -24,6 +24,10 @@ export const ARTIFACT_VERSIONS = {
switchdash: '0.19.2',
'agent-runtime': '0.1.5',
sidecar: '1.8.0',
+ gateway: '0.12.3',
+ setup: '0.12.3',
+ 'helm-chart': '0.12.3',
+ compose: '0.12.3',
'switch-connector': '0.7.8',
'switch-connector-codex': '0.2.0',
} as const satisfies Record<string, string>;
diff --git a/dash/packages/switch-agent-runtime/src/artifacts.ts b/dash/packages/switch-agent-runtime/src/artifacts.ts
index db6108372..9d8d683f8 100644
--- a/dash/packages/switch-agent-runtime/src/artifacts.ts
+++ b/dash/packages/switch-agent-runtime/src/artifacts.ts
@@ -24,6 +24,10 @@ export const ARTIFACT_VERSIONS = {
switchdash: '0.19.2',
'agent-runtime': '0.1.5',
sidecar: '1.8.0',
+ gateway: '0.12.3',
+ setup: '0.12.3',
+ 'helm-chart': '0.12.3',
+ compose: '0.12.3',
'switch-connector': '0.7.8',
'switch-connector-codex': '0.2.0',
} as const satisfies Record<string, string>;
diff --git a/scripts/gen_artifacts.py b/scripts/gen_artifacts.py
index 3a6065d40..2f4486ad4 100644
--- a/scripts/gen_artifacts.py
+++ b/scripts/gen_artifacts.py
@@ -37,7 +37,7 @@ import json
import re
import sys
import tomllib
-from dataclasses import dataclass
+from dataclasses import dataclass, replace
from pathlib import Path
from typing import Any
@@ -65,8 +65,14 @@ class Target:
class Artifact:
name: str
description: str
+ #: Resolved: an artifact with `version_from` carries its source's version.
version: str
+ #: Where a packaging ecosystem states this version, when one owns it.
declared_in: str | None
+ #: The artifact this one inherits its version from, if it has none of its own.
+ version_from: str | None
+ #: Where it lands on the registry, for anything we publish.
+ published_as: str | None
pins: dict[str, str]
@@ -101,6 +107,7 @@ def load_registry() -> Registry:
raise ValueError(f"{SOURCE} must have a top-level {section!r} mapping")
artifacts = [_parse_artifact(name, body) for name, body in raw["artifacts"].items()]
+ artifacts = _resolve_inherited_versions(artifacts)
known = {artifact.name for artifact in artifacts}
for artifact in artifacts:
for pinned in artifact.pins:
@@ -111,9 +118,52 @@ def load_registry() -> Registry:
)
contracts = [_parse_contract(name, body) for name, body in raw["contracts"].items()]
+
+ # Every artifact a contract names must exist in the artifacts section.
+ # Without this the two halves can disagree about what an artifact even is:
+ # `compose` was a peer on stack-compose while the artifacts section had
+ # never heard of it, so one name resolved in one half and threw in the
+ # other (CHOO-1865).
+ for contract in contracts:
+ for participant in contract.artifacts:
+ if participant not in known:
+ raise ValueError(
+ f"contract {contract.name!r} names artifact {participant!r}, "
+ "which is not in the artifacts section — every peer must be "
+ "an artifact this registry knows"
+ )
+
return Registry(artifacts=artifacts, contracts=contracts)
+def _resolve_inherited_versions(artifacts: list[Artifact]) -> list[Artifact]:
+ """Give every `version_from` artifact the version it inherits.
+
+ One hop only. A chain would mean an artifact inheriting from something that
+ itself has no version of its own, which is a modelling mistake rather than
+ a case worth supporting.
+ """
+ by_name = {artifact.name: artifact for artifact in artifacts}
+ resolved: list[Artifact] = []
+ for artifact in artifacts:
+ if artifact.version_from is None:
+ resolved.append(artifact)
+ continue
+ source = by_name.get(artifact.version_from)
+ if source is None:
+ raise ValueError(
+ f"artifact {artifact.name!r} takes its version from "
+ f"{artifact.version_from!r}, which is not an artifact in this registry"
+ )
+ if source.version_from is not None:
+ raise ValueError(
+ f"artifact {artifact.name!r} takes its version from "
+ f"{artifact.version_from!r}, which has no version of its own"
+ )
+ resolved.append(replace(artifact, version=source.version))
+ return resolved
+
+
def _parse_artifact(name: str, body: object) -> Artifact:
if not isinstance(body, dict):
raise ValueError(f"artifact {name!r}: expected a mapping")
@@ -122,7 +172,23 @@ def _parse_artifact(name: str, body: object) -> Artifact:
raise ValueError(f"artifact {name!r}: a description is required")
version = body.get("version")
- if not isinstance(version, str) or not SEMVER.fullmatch(version):
+ version_from = body.get("version_from")
+ if (version is None) == (version_from is None):
+ raise ValueError(
+ f"artifact {name!r}: set exactly one of 'version' (it has its own) "
+ "or 'version_from' (it is stamped from another artifact's release)"
+ )
+ if version_from is not None:
+ if not isinstance(version_from, str):
+ raise ValueError(f"artifact {name!r}: version_from must be a name")
+ if body.get("declared_in") is not None:
+ raise ValueError(
+ f"artifact {name!r}: declared_in makes no sense with version_from — "
+ "nothing declares a version it does not have"
+ )
+ # Filled in once the source is known.
+ version = "0.0.0"
+ elif not isinstance(version, str) or not SEMVER.fullmatch(version):
raise ValueError(
f"artifact {name!r}: version must be three-part semver, got {version!r}"
)
@@ -131,6 +197,10 @@ def _parse_artifact(name: str, body: object) -> Artifact:
if declared_in is not None and not isinstance(declared_in, str):
raise ValueError(f"artifact {name!r}: declared_in must be a path")
+ published_as = body.get("published_as")
+ if published_as is not None and not isinstance(published_as, str):
+ raise ValueError(f"artifact {name!r}: published_as must be a string")
+
pins_raw = body.get("pins") or {}
if not isinstance(pins_raw, dict):
raise ValueError(f"artifact {name!r}: pins must be a mapping")
@@ -148,6 +218,8 @@ def _parse_artifact(name: str, body: object) -> Artifact:
description=_squash(description),
version=version,
declared_in=declared_in,
+ version_from=version_from,
+ published_as=published_as,
pins=pins,
)