fix: deployment contract CI bridge — container manifest, OCI labels, runtime stage

Implements the deployment contract CI bridge spec:

1. container-manifest.json — minimal CI-consumable JSON for image builds
2. OCI labels — static labels in contract, dynamic injected by CI
3. Dockerfile.runtime — runtime stage fragment for CI composition
4. from_cargo_toml() — auto-detect native deps from Cargo.toml features
5. schema_version field on DeploymentContract (default: 2)

generate-artefacts now emits 3 additional files: container-manifest.json,
deployment-contract.json, and Dockerfile.runtime.

Author: catinspace-au

src/cli/app.rs

@@ -301,15 +301,33 @@ fn generate_artefacts<A: DfeApp>(
         ));
     }
 
-    // Deployment contract
+    // Deployment contract + container manifest
     #[cfg(feature = "deployment")]
     if let Some(contract) = app.deployment_contract() {
+        // Full deployment contract (secrets, KEDA, Helm, everything)
         let path = output_dir.join("deployment-contract.json");
         let json = serde_json::to_string_pretty(&contract)
             .map_err(|e| CliError::Service(format!("deployment contract JSON failed: {e}")))?;
         std::fs::write(&path, &json)
             .map_err(|e| CliError::Service(format!("failed to write {}: {e}", path.display())))?;
         generated.push("deployment-contract.json".to_string());
+
+        // Container manifest (minimal subset for CI image builds)
+        let cm_path = output_dir.join("container-manifest.json");
+        let cm_json = crate::deployment::generate::generate_container_manifest(&contract)
+            .map_err(|e| CliError::Service(format!("container manifest failed: {e}")))?;
+        std::fs::write(&cm_path, &cm_json).map_err(|e| {
+            CliError::Service(format!("failed to write {}: {e}", cm_path.display()))
+        })?;
+        generated.push("container-manifest.json".to_string());
+
+        // Runtime stage Dockerfile fragment (for CI composition)
+        let rt_path = output_dir.join("Dockerfile.runtime");
+        let rt_content = crate::deployment::generate::generate_runtime_stage(&contract);
+        std::fs::write(&rt_path, &rt_content).map_err(|e| {
+            CliError::Service(format!("failed to write {}: {e}", rt_path.display()))
+        })?;
+        generated.push("Dockerfile.runtime".to_string());
     }
 
     if generated.is_empty() {

src/deployment/contract.rs

@@ -43,6 +43,10 @@ pub enum ImageProfile {
 /// fragment) from scratch.
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct DeploymentContract {
+    /// Contract schema version. CI checks this and fails if unsupported.
+    #[serde(default = "default_schema_version")]
+    pub schema_version: u32,
+
     /// Application name (e.g., "dfe-loader") — matched against Chart.yaml `name`.
     pub app_name: String,
 
@@ -116,6 +120,53 @@ pub struct DeploymentContract {
     /// to derive a development variant from an existing contract.
     #[serde(default)]
     pub image_profile: ImageProfile,
+
+    /// OCI image labels (static — dynamic labels injected by CI at build time).
+    #[serde(default)]
+    pub oci_labels: OciLabels,
+}
+
+/// OCI image labels for the container.
+///
+/// Static labels are set from the contract. Dynamic labels (source, revision,
+/// version, created) are injected by CI at build time via `--build-arg`.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct OciLabels {
+    /// Image title (defaults to app_name).
+    #[serde(default)]
+    pub title: String,
+    /// Image description.
+    #[serde(default)]
+    pub description: String,
+    /// Image vendor.
+    #[serde(default = "default_vendor")]
+    pub vendor: String,
+    /// License identifier.
+    #[serde(default = "default_license")]
+    pub licenses: String,
+}
+
+impl Default for OciLabels {
+    fn default() -> Self {
+        Self {
+            title: String::new(),
+            description: String::new(),
+            vendor: default_vendor(),
+            licenses: default_license(),
+        }
+    }
+}
+
+fn default_vendor() -> String {
+    "HYPERI PTY LIMITED".to_string()
+}
+
+fn default_license() -> String {
+    "FSL-1.1-ALv2".to_string()
+}
+
+fn default_schema_version() -> u32 {
+    2
 }
 
 /// Health probe endpoint paths.

src/deployment/generate.rs

@@ -101,6 +101,184 @@ ENTRYPOINT ["{binary}"]{cmd}
     )
 }
 
