Components declare non-secret environment as receipted state

Feature flags, Redis database ids, and other plain configuration move out
of encrypted fragments into a declared spec.environment block on the
Component: string-only values validated against control characters, typed
into inventory, serialized (they are config, not secrets), and merged
into the rendered environment file alongside secret fragments. A key may
live in exactly one place - a declared key that also appears in a secret
source fails rendering with secrets_key_conflict naming the key and file,
so neither channel can silently shadow the other. The example component
declares a flag and its Redis URL; the secrets guide documents the split.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HX4L4HUFnJ5bq7SFQwHzDU

Author: romamo

docs/secrets-guide.md

@@ -57,6 +57,27 @@ sops secrets/production/crm/backend.env
 # opens your editor; write KEY=VALUE lines; sops encrypts on save
 ```
 
+## Non-secret configuration: declare it in state
+
+Feature flags, Redis database ids, and other plain configuration do not
+belong in encrypted fragments — they belong in the component's declared
+`environment` block, where changes are diffable, reviewable, and audited
+like any other state:
+
+```yaml
+# state/production/components/crm-backend.yaml
+spec:
+  environment:
+    FEATURE_SIGNUPS: "true"
+    REDIS_URL: redis://127.0.0.1:6379/0
+```
+
+Rendering merges declared entries with the secret fragments into one
+environment file. A key may live in **exactly one place**: if a declared
+key also appears in a secret source, rendering fails fast with a
+`secrets_key_conflict` naming the key and the offending file — no silent
+shadowing in either direction.
+
 ## Declaring and rendering
 
 Projects declare platform-scope references; components declare project and

sdk/src/cloudfall/inventory.py

@@ -494,10 +494,11 @@ class ComponentInventory:
     service: ComponentService
     health_check: ComponentHealthCheck
     secret_refs: tuple[SecretReference, ...] = ()
+    environment: tuple[tuple[str, str], ...] = ()
 
     def as_dict(self) -> dict[str, object]:
         """Serialize the component for inventory consumers."""
-        return {
+        result: dict[str, object] = {
             "id": self.resource_id.value,
             "project": self.project_id.value,
             "servers": [server.value for server in self.server_ids],
@@ -508,6 +509,9 @@ def as_dict(self) -> dict[str, object]:
             "service": self.service.as_dict(),
             "healthCheck": self.health_check.as_dict(),
         }
+        if self.environment:
+            result["environment"] = dict(self.environment)
+        return result
 
 
 @dataclass(frozen=True, slots=True)
@@ -1453,9 +1457,22 @@ def _component_inventory(document: ResourceDocument) -> ComponentInventory:
         ),
         health_check=_component_health_check(health),
         secret_refs=_secret_references(spec.get("secretRefs")),
+        environment=_declared_environment(spec.get("environment")),
     )
 
 
+def _declared_environment(value: object) -> tuple[tuple[str, str], ...]:
+    if value is None:
+        return ()
+    if not isinstance(value, dict) or not all(
+        isinstance(key, str) and isinstance(entry, str)
+        for key, entry in value.items()
+    ):
+        message = "validated component environment is not a string mapping"
+        raise TypeError(message)
+    return tuple(value.items())
+
+
 def _secret_references(value: object) -> tuple[SecretReference, ...]:
     if value is None:
         return ()

sdk/src/cloudfall/secrets.py

@@ -33,6 +33,7 @@
 _ERROR_SOURCE_INVALID = "secrets_source_invalid"
 _ERROR_COMPONENT_UNKNOWN = "secrets_component_unknown"
 _ERROR_DECRYPT_FAILED = "secrets_decrypt_failed"
+_ERROR_KEY_CONFLICT = "secrets_key_conflict"
 _KEY_PATTERN = re.compile(r"[A-Za-z_][A-Za-z0-9_]*")
 _FILE_MODE = 0o600
 
@@ -111,11 +112,19 @@ def render_environment(
         if project.resource_id == component.project_id
     )
     references = (*project.secret_refs, *component.secret_refs)
-    merged: dict[str, str] = {
-        key: value
-        for reference in references
-        for key, value in provider.fetch(reference)
-    }
+    declared = dict(component.environment)
+    merged: dict[str, str] = dict(declared)
+    for reference in references:
+        for key, value in provider.fetch(reference):
+            if key in declared:
+                message = (
+                    f"{key} is declared in the component's non-secret "
+                    "environment and also provided by the secret source "
+                    f"{provider.source_path(reference)}; a key must live "
+                    "in exactly one place"
+                )
+                raise SecretsError(_ERROR_KEY_CONFLICT, message)
+            merged[key] = value
     content = "".join(f"{key}={value}\n" for key, value in merged.items())
     output_path.parent.mkdir(parents=True, exist_ok=True)
     descriptor = os.open(
@@ -130,6 +139,7 @@ def render_environment(
         "environmentFile": str(output_path),
         "sha256": hashlib.sha256(content.encode("utf-8")).hexdigest(),
         "keys": sorted(merged),
+        "declaredKeys": sorted(declared),
         "references": [reference.as_dict() for reference in references],
     }
 

sdk/tests/test_secrets.py

@@ -68,10 +68,19 @@ def test_render_environment_merges_refs_in_override_order(
     assert "LOG_LEVEL=info" in content
     assert "LOG_LEVEL=warning" not in content
     assert "STRIPE_KEY=sk_test_123" in content
+    assert "FEATURE_SIGNUPS=true" in content
+    assert "REDIS_URL=redis://127.0.0.1:6379/0" in content
     mode = stat.S_IMODE(output.stat().st_mode)
     assert mode == 0o600
     assert result["status"] == "ok"
-    assert result["keys"] == ["LOG_LEVEL", "SENTRY_DSN", "STRIPE_KEY"]
+    assert result["keys"] == [
+        "FEATURE_SIGNUPS",
+        "LOG_LEVEL",
+        "REDIS_URL",
+        "SENTRY_DSN",
+        "STRIPE_KEY",
+    ]
+    assert result["declaredKeys"] == ["FEATURE_SIGNUPS", "REDIS_URL"]
     serialized = str(result)
     assert "sk_test_123" not in serialized
     assert "https://shared.example/1" not in serialized
@@ -124,3 +133,23 @@ def test_unknown_component_is_refused(tmp_path: Path) -> None:
         )
 
     assert caught.value.code == "secrets_component_unknown"
+
+
+def test_declared_and_secret_key_conflicts_fail_fast(tmp_path: Path) -> None:
+    provider = _provider(tmp_path)
+    backend = tmp_path / "secrets" / "production" / "crm" / "backend.env"
+    backend.write_text(
+        "STRIPE_KEY=sk_test_123\nFEATURE_SIGNUPS=false\n", encoding="utf-8"
+    )
+
+    with pytest.raises(SecretsError) as caught:
+        render_environment(
+            _context(tmp_path),
+            ResourceId.from_boundary("crm-backend"),
+            provider,
+            tmp_path / "out.env",
+        )
+
+    assert caught.value.code == "secrets_key_conflict"
+    assert "FEATURE_SIGNUPS" in caught.value.message
+    assert "exactly one place" in caught.value.message

state/examples/components/crm-backend.yaml

@@ -29,6 +29,9 @@ spec:
       - 127.0.0.1
       - --port
       - "8100"
+  environment:
+    FEATURE_SIGNUPS: "true"
+    REDIS_URL: redis://127.0.0.1:6379/0
   healthCheck:
     type: http
     scheme: http

state/schemas/v1/component.schema.json

@@ -193,6 +193,18 @@
             }
           ]
         },
+        "environment": {
+          "type": "object",
+          "minProperties": 1,
+          "patternProperties": {
+            "^[A-Za-z_][A-Za-z0-9_]*$": {
+              "type": "string",
+              "maxLength": 1000,
+              "pattern": "^[^\\u0000-\\u001f\\u007f]*$"
+            }
+          },
+          "additionalProperties": false
+        },
         "secretRefs": {
           "type": "array",
           "items": {