refactor: simplify env prefix convention by removing double-underscore requirement and legacy reservation rule

Signed-off-by: tercel <tercel.yi@gmail.com>

Author: tercel

CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.15.1] - 2026-03-31
+
+### Changed
+
+- **Env prefix convention simplified** — Removed the `^APCORE_[A-Z0-9]` reservation rule from `Config._validate_env_prefix()`. Sub-packages now use single-underscore prefixes (`APCORE_MCP`, `APCORE_OBSERVABILITY`, `APCORE_SYS`) instead of the double-underscore form. Only the exact `APCORE` prefix is reserved for the core namespace.
+- Built-in namespace env prefixes: `APCORE__OBSERVABILITY` → `APCORE_OBSERVABILITY`, `APCORE__SYS` → `APCORE_SYS`.
+
+---
+
 ## [0.15.0] - 2026-03-30
 
 ### Added
@@ -17,7 +26,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **`config.mount(namespace, from_file=...|from_dict=...)`** — Attach external config sources to a namespace without a unified YAML file. Primary integration path for third-party packages with existing config systems.
 - **`Config.registered_namespaces()`** — Class-level introspection; returns names of all registered namespaces.
 - **Unified YAML with namespace partitioning** — Single YAML file with namespace-keyed top-level sections. Automatic mode detection: legacy mode (no `apcore:` key, fully backward compatible) vs. namespace mode (`apcore:` key present). `_config` is a reserved meta-namespace (`strict`, `allow_unknown`).
-- **Per-namespace env override with longest-prefix-match dispatch** — Each namespace declares its own `env_prefix`. `APCORE__` double-underscore convention for apcore sub-packages (e.g., `APCORE__OBSERVABILITY`, `APCORE__SYS`) to avoid collision with the existing single-underscore `APCORE_` prefix used for flat keys.
+- **Per-namespace env override with longest-prefix-match dispatch** — Each namespace declares its own `env_prefix`. Apcore sub-packages use `APCORE_` prefixed names (e.g., `APCORE_OBSERVABILITY`, `APCORE_SYS`); the longest-prefix-match dispatch algorithm resolves any ambiguity with the core `APCORE` prefix.
 - **Hot-reload namespace support** — `config.reload()` re-reads YAML, re-detects mode, re-applies namespace defaults and env overrides, re-validates, and re-reads mounted files.
 - **New error codes** — `CONFIG_NAMESPACE_DUPLICATE`, `CONFIG_NAMESPACE_RESERVED`, `CONFIG_ENV_PREFIX_CONFLICT`, `CONFIG_MOUNT_ERROR`, `CONFIG_BIND_ERROR`
 
@@ -30,8 +39,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **New error code** — `ERROR_FORMATTER_DUPLICATE`
 
 #### Built-in Namespace Registrations (§9.15)
-- **`observability` namespace** (`APCORE__OBSERVABILITY` env prefix) — apcore pre-registers this namespace, promoting the existing `apcore.observability.*` flat config keys (tracing, metrics, logging, error_history, platform_notify) into a named subtree. Adapter packages (apcore-mcp, apcore-a2a, apcore-cli) should read from this namespace rather than independent logging defaults.
-- **`sys_modules` namespace** (`APCORE__SYS` env prefix) — apcore pre-registers this namespace, promoting the existing `apcore.sys_modules.*` flat keys into a named subtree. `register_sys_modules()` prefers `config.namespace("sys_modules")` in namespace mode with `config.get("sys_modules.*")` legacy fallback. Both registrations are 1:1 migrations of existing keys; there are no breaking changes.
+- **`observability` namespace** (`APCORE_OBSERVABILITY` env prefix) — apcore pre-registers this namespace, promoting the existing `apcore.observability.*` flat config keys (tracing, metrics, logging, error_history, platform_notify) into a named subtree. Adapter packages (apcore-mcp, apcore-a2a, apcore-cli) should read from this namespace rather than independent logging defaults.
+- **`sys_modules` namespace** (`APCORE_SYS` env prefix) — apcore pre-registers this namespace, promoting the existing `apcore.sys_modules.*` flat keys into a named subtree. `register_sys_modules()` prefers `config.namespace("sys_modules")` in namespace mode with `config.get("sys_modules.*")` legacy fallback. Both registrations are 1:1 migrations of existing keys; there are no breaking changes.
 
 #### Event Type Naming Convention and Collision Fix (§9.16)
 - **Canonical event names** — Two confirmed event type collisions in apcore-python are resolved:

README.md

@@ -142,18 +142,18 @@ apcore pre-registers two namespaces that promote its existing flat config keys:
 
 | Namespace | Env prefix | Keys |
 |-----------|-----------|------|
-| `observability` | `APCORE__OBSERVABILITY` | tracing, metrics, logging, error_history, platform_notify |
-| `sys_modules` | `APCORE__SYS` | thresholds.error_rate, thresholds.latency_p99_ms |
+| `observability` | `APCORE_OBSERVABILITY` | tracing, metrics, logging, error_history, platform_notify |
+| `sys_modules` | `APCORE_SYS` | thresholds.error_rate, thresholds.latency_p99_ms |
 
 ### Environment Variable Conventions
 
 | Pattern | When to use | Example |
 |---------|------------|---------|
 | `APCORE_KEY_NAME` | Override a flat top-level apcore key (existing convention) | `APCORE_EXECUTOR_DEFAULT__TIMEOUT=5000` |
