feat(api): kind-scoped deployment resolution

Resolve deployments by (name, kind) via the core per-kind stores / registry.get:
- get_service resolves a service-or-static; get_job a job; get_component returns
  the first kind for a name (the /services|/jobs|/tools/{name} endpoints are the
  unambiguous addresses). _save_deployment stores into the kind store, preferring
  the existing same-named deployment on a partial patch (can't derive kind from a
  partial payload). delete/set-enabled act across a name's kinds.
- All iterate-all loops use registry.all(); lookups use registry.get/named.
- services.py/logs.py resolve the managed deployment and use kind-aware unit names.
- mqtt registry (de)serialization keyed by composite "<kind>/<name>".
API + core suites green (85 + 182).

castle-api/src/castle_api/config_editor.py

@@ -10,6 +10,7 @@ from fastapi import APIRouter, HTTPException, status
 from pydantic import BaseModel
 
 from castle_core.config import (
+    KINDS,
     CastleConfig,
     _DEPLOYMENT_ADAPTER,
     _normalize_deployment_dict,
@@ -81,10 +82,9 @@ def _aggregate_yaml(config: CastleConfig) -> str:
         data["programs"] = {
             n: _program_to_yaml_dict(s, config) for n, s in config.programs.items()
         }
-    if config.deployments:
+    deps = {n: _spec_to_yaml_dict(s) for _k, n, s in config.all_deployments()}
-        data["deployments"] = {
+    if deps:
-            n: _spec_to_yaml_dict(s) for n, s in config.deployments.items()
+        data["deployments"] = deps
-        }
     return yaml.dump(data, default_flow_style=False, sort_keys=False)
 
 
@@ -242,12 +242,12 @@ async def delete_program(name: str, cascade: bool = False) -> dict:
             status_code=status.HTTP_404_NOT_FOUND,
             detail=f"Program '{name}' not found",
         )
-    refs = [d for d, spec in config.deployments.items() if spec.program == name]
+    refs = [(k, d) for k, d, spec in config.all_deployments() if spec.program == name]
     if refs and not cascade:
         raise HTTPException(
             status_code=status.HTTP_409_CONFLICT,
             detail=(
-                f"'{name}' still has deployments ({', '.join(refs)}). "
+                f"'{name}' still has deployments ({', '.join(d for _k, d in refs)}). "
                 "Delete them first, or pass cascade=true to remove them too."
             ),
         )
@@ -256,14 +256,14 @@ async def delete_program(name: str, cascade: bool = False) -> dict:
     if refs:
         from castle_core.lifecycle import deactivate
 
-        for ref in refs:
+        for kind, ref in refs:
             # Best-effort teardown (uninstall/stop/disable); still remove the config
             # even if the runtime is already gone.
             try:
-                await deactivate(ref, config, config.root)
+                await deactivate(ref, kind, config, config.root)
             except Exception:
                 pass
-            del config.deployments[ref]
+            del config.store_for(kind)[ref]
             removed.append(ref)
 
     del config.programs[name]
@@ -295,8 +295,25 @@ def _save_deployment(name: str, config_dict: dict) -> dict:
     config = get_config()
     incoming = dict(config_dict)
 
-    if name in config.deployments:
+    # Resolve the (name, kind) this save targets. A partial patch (e.g. just
-        base = config.deployments[name].model_dump(mode="json", exclude_none=True)
+    # {reach: off}) has no manager, so we can't derive kind from it — prefer the
+    # existing same-named deployment when there's exactly one; otherwise derive the
+    # kind from the incoming spec (a create, or disambiguating a shared name).
+    named = config.deployments_named(name)
+    existing = None
+    if len(named) == 1:
+        existing = named[0][1]
+    else:
+        try:
+            probe = _DEPLOYMENT_ADAPTER.validate_python(
+                _normalize_deployment_dict({**incoming, "id": name})
+            )
+            existing = config.deployment(kind_for(probe), name)
+        except Exception:
+            existing = None
+
+    if existing is not None:
+        base = existing.model_dump(mode="json", exclude_none=True)
         merged = {**base, **incoming, "id": name}
         # An explicit null means "clear" — drop the key so its default applies.
         merged = {k: v for k, v in merged.items() if v is not None}
