feat: Implement unit specification and expansion logic in configuration

core/src/castle_core/manifest.py

@@ -247,3 +247,58 @@ class JobSpec(BaseModel):
 
     manage: ManageSpec | None = None
     defaults: DefaultsSpec | None = None
+
+
+# ---------------------
+# Unit spec — unified definition
+# ---------------------
+
+
+class UnitKind(str, Enum):
+    TOOL = "tool"
+    SERVICE = "service"
+    SITE = "site"
+    JOB = "job"
+
+
+class UnitSpec(BaseModel):
+    """Unified program+deployment definition.
+
+    Expands into ProgramSpec + optional ServiceSpec/JobSpec at config load time.
+    """
+
+    id: str = ""
+    kind: UnitKind
+    description: str | None = None
+
+    # Program identity
+    source: str | None = None
+    stack: str | None = None
+    system_dependencies: list[str] = Field(default_factory=list)
+    install_extras: list[str] = Field(default_factory=list)
+    version: str | None = None
+    build: BuildSpec | None = None
+    tags: list[str] = Field(default_factory=list)
+
+    # Service fields (kind=service)
+    port: int | None = Field(default=None, ge=1, le=65535)
+    path_prefix: str | None = None
+    health_path: str | None = None
+
+    # Job fields (kind=job)
+    schedule: str | None = None
+    timezone: str = "America/Los_Angeles"
+    argv: list[str] | None = None
+
+    # Simplified env (flat dict, replaces defaults.env nesting)
+    env: EnvMap = Field(default_factory=dict)
+
+    @model_validator(mode="after")
+    def _validate_kind_fields(self) -> UnitSpec:
+        if self.kind == UnitKind.SERVICE and self.port is None:
+            raise ValueError("kind=service requires 'port'")
+        if self.kind == UnitKind.JOB and self.schedule is None:
+            raise ValueError("kind=job requires 'schedule'")
+        if self.kind == UnitKind.JOB and self.argv is None:
+            raise ValueError("kind=job requires 'argv'")
+        return self