-| `APCORE__NAMESPACE` prefix | Override keys inside a registered namespace (new convention) | `APCORE__OBSERVABILITY_TRACING_ENABLED=true` |
+| `APCORE_NAMESPACE` prefix | Override keys inside a registered namespace | `APCORE_OBSERVABILITY_TRACING_ENABLED=true` |
 | Custom prefix declared in `register_namespace` | Third-party packages with their own prefix | `MY_PLUGIN__TIMEOUT_MS=3000` |
 
-The double-underscore separator (`__`) in `APCORE__` avoids collisions with the existing single-underscore `APCORE_` flat-key prefix. Within each namespace, a single `_` maps to `.` and `__` maps to a literal `_`.
+The longest-prefix-match dispatch algorithm ensures that `APCORE_OBSERVABILITY_TRACING_ENABLED` routes to the `observability` namespace (not to a core flat key). Within each namespace, a single `_` maps to `.` and `__` maps to a literal `_`.
 
 ### New Error Codes (0.15.0)
 

src/apcore/config.py

@@ -10,7 +10,7 @@
 import dataclasses
 import logging
 import os
-import re
+
 import sys
 import threading
 from pathlib import Path
@@ -154,9 +154,6 @@
 
 _RESERVED_NAMESPACES: frozenset[str] = frozenset({"apcore", "_config"})
 
-#: Pattern that matches the APCORE_ legacy prefix — env_prefix must not match.
-_APCORE_RESERVED_ENV_PATTERN: re.Pattern[str] = re.compile(r"^APCORE_[A-Z0-9]")
-
 
 @dataclasses.dataclass
 class _NamespaceRegistration:
@@ -427,14 +424,14 @@ def register_namespace(
         Args:
             name: Namespace name (must not be reserved or already registered).
             schema: Optional JSON Schema dict or path to a JSON Schema file.
-            env_prefix: Optional env var prefix (e.g. ``"APCORE__OBSERVABILITY"``).
+            env_prefix: Optional env var prefix (e.g. ``"APCORE_OBSERVABILITY"``).
             defaults: Optional default values for this namespace.
 
         Raises:
             ConfigNamespaceReservedError: If ``name`` is a reserved namespace.
             ConfigNamespaceDuplicateError: If ``name`` is already registered.
             ConfigEnvPrefixConflictError: If ``env_prefix`` conflicts with an
-                existing prefix or matches the legacy ``APCORE_[A-Z0-9]`` pattern.
+                existing prefix.
         """
         if name in _RESERVED_NAMESPACES:
             raise ConfigNamespaceReservedError(name=name)
@@ -455,9 +452,7 @@ def register_namespace(
 
     @classmethod
     def _validate_env_prefix(cls, env_prefix: str) -> None:
-        """Raise ConfigEnvPrefixConflictError if env_prefix is already in use or reserved."""
-        if _APCORE_RESERVED_ENV_PATTERN.match(env_prefix):
-            raise ConfigEnvPrefixConflictError(env_prefix=env_prefix)
+        """Raise ConfigEnvPrefixConflictError if env_prefix is already in use."""
         for reg in _GLOBAL_NS_REGISTRY.values():
             if reg.env_prefix and reg.env_prefix == env_prefix:
                 raise ConfigEnvPrefixConflictError(env_prefix=env_prefix)
@@ -928,7 +923,7 @@ def _instantiate_model(model_class: type, data: dict[str, Any], namespace: str)
 
 Config.register_namespace(
     "observability",
-    env_prefix="APCORE__OBSERVABILITY",
+    env_prefix="APCORE_OBSERVABILITY",
     defaults={
         "tracing": {
             "enabled": False,
@@ -958,7 +953,7 @@ def _instantiate_model(model_class: type, data: dict[str, Any], namespace: str)
 
 Config.register_namespace(
     "sys_modules",
-    env_prefix="APCORE__SYS",
+    env_prefix="APCORE_SYS",
     defaults={
         "enabled": True,
         "health": {"enabled": True},

tests/test_config_bus.py

@@ -87,14 +87,9 @@ def test_register_reserved_config_raises(self) -> None:
         with pytest.raises(ConfigNamespaceReservedError):
             Config.register_namespace("_config")
 
-    def test_register_env_prefix_conflict_legacy_pattern(self) -> None:
-        # Must not match ^APCORE_[A-Z0-9]
-        with pytest.raises(ConfigEnvPrefixConflictError):
-            Config.register_namespace("envns", env_prefix="APCORE_FOO")
-
-    def test_register_env_prefix_double_underscore_ok(self) -> None:
-        # APCORE__SOMETHING is fine (double underscore)
-        Config.register_namespace("envns2", env_prefix="APCORE__ENVNS2")
+    def test_register_env_prefix_apcore_subpackage_ok(self) -> None:
+        # APCORE_SOMETHING is fine — longest-prefix-match disambiguates.
+        Config.register_namespace("envns2", env_prefix="APCORE_ENVNS2")
         names = [r["name"] for r in Config.registered_namespaces()]
         assert "envns2" in names
 
@@ -130,12 +125,12 @@ def test_sys_modules_registered(self) -> None:
     def test_observability_has_correct_env_prefix(self) -> None:
         namespaces = Config.registered_namespaces()
         ns = next(r for r in namespaces if r["name"] == "observability")
-        assert ns["env_prefix"] == "APCORE__OBSERVABILITY"
+        assert ns["env_prefix"] == "APCORE_OBSERVABILITY"
 
     def test_sys_modules_has_correct_env_prefix(self) -> None:
         namespaces = Config.registered_namespaces()
         ns = next(r for r in namespaces if r["name"] == "sys_modules")
-        assert ns["env_prefix"] == "APCORE__SYS"
+        assert ns["env_prefix"] == "APCORE_SYS"
 
 
 # ---------------------------------------------------------------------------