+// ============================================================================
+// Container Manifest (CI-consumable JSON)
+// ============================================================================
+
+/// Generate a container manifest JSON for CI consumption.
+///
+/// This is the minimal subset of the deployment contract that CI needs to
+/// build the container image. No secrets, no K8s-specific config.
+///
+/// # Errors
+///
+/// Returns an error string if JSON serialisation fails.
+pub fn generate_container_manifest(contract: &DeploymentContract) -> Result<String, String> {
+    let binary = contract.binary();
+
+    let apt_repos: Vec<serde_json::Value> = contract
+        .native_deps
+        .apt_repos
+        .iter()
+        .map(|r| {
+            serde_json::json!({
+                "key_url": r.key_url,
+                "keyring": r.keyring,
+                "url": r.url,
+                "codename": r.codename,
+                "packages": r.packages,
+            })
+        })
+        .collect();
+
+    let mut expose_ports: Vec<u16> = vec![contract.metrics_port];
+    expose_ports.extend(contract.extra_ports.iter().map(|p| p.port));
+
+    let profile_str = match contract.image_profile {
+        ImageProfile::Production => "production",
+        ImageProfile::Development => "development",
+    };
+
+    let title = if contract.oci_labels.title.is_empty() {
+        &contract.app_name
+    } else {
+        &contract.oci_labels.title
+    };
+
+    let manifest = serde_json::json!({
+        "schema_version": "1",
+        "app_name": contract.app_name,
+        "binary_name": binary,
+        "base_image": contract.base_image,
+        "image_registry": contract.image_registry,
+        "image_profile": profile_str,
+        "runtime_packages": {
+            "apt_repos": apt_repos,
+            "apt_packages": contract.native_deps.apt_packages,
+        },
+        "expose_ports": expose_ports,
+        "healthcheck": {
+            "path": contract.health.liveness_path,
+            "port": contract.metrics_port,
+            "interval": "30s",
+            "timeout": "3s",
+            "start_period": "5s",
+            "retries": 3,
+        },
+        "entrypoint": [binary],
+        "cmd": contract.entrypoint_args,
+        "user": "appuser",
+        "uid": 1000,
+        "labels": {
+            "io.hyperi.profile": profile_str,
+            "io.hyperi.app": contract.app_name,
+            "io.hyperi.metrics_port": contract.metrics_port.to_string(),
+            "org.opencontainers.image.title": title,
+            "org.opencontainers.image.description": contract.oci_labels.description,
+            "org.opencontainers.image.vendor": contract.oci_labels.vendor,
+            "org.opencontainers.image.licenses": contract.oci_labels.licenses,
+        },
+    });
+
+    serde_json::to_string_pretty(&manifest)
+        .map_err(|e| format!("container manifest JSON failed: {e}"))
+}
+
+// ============================================================================
+// Runtime Stage Fragment (for CI Dockerfile composition)
+// ============================================================================
+
+/// Generate only the runtime stage of a Dockerfile as a fragment.
+///
+/// CI composes the full Dockerfile by prepending its own build stages
+/// (cargo-chef pattern) and appending this runtime stage. This keeps
+/// the boundary clean: rustlib owns what's *in* the container, CI owns
+/// how to *build* the binary.
+#[must_use]
+pub fn generate_runtime_stage(contract: &DeploymentContract) -> String {
+    let binary = contract.binary();
+    let apt_block = build_apt_block(&contract.native_deps, contract.image_profile);
+
+    let profile_label = match contract.image_profile {
+        ImageProfile::Production => "production",
+        ImageProfile::Development => "development",
+    };
+
+    let title = if contract.oci_labels.title.is_empty() {
+        &contract.app_name
+    } else {
+        &contract.oci_labels.title
+    };
+
+    let expose_ports = {
+        let mut ports = vec![contract.metrics_port.to_string()];
+        for p in &contract.extra_ports {
+            ports.push(p.port.to_string());
+        }
+        ports.join(" ")
+    };
+
+    let cmd = if contract.entrypoint_args.is_empty() {
+        String::new()
+    } else {
+        let args: Vec<String> = contract
+            .entrypoint_args
+            .iter()
+            .map(|a| format!("\"{a}\""))
+            .collect();
+        format!("\nCMD [{}]", args.join(", "))
+    };
+
+    format!(
+        r#"# --- Runtime stage (generated by hyperi-rustlib deployment contract) ---
+FROM {base_image} AS runtime
+
+# Static OCI labels (from contract)
+LABEL org.opencontainers.image.title="{title}"
+LABEL org.opencontainers.image.description="{description}"
+LABEL org.opencontainers.image.vendor="{vendor}"
+LABEL org.opencontainers.image.licenses="{licenses}"
+LABEL io.hyperi.profile="{profile_label}"
+
+{apt_block}
+# Dynamic OCI labels (injected by CI at build time)
+ARG OCI_SOURCE=""
+ARG OCI_REVISION=""
+ARG OCI_VERSION=""
+ARG OCI_CREATED=""
+LABEL org.opencontainers.image.source="${{OCI_SOURCE}}"
+LABEL org.opencontainers.image.revision="${{OCI_REVISION}}"
+LABEL org.opencontainers.image.version="${{OCI_VERSION}}"
+LABEL org.opencontainers.image.created="${{OCI_CREATED}}"
+
+COPY --from=builder /app/target/release/{binary} /usr/local/bin/{binary}
+RUN chmod +x /usr/local/bin/{binary}
+
+RUN userdel -r ubuntu && useradd --create-home --uid 1000 appuser
+USER appuser
+
+EXPOSE {expose_ports}
+
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD curl -sf http://localhost:{metrics_port}{liveness_path} > /dev/null || exit 1
+
+ENTRYPOINT ["{binary}"]{cmd}
+"#,
+        base_image = contract.base_image,
+        title = title,
+        description = contract.oci_labels.description,
+        vendor = contract.oci_labels.vendor,
+        licenses = contract.oci_labels.licenses,
+        profile_label = profile_label,
+        apt_block = apt_block,
+        binary = binary,
+        expose_ports = expose_ports,
+        metrics_port = contract.metrics_port,
+        liveness_path = contract.health.liveness_path,
+        cmd = cmd,
+    )
+}
+
 /// Diagnostic tools installed in development images.
 const DEV_TOOLS: &[&str] = &[
     "bash",

src/deployment/mod.rs

@@ -73,17 +73,20 @@
 
 mod contract;
 mod error;
-mod generate;
+pub mod generate;
 mod keda;
 mod native_deps;
 mod validate;
 
 pub use contract::{
-    DeploymentContract, HealthContract, ImageProfile, PortContract, SecretEnvContract,
+    DeploymentContract, HealthContract, ImageProfile, OciLabels, PortContract, SecretEnvContract,
     SecretGroupContract,
 };
 pub use error::{ContractMismatch, DeploymentError};
-pub use generate::{generate_chart, generate_compose_fragment, generate_dockerfile};
+pub use generate::{
+    generate_chart, generate_compose_fragment, generate_container_manifest, generate_dockerfile,
+    generate_runtime_stage,
+};
 pub use keda::{KedaConfig, KedaContract};
 pub use native_deps::{AptRepoContract, NativeDepsContract};
 pub use validate::{validate_dockerfile, validate_helm_values};

src/deployment/native_deps.rs

@@ -153,13 +153,89 @@ impl NativeDepsContract {
         }
     }
 