@@ -315,19 +332,23 @@ def _save_deployment(name: str, config_dict: dict) -> dict:
             status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
             detail=f"Invalid deployment config: {e}",
         )
-    config.deployments[name] = dep
+    config.store_for(kind_for(dep))[name] = dep
     save_config(config)
     return {"ok": True, "deployment": name}
 
 
 def _delete_deployment(name: str) -> dict:
     config = get_config()
-    if name not in config.deployments:
+    removed = False
+    for kind in KINDS:
+        if name in config.store_for(kind):
+            del config.store_for(kind)[name]
+            removed = True
+    if not removed:
         raise HTTPException(
             status_code=status.HTTP_404_NOT_FOUND,
             detail=f"Deployment '{name}' not found",
         )
-    del config.deployments[name]
     save_config(config)
     return {"ok": True, "deployment": name, "action": "deleted"}
 
@@ -357,13 +378,15 @@ def set_deployment_enabled(name: str, request: EnabledRequest) -> dict:
     declarative flow: change what you want, then apply.
     """
     config = get_config()
-    dep = config.deployments.get(name)
+    deps = config.deployments_named(name)
-    if dep is None:
+    if not deps:
         raise HTTPException(
             status_code=status.HTTP_404_NOT_FOUND,
             detail=f"Deployment '{name}' not found",
         )
-    dep.enabled = request.enabled
+    # A name may span kinds — toggle all of them together.
+    for _kind, dep in deps:
+        dep.enabled = request.enabled
     save_config(config)
     return {"ok": True, "deployment": name, "enabled": request.enabled}
 

castle-api/src/castle_api/health.py

@@ -21,7 +21,7 @@ async def check_all_health(registry: NodeRegistry) -> list[HealthStatus]:
     http_targets: list[tuple[str, str]] = []
     systemd_targets: list[str] = []
 
-    for name, deployed in registry.deployed.items():
+    for _kind, name, deployed in registry.all():
         if deployed.port and deployed.health_path:
             url = f"http://127.0.0.1:{deployed.port}{deployed.health_path}"
             http_targets.append((name, url))

castle-api/src/castle_api/logs.py

@@ -8,6 +8,8 @@ from collections.abc import AsyncGenerator
 from fastapi import APIRouter, HTTPException, Query, status
 from starlette.responses import StreamingResponse
 
+from castle_core.generators.systemd import unit_name
+
 from castle_api.config import get_castle_root
 
 router = APIRouter(prefix="/logs", tags=["logs"])
@@ -27,20 +29,24 @@ async def get_logs(
         from castle_core.config import load_config
 
         config = load_config(root)
-        dep = config.deployments.get(name)
+        # A name may span kinds — the managed (systemd) one owns the journal.
-        is_managed = dep is not None and getattr(dep, "manage", None) is not None
+        dep_kind = next(
-        if not is_managed:
+            ((k, s) for k, s in config.deployments_named(name) if getattr(s, "manage", None)),
+            None,
+        )
+        if dep_kind is None:
             raise HTTPException(
                 status_code=status.HTTP_404_NOT_FOUND,
                 detail=f"'{name}' is not a managed service",
             )
+        kind, _spec = dep_kind
     else:
         raise HTTPException(
             status_code=status.HTTP_404_NOT_FOUND,
             detail="Castle root not available",
         )
 
-    unit = f"{UNIT_PREFIX}{name}.service"
+    unit = unit_name(name, kind)
 
     if follow:
         return StreamingResponse(

castle-api/src/castle_api/mqtt_client.py

@@ -41,7 +41,7 @@ def _registry_to_json(registry: NodeRegistry) -> str:
         "deployed": {},
     }
 
-    for name, comp in registry.deployed.items():
+    for _kind, name, comp in registry.all():
         entry: dict = {
             "manager": comp.manager,
             "launcher": comp.launcher,
@@ -61,7 +61,7 @@ def _registry_to_json(registry: NodeRegistry) -> str:
             entry["schedule"] = comp.schedule
         if comp.managed:
             entry["managed"] = comp.managed
-        data["deployed"][name] = entry
+        data["deployed"][NodeRegistry.key(comp.kind, name)] = entry
 
     return json.dumps(data)
 
@@ -76,14 +76,17 @@ def _json_to_registry(payload: str) -> NodeRegistry:
         gateway_port=node_data.get("gateway_port", 9000),
     )
     deployed: dict[str, Deployment] = {}
-    for name, comp_data in data.get("deployed", {}).items():
+    for key, comp_data in data.get("deployed", {}).items():
-        deployed[name] = Deployment(
+        key_kind, name = key.split("/", 1) if "/" in key else (None, key)
+        kind = comp_data.get("kind") or key_kind or "service"
+        deployed[NodeRegistry.key(kind, name)] = Deployment(
             manager=comp_data.get("manager", "systemd"),
             launcher=comp_data.get("launcher"),
             run_cmd=comp_data.get("run_cmd", []),
             env=comp_data.get("env", {}),
             description=comp_data.get("description"),
-            kind=comp_data.get("kind", "service"),
+            name=name,
+            kind=kind,
             stack=comp_data.get("stack"),
             port=comp_data.get("port"),
             health_path=comp_data.get("health_path"),

castle-api/src/castle_api/nodes.py

@@ -42,7 +42,7 @@ def _remote_node_summary(hostname: str, remote: object) -> NodeSummary:
 def _deployed_to_summaries(registry: object, hostname: str) -> list[DeploymentSummary]:
     """Convert deployed components from a registry into DeploymentSummary list."""
     summaries = []
-    for name, d in registry.deployed.items():
+    for _kind, name, d in registry.all():
         summaries.append(
             DeploymentSummary(
                 id=name,

castle-api/src/castle_api/routes.py

@@ -385,7 +385,10 @@ def _program_from_spec(
     if config is not None:
         from castle_core.lifecycle import is_active
 
-        active = is_active(name, config)
+        # A program's active state = its same-named deployment's (or the bare
+        # program on PATH when it has none).
+        _named = config.deployments_named(name)
+        active = is_active(name, _named[0][0] if _named else "service", config)
         # A program → 0-N deployments, each with its own kind.
         deployments = [
             DeploymentRef(name=dname, kind=kind)
@@ -424,7 +427,7 @@ def list_services(include_remote: bool = False) -> list[ServiceSummary]:
 
     # Services page shows services (systemd) AND statics (caddy) — both are
     # exposed, URL-reachable "services". Not jobs, tools, or remotes.
-    for name, deployed in registry.deployed.items():
+    for _kind, name, deployed in registry.all():
         if deployed.kind not in ("service", "static"):
             continue
         s = _service_from_deployed(name, deployed)
@@ -461,7 +464,7 @@ def list_services(include_remote: bool = False) -> list[ServiceSummary]:
     # Remote
     if include_remote:
         for remote_host, remote in mesh_state.all_nodes().items():
-            for name, d in remote.registry.deployed.items():
+            for _kind, name, d in remote.registry.all():
                 if not d.schedule and name not in seen:
                     s = _service_from_deployed(name, d)
                     s.node = remote_host
@@ -501,19 +504,17 @@ def get_service(name: str) -> ServiceDetail:
         return ServiceDetail(**summary.model_dump(), manifest=manifest)
 
     registry = get_registry()
-    if name in registry.deployed and not registry.deployed[name].schedule:
+    # /services/{name} covers a service OR a static (both are "services" in the UI),
-        deployed = registry.deployed[name]
+    # never a job — resolve the non-job deployment of this name.
+    deployed = registry.get("service", name) or registry.get("static", name)
+    if deployed is not None:
         summary = _service_from_deployed(name, deployed)
         if config is not None and summary.source is None:
             summary.source = _backfill_source(name, config)
-        # Serve the editable spec whenever the deployment is in castle.yaml — a
+        # Serve the editable spec (reach/root/program) when it's in castle.yaml.
-        # STATIC (caddy) is in config.deployments but NOT config.services, so it
+        spec = config.deployment(deployed.kind, name) if config is not None else None
-        # lands here; without this its manifest lacks reach/root/program and the
+        if spec is not None:
-        # edit form defaults them wrong (calculator showed reach as internal).
+            manifest = spec.model_dump(mode="json", exclude_none=True)
-        if config is not None and name in config.deployments:
-            manifest = config.deployments[name].model_dump(
-                mode="json", exclude_none=True
-            )
         else:
             manifest = {
                 "manager": deployed.manager,
@@ -545,7 +546,7 @@ def list_jobs(include_remote: bool = False) -> list[JobSummary]:
     seen: set[str] = set()
 
     # Deployed jobs (scheduled)
-    for name, deployed in registry.deployed.items():
+    for _kind, name, deployed in registry.all():
         if not deployed.schedule:
             continue
         s = _job_from_deployed(name, deployed)
@@ -581,7 +582,7 @@ def list_jobs(include_remote: bool = False) -> list[JobSummary]:
     # Remote
     if include_remote:
         for remote_host, remote in mesh_state.all_nodes().items():
-            for name, d in remote.registry.deployed.items():
+            for _kind, name, d in remote.registry.all():
                 if d.schedule and name not in seen:
                     s = _job_from_deployed(name, d)
                     s.node = remote_host
@@ -612,8 +613,8 @@ def get_job(name: str) -> JobDetail:
         return JobDetail(**summary.model_dump(), manifest=manifest)
 
     registry = get_registry()
-    if name in registry.deployed and registry.deployed[name].schedule:
+    deployed = registry.get("job", name)
-        deployed = registry.deployed[name]
+    if deployed is not None:
         summary = _job_from_deployed(name, deployed)
         if config is not None and summary.source is None:
             summary.source = _backfill_source(name, config)
@@ -704,7 +705,7 @@ def list_components(include_remote: bool = False) -> list[DeploymentSummary]:
     seen: set[str] = set()
 
     # Deployed components from registry
-    for name, deployed in registry.deployed.items():
+    for _kind, name, deployed in registry.all():
         s = _summary_from_deployed(name, deployed)
         s.node = local_hostname
         summaries.append(s)
@@ -759,7 +760,7 @@ def list_components(include_remote: bool = False) -> list[DeploymentSummary]:
     # Remote components from mesh (local wins on name conflicts)
     if include_remote:
         for hostname, remote in mesh_state.all_nodes().items():
-            for name, d in remote.registry.deployed.items():
+            for _kind, name, d in remote.registry.all():
                 if name not in seen:
                     summaries.append(
                         DeploymentSummary(
@@ -788,8 +789,11 @@ def get_component(name: str) -> DeploymentDetail:
     """Get detailed info for a single component."""
     registry = get_registry()
 
-    if name in registry.deployed:
+    # A name may span kinds; the unified endpoint returns the first (kind-scoped
-        deployed = registry.deployed[name]
+    # /services|/jobs|/tools/{name} are the unambiguous addresses).
+    named = registry.named(name)
+    if named:
+        deployed = named[0]
         summary = _summary_from_deployed(name, deployed)
 
         root = get_castle_root()
@@ -819,8 +823,9 @@ def get_component(name: str) -> DeploymentDetail:
         # defaults), not the runtime view — serve the castle.yaml spec whenever the
         # deployment is defined there. Fall back to the runtime dict only for a
         # deployed-but-not-in-config item (e.g. a discovered remote reference).
-        if config and name in config.deployments:
+        spec = config.deployment(deployed.kind, name) if config else None
-            raw = config.deployments[name].model_dump(mode="json", exclude_none=True)
+        if spec is not None:
+            raw = spec.model_dump(mode="json", exclude_none=True)
         else:
             raw = {
                 "manager": deployed.manager,
@@ -906,7 +911,7 @@ def get_gateway() -> GatewayInfo:
     # is not a service, so filtering to services dropped its public_url (calculator).
     public_domain = registry.node.public_domain
     public_names = {
-        name for name, dep in (config.deployments.items() if config else [])
+        name for _k, name, dep in (config.all_deployments() if config else [])
         if getattr(dep, "public", False)
     }
 

castle-api/src/castle_api/services.py

@@ -11,6 +11,7 @@ from starlette.responses import JSONResponse
 from castle_core.generators.systemd import (
     generate_timer,
     generate_unit_from_deployed,
+    unit_name,
 )
 
 from castle_api.config import get_castle_root, get_registry
@@ -53,10 +54,15 @@ async def _get_unit_status(unit: str) -> str:
     return (stdout or b"").decode().strip()
 
 
+def _managed(name: str):
+    """The managed deployment with this name (a name may span kinds; take the
+    managed systemd one — service or job), or None."""
+    return next((d for d in get_registry().named(name) if d.managed), None)
+
+
 def _validate_managed(name: str) -> None:
     """Raise 404 if the component isn't managed in the registry."""