+    /// Auto-detect native deps from the app's Cargo.toml.
+    ///
+    /// Reads `[dependencies.hyperi-rustlib]` features from the given Cargo.toml
+    /// and maps them to runtime packages. Falls back to empty deps if parsing fails.
+    #[must_use]
+    pub fn from_cargo_toml(cargo_toml_path: &std::path::Path, base_image: &str) -> Self {
+        let Ok(content) = std::fs::read_to_string(cargo_toml_path) else {
+            return Self::default();
+        };
+
+        // Parse features from the hyperi-rustlib dependency line
+        // Matches: features = ["transport-kafka", "spool", ...]
+        let features = extract_rustlib_features(&content);
+        if features.is_empty() {
+            return Self::default();
+        }
+
+        let feature_refs: Vec<&str> = features.iter().map(String::as_str).collect();
+        Self::for_rustlib_features(&feature_refs, base_image)
+    }
+
     /// Returns true if there are no native deps to install.
     #[must_use]
     pub fn is_empty(&self) -> bool {
         self.apt_repos.is_empty() && self.apt_packages.is_empty()
     }
 }
 
+/// Extract hyperi-rustlib feature names from Cargo.toml content.
+///
+/// Parses the `features = [...]` array from the `hyperi-rustlib` dependency.
+/// Returns empty vec if not found or parsing fails.
+fn extract_rustlib_features(content: &str) -> Vec<String> {
+    // Find the hyperi-rustlib dependency line
+    let mut in_rustlib = false;
+    let mut features = Vec::new();
+
+    for line in content.lines() {
+        let trimmed = line.trim();
+
+        // Single-line: hyperi-rustlib = { version = "...", features = [...] }
+        if trimmed.starts_with("hyperi-rustlib")
+            && trimmed.contains("features")
+            && let Some(start) = trimmed.find("features = [")
+        {
+            let after = &trimmed[start + 12..];
+            if let Some(end) = after.find(']') {
+                let feature_str = &after[..end];
+                for feat in feature_str.split(',') {
+                    let f = feat.trim().trim_matches('"').trim();
+                    if !f.is_empty() {
+                        features.push(f.to_string());
+                    }
+                }
+                return features;
+            }
+        }
+
+        // Multi-line: features = [\n"transport-kafka",\n...\n]
+        if trimmed.starts_with("hyperi-rustlib") {
+            in_rustlib = true;
+            continue;
+        }
+        if in_rustlib {
+            if trimmed.starts_with(']') {
+                return features;
+            }
+            if trimmed.starts_with('"') {
+                let f = trimmed.trim_matches('"').trim_end_matches(',').trim();
+                if !f.is_empty() {
+                    features.push(f.to_string());
+                }
+            }
+            // End of dependency block
+            if trimmed.starts_with('[') && !trimmed.starts_with("[dependencies") {
+                return features;
+            }
+        }
+    }
+
+    features
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;