-    registry = get_registry()
+    if _managed(name) is None:
-    if name not in registry.deployed or not registry.deployed[name].managed:
         raise HTTPException(
             status_code=status.HTTP_404_NOT_FOUND,
             detail=f"'{name}' is not a managed service",
@@ -100,8 +106,8 @@ async def _deferred_systemctl(action: str, unit: str, delay: float = 0.5) -> Non
 
 async def _do_action(name: str, action: str) -> JSONResponse:
     """Execute a systemctl action and broadcast updated health."""
-    _validate_managed(name)
+    deployed = _managed(name)
-    unit = f"{UNIT_PREFIX}{name}.service"
+    unit = unit_name(name, deployed.kind) if deployed else f"{UNIT_PREFIX}{name}.service"
 
     # Self-restart: defer the systemctl call so the response can be sent first
     if name == SELF_NAME and action in ("restart", "stop"):
@@ -128,8 +134,7 @@ async def _do_action(name: str, action: str) -> JSONResponse:
 def get_unit(name: str) -> dict[str, str | None]:
     """Return the generated systemd unit file(s) for a managed component."""
     _validate_managed(name)
-    registry = get_registry()
+    deployed = _managed(name)
-    deployed = registry.deployed[name]
 
     # Get systemd spec from config if repo available
     systemd_spec = None
@@ -140,7 +145,7 @@ def get_unit(name: str) -> dict[str, str | None]:
         from castle_core.config import load_config
 
         config = load_config(root)
-        dep = config.deployments.get(name)
+        dep = config.deployment(deployed.kind, name)
         if dep is not None:
             manage = getattr(dep, "manage", None)
             if manage and manage.systemd:

castle-api/tests/test_mqtt.py

@@ -17,6 +17,7 @@ def _make_registry() -> NodeRegistry:
                 run_cmd=["uv", "run", "my-svc"],
                 env={"PORT": "9001", "SECRET_KEY": "super-secret"},
                 description="My service",
+                name="my-svc",
                 kind="service",
                 stack="python-fastapi",
                 port=9001,
@@ -28,6 +29,7 @@ def _make_registry() -> NodeRegistry:
                 manager="systemd",
                 launcher="command",
                 run_cmd=["my-job"],
+                name="my-job",
                 kind="job",
                 stack="python-cli",
                 schedule="0 2 * * *",
@@ -51,8 +53,8 @@ class TestRegistrySerialization:
         original = _make_registry()
         restored = _json_to_registry(_registry_to_json(original))
 
-        assert "my-svc" in restored.deployed
+        svc = restored.get("service", "my-svc")
-        svc = restored.deployed["my-svc"]
+        assert svc is not None
         assert svc.manager == "systemd"
         assert svc.launcher == "python"
         assert svc.port == 9001
@@ -66,8 +68,8 @@ class TestRegistrySerialization:
         original = _make_registry()
         restored = _json_to_registry(_registry_to_json(original))
 
-        assert "my-job" in restored.deployed
+        job = restored.get("job", "my-job")
-        job = restored.deployed["my-job"]
+        assert job is not None
         assert job.launcher == "command"
         assert job.schedule == "0 2 * * *"
         assert job.kind == "job"
@@ -78,11 +80,11 @@ class TestRegistrySerialization:
         reg = NodeRegistry(
             node=NodeConfig(hostname="minimal"),
             deployed={
-                "bare": Deployment(manager="systemd", launcher="command", run_cmd=["bare"]),
+                "bare": Deployment(manager="systemd", launcher="command", run_cmd=["bare"], name="bare"),
             },
         )
         restored = _json_to_registry(_registry_to_json(reg))
-        bare = restored.deployed["bare"]
+        bare = restored.get("service", "bare")
         assert bare.port is None
         assert bare.health_path is None
         assert bare.subdomain is None