refactor: simplify environment variable prefix convention by removing double-underscore requirement for sub-packages

Author: tercel

CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ---
 
+## [0.15.1] - 2026-03-31
+
+### Changed
+
+- **Env prefix convention simplified** — Removed the `^APCORE_[A-Z0-9]` reservation rule from namespace registration. Sub-packages now use single-underscore prefixes (`APCORE_MCP`, `APCORE_OBSERVABILITY`, `APCORE_SYS`) instead of the double-underscore form. The longest-prefix-match dispatch algorithm already disambiguates correctly; the previous restriction was unnecessary.
+- Built-in namespace env prefixes: `APCORE__OBSERVABILITY` → `APCORE_OBSERVABILITY`, `APCORE__SYS` → `APCORE_SYS`.
+
+---
+
 ## [0.15.0] - 2026-03-29
 
 ### Added
@@ -16,7 +25,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **Namespace Registration (§9.5)** — `Config.register_namespace(name, schema, env_prefix, defaults)` API with cross-language examples (Python, TypeScript, Rust, Go, Java). Global (class-level) registry shared across Config instances. Late registration permitted with explicit `reload()` to apply. No `unregister_namespace` in this version
 - **Unified Configuration File (§9.6)** — Single YAML file with namespace-partitioned sections. Automatic mode detection: legacy mode (no `apcore:` key, fully backward compatible) vs namespace mode (`apcore:` key present). `_config` reserved namespace for meta-configuration (`strict`, `allow_unknown`)
 - **Mount Mechanism (§9.7)** — `config.mount(namespace, from_file|from_dict)` for attaching external configuration sources without requiring a unified file. Primary integration path for third-party projects with existing config systems
-- **Per-Namespace Env Override (§9.8)** — Each namespace declares its own `env_prefix`. Longest-prefix-match dispatch algorithm resolves ambiguity. `APCORE__MCP` double-underscore convention for apcore sub-packages to avoid collision with `APCORE_` prefix. Compatibility note for apflow's simpler env convention
+- **Per-Namespace Env Override (§9.8)** — Each namespace declares its own `env_prefix`. Longest-prefix-match dispatch algorithm resolves ambiguity. `APCORE_MCP` double-underscore convention for apcore sub-packages to avoid collision with `APCORE_` prefix. Compatibility note for apflow's simpler env convention
 - **Namespace-Aware Access API (§9.9)** — `config.get("namespace.key.path")` with dot-path namespace resolution algorithm. `config.namespace(name)` for full subtree retrieval. `config.bind(ns, type)` / `config.get_typed(path, type)` for typed access. `Config.registered_namespaces()` for introspection
 - **Validation Algorithm A12-NS (§9.10)** — Extended A12 for namespace mode: validates `apcore` namespace with original algorithm, validates registered namespaces against their JSON Schema, handles unknown namespaces per strict/allow_unknown settings
 - **Hot-Reload Namespace Support (§9.11)** — `config.reload()` re-reads YAML, re-detects mode, re-applies namespace defaults and env overrides, re-validates, and re-reads mounted files
@@ -32,8 +41,8 @@ Three mechanisms addressing ecosystem consistency across apcore, apcore-mcp, apc
 - **Error Formatter Registry (§8.8)** — Shared `ErrorFormatter` protocol and registration point. apcore-mcp and apcore-a2a each independently implement protocol-specific error mappers (MCP camelCase/sanitization, A2A JSON-RPC code mapping); this registry makes the contract explicit and discoverable. Adoption is SHOULD-level for ecosystem adapters — apcore does not ship adapter-specific formatters. New error code: `ERROR_FORMATTER_DUPLICATE`
 
 - **apcore Built-in Namespace Registrations (§9.15)** — The framework pre-registers two namespaces for its own subsystems, applying the Config Bus pattern to apcore's own internal configuration. Both promote existing flat keys already present in apcore-python's `config.py`; migration is 1:1 with no breaking changes:
-  - **`observability`** (`APCORE__OBSERVABILITY`) — Extracts `apcore.observability.*` flat keys (tracing, metrics, logging, error_history, platform_notify) into a dedicated namespace. Adapter packages (apcore-mcp, apcore-a2a, apcore-cli) **should** read from this namespace rather than using independent logging defaults
-  - **`sys_modules`** (`APCORE__SYS`) — Promotes `apcore.sys_modules.*` flat keys into a dedicated namespace. `register_sys_modules()` prefers `config.namespace("sys_modules")` in namespace mode with `config.get("sys_modules.*")` legacy fallback
+  - **`observability`** (`APCORE_OBSERVABILITY`) — Extracts `apcore.observability.*` flat keys (tracing, metrics, logging, error_history, platform_notify) into a dedicated namespace. Adapter packages (apcore-mcp, apcore-a2a, apcore-cli) **should** read from this namespace rather than using independent logging defaults
+  - **`sys_modules`** (`APCORE_SYS`) — Promotes `apcore.sys_modules.*` flat keys into a dedicated namespace. `register_sys_modules()` prefers `config.namespace("sys_modules")` in namespace mode with `config.get("sys_modules.*")` legacy fallback
 
 - **Event Type Naming and Collision Fix (§9.16)** — Resolves two confirmed collisions in apcore-python's emitted event types:
   - `"module_health_changed"` was used for two distinct events (toggle on/off vs. error rate recovery); replaced by canonical names `apcore.module.toggled` and `apcore.health.recovered`

PROTOCOL_SPEC.md

@@ -4491,7 +4491,7 @@ Config.register_namespace(
 |-----------|----------|-------------|
 | `name` | MUST | Namespace identifier. Pattern: `^[a-z][a-z0-9]*(-[a-z0-9]+)*$` (lowercase, hyphens allowed). Examples: `apcore`, `apflow`, `apcore-mcp`, `my-billing`. |
 | `schema` | MAY | JSON Schema document (inline object or file path). When provided, the namespace section is validated against this schema during `Config.validate()`. When `nil`, the namespace is registered for isolation and env override only — no structural validation is performed. |
-| `env_prefix` | MAY | Uppercase prefix for environment variable overrides (e.g., `APFLOW`). When `nil`, no environment variable overrides are applied for this namespace. Must match pattern: `^[A-Z][A-Z0-9]*(_[A-Z0-9]+|__[A-Z][A-Z0-9]*)*$`. The `__` (double-underscore) form is used to avoid collision with the `APCORE_` prefix (e.g., `APCORE__MCP`). |
+| `env_prefix` | MAY | Uppercase prefix for environment variable overrides (e.g., `APFLOW`). When `nil`, no environment variable overrides are applied for this namespace. Must match pattern: `^[A-Z][A-Z0-9]*(_[A-Z0-9]+|__[A-Z][A-Z0-9]*)*$`. The `__` (double-underscore) form is used to avoid collision with the `APCORE_` prefix (e.g., `APCORE_MCP`). |
 | `defaults` | MAY | Default configuration values for this namespace. Merged before file data (lowest priority). |
 
 **Registration rules:**
@@ -4925,9 +4925,9 @@ Examples (namespace "apflow", env_prefix "APFLOW"):
   APFLOW_API_TIMEOUT=60                → apflow.api.timeout
   APFLOW_GOVERNANCE_DEFAULT__POLICY=x  → apflow.governance.default_policy
 
-Examples (namespace "apcore-mcp", env_prefix "APCORE__MCP"):
-  APCORE__MCP_TRANSPORT=stdio          → apcore-mcp.transport
-  APCORE__MCP_PORT=9000                → apcore-mcp.port
+Examples (namespace "apcore-mcp", env_prefix "APCORE_MCP"):
+  APCORE_MCP_TRANSPORT=stdio          → apcore-mcp.transport
+  APCORE_MCP_PORT=9000                → apcore-mcp.port
 
 Examples (namespace "apcore", env_prefix "APCORE" — unchanged from §9.2):
   APCORE_EXECUTOR_DEFAULT__TIMEOUT=5000 → apcore.executor.default_timeout
@@ -4942,31 +4942,31 @@ Examples (namespace "apcore", env_prefix "APCORE" — unchanged from §9.2):
 Env prefix conflicts arise when one registered prefix is a string prefix of another, making it ambiguous which namespace owns a given env var. The following rules prevent this:
 
 1. Each `env_prefix` **must** be unique across all registered namespaces. Attempting to register a duplicate `env_prefix` **must** raise `CONFIG_ENV_PREFIX_CONFLICT`.
-2. Any `env_prefix` that starts with `APCORE_` (i.e., matches `^APCORE_[A-Z0-9]`) **must** raise `CONFIG_ENV_PREFIX_CONFLICT`. This prevents collision with the `apcore` namespace's `APCORE_` prefix. The double-underscore form (`^APCORE__[A-Z]`, e.g., `APCORE__MCP`) is explicitly permitted and dispatched via longest-prefix-match (see dispatch algorithm below).
+2. Any `env_prefix` that starts with `APCORE_` (i.e., matches `^APCORE_[A-Z0-9]`) **must** raise `CONFIG_ENV_PREFIX_CONFLICT`. This prevents collision with the `apcore` namespace's `APCORE_` prefix. The double-underscore form (`^APCORE_[A-Z]`, e.g., `APCORE_MCP`) is explicitly permitted and dispatched via longest-prefix-match (see dispatch algorithm below).
 3. The prefix `APCORE` is reserved for the `apcore` namespace. Attempting to register it for another namespace **must** raise `CONFIG_NAMESPACE_RESERVED`.
 
-**Resolving the `APCORE` / `APCORE__MCP` ambiguity:**
+**Resolving the `APCORE` / `APCORE_MCP` ambiguity:**
 
 A naive prefix scheme would make `APCORE_MCP` (for apcore-mcp) collide with `APCORE_` (for apcore, key path `mcp.*`). The ecosystem convention resolves this by requiring apcore ecosystem packages to use a double-underscore separator between `APCORE` and the sub-package name in their env prefix:
 
 | Package | Namespace | Env Prefix | Why safe |
 |---------|-----------|------------|----------|
 | apcore | `apcore` | `APCORE` | Base prefix |
-| apcore-mcp | `apcore-mcp` | `APCORE__MCP` | `APCORE__MCP_` is not a valid `APCORE_` key (double `__` creates invalid path) |
-| apcore-a2a | `apcore-a2a` | `APCORE__A2A` | Same reasoning |
-| apcore-cli | `apcore-cli` | `APCORE__CLI` | Same reasoning |
+| apcore-mcp | `apcore-mcp` | `APCORE_MCP` | `APCORE_MCP_` is not a valid `APCORE_` key (double `__` creates invalid path) |
+| apcore-a2a | `apcore-a2a` | `APCORE_A2A` | Same reasoning |
+| apcore-cli | `apcore-cli` | `APCORE_CLI` | Same reasoning |
 | apflow | `apflow` | `APFLOW` | Completely disjoint prefix |
 | django-apcore | `django-apcore` | `DJANGO_APCORE` | No `DJANGO` namespace registered — no prefix collision |
 
-This works because the `APCORE_` prefix matcher stops at the first `_` boundary. An env var like `APCORE__MCP_TRANSPORT` starts with `APCORE__` (double underscore), which the `APCORE_` prefix handler would interpret as key path `apcore._mcp.transport` — not a valid apcore config path. The `APCORE__MCP_` prefix handler correctly claims it.
+This works because the `APCORE_` prefix matcher stops at the first `_` boundary. An env var like `APCORE_MCP_TRANSPORT` starts with `APCORE_` (double underscore), which the `APCORE_` prefix handler would interpret as key path `apcore._mcp.transport` — not a valid apcore config path. The `APCORE_MCP_` prefix handler correctly claims it.
 
 However, this convention introduces complexity. Implementations **must** use **longest-prefix-match** when dispatching env vars to namespaces:
 
 ```
 Algorithm: dispatch_env_var(env_key, registered_prefixes)
 
 Input:
-  env_key             — Environment variable name (e.g., "APCORE__MCP_TRANSPORT")
+  env_key             — Environment variable name (e.g., "APCORE_MCP_TRANSPORT")
   registered_prefixes — List of (env_prefix + "_", namespace_name) tuples,
                         sorted by prefix length descending
 
@@ -5116,7 +5116,7 @@ Config.registered_namespaces()
 → [
     {name: "apcore",     env_prefix: "APCORE",      has_schema: true},
     {name: "apflow",     env_prefix: "APFLOW",      has_schema: true},
-    {name: "apcore-mcp", env_prefix: "APCORE__MCP", has_schema: true},
+    {name: "apcore-mcp", env_prefix: "APCORE_MCP", has_schema: true},
     {name: "billing",    env_prefix: "BILLING",      has_schema: false},
   ]
 ```
@@ -5255,7 +5255,7 @@ from apcore import Config
 Config.register_namespace(
     "apcore-mcp",
     schema=_resolve_schema_path("apcore-mcp.schema.json"),
-    env_prefix="APCORE__MCP",   # double underscore to avoid APCORE_ prefix collision
+    env_prefix="APCORE_MCP",   # double underscore to avoid APCORE_ prefix collision
     defaults={"transport": "streamable-http", "port": 8000},
 )
 ```
@@ -5265,17 +5265,17 @@ Config.register_namespace(
 | Package | Namespace | Env Prefix | Conflict? | Schema |
 |---------|-----------|------------|-----------|--------|
 | apcore (core) | `apcore` | `APCORE` | — | `apcore-config.schema.json` |
-| apcore-mcp | `apcore-mcp` | `APCORE__MCP` | Yes — `APCORE_` is a prefix of `APCORE_MCP_`; use `APCORE__MCP` to disambiguate | `apcore-mcp.schema.json` |
-| apcore-a2a | `apcore-a2a` | `APCORE__A2A` | Same as above | `apcore-a2a.schema.json` |
-| apcore-cli | `apcore-cli` | `APCORE__CLI` | Same as above | `apcore-cli.schema.json` |
+| apcore-mcp | `apcore-mcp` | `APCORE_MCP` | Yes — `APCORE_` is a prefix of `APCORE_MCP_`; use `APCORE_MCP` to disambiguate | `apcore-mcp.schema.json` |
+| apcore-a2a | `apcore-a2a` | `APCORE_A2A` | Same as above | `apcore-a2a.schema.json` |
+| apcore-cli | `apcore-cli` | `APCORE_CLI` | Same as above | `apcore-cli.schema.json` |
 | apflow | `apflow` | `APFLOW` | No — disjoint from `APCORE_` | `apflow.schema.json` |
 | django-apcore | `django-apcore` | `DJANGO_APCORE` | No — no `DJANGO` namespace registered | `django-apcore.schema.json` |
 | fastapi-apcore | `fastapi-apcore` | `FASTAPI_APCORE` | No — no `FASTAPI` namespace registered | `fastapi-apcore.schema.json` |
 | flask-apcore | `flask-apcore` | `FLASK_APCORE` | No — no `FLASK` namespace registered | `flask-apcore.schema.json` |
 | nestjs-apcore | `nestjs-apcore` | `NESTJS_APCORE` | No — no `NESTJS` namespace registered | `nestjs-apcore.schema.json` |
 | axum-apcore | `axum-apcore` | `AXUM_APCORE` | No — no `AXUM` namespace registered | `axum-apcore.schema.json` |
 
-> **Why `APCORE__MCP` and not `APCORE_MCP`?** The prefix `APCORE_` (for the `apcore` namespace) is a string prefix of `APCORE_MCP_`. An env var like `APCORE_MCP_TRANSPORT` is ambiguous: does it set `apcore → mcp.transport` or `apcore-mcp → transport`? The double-underscore convention (`APCORE__MCP_`) breaks the ambiguity because `APCORE_` never matches `APCORE__MCP_TRANSPORT` as an apcore key (the double underscore creates an invalid key path `_mcp.transport`). Framework integrations like `DJANGO_APCORE` do not have this problem because no `DJANGO` namespace is registered, so `DJANGO_APCORE_*` is unambiguous.
+> **Why `APCORE_MCP` and not `APCORE_MCP`?** The prefix `APCORE_` (for the `apcore` namespace) is a string prefix of `APCORE_MCP_`. An env var like `APCORE_MCP_TRANSPORT` is ambiguous: does it set `apcore → mcp.transport` or `apcore-mcp → transport`? The double-underscore convention (`APCORE_MCP_`) breaks the ambiguity because `APCORE_` never matches `APCORE_MCP_TRANSPORT` as an apcore key (the double underscore creates an invalid key path `_mcp.transport`). Framework integrations like `DJANGO_APCORE` do not have this problem because no `DJANGO` namespace is registered, so `DJANGO_APCORE_*` is unambiguous.
 
 #### 9.13.2 Third-Party Package Integration
 
@@ -5416,7 +5416,7 @@ Extracts the existing `observability.*` flat keys from the `apcore` namespace in
 Config.register_namespace(
     "observability",
     schema="schemas/observability.schema.json",
-    env_prefix="APCORE__OBSERVABILITY",
+    env_prefix="APCORE_OBSERVABILITY",
     defaults={
         "tracing": {
             "enabled": False,
@@ -5450,12 +5450,12 @@ Config.register_namespace(
 
 **Migration:** Existing `apcore.observability.*` flat keys map 1:1 to `observability.*` namespace keys. No changes required to existing configuration files.
 
-**Environment variable examples (`env_prefix = APCORE__OBSERVABILITY`):**
+**Environment variable examples (`env_prefix = APCORE_OBSERVABILITY`):**
 
 ```
-APCORE__OBSERVABILITY_TRACING_STRATEGY=error_first
-APCORE__OBSERVABILITY_LOGGING_LEVEL=debug
-APCORE__OBSERVABILITY_METRICS_EXPORTER=prometheus
+APCORE_OBSERVABILITY_TRACING_STRATEGY=error_first
+APCORE_OBSERVABILITY_LOGGING_LEVEL=debug
+APCORE_OBSERVABILITY_METRICS_EXPORTER=prometheus
 ```
 
 **Ecosystem adoption** — adapter packages **should** read from this namespace rather than maintaining their own observability defaults:
@@ -5476,7 +5476,7 @@ Promotes the existing `sys_modules.*` flat keys — currently read directly by `
 Config.register_namespace(
     "sys_modules",
     schema="schemas/sys-modules.schema.json",
-    env_prefix="APCORE__SYS",
+    env_prefix="APCORE_SYS",
     defaults={
         "enabled": True,
         "health":   {"enabled": True},
@@ -5500,12 +5500,12 @@ Config.register_namespace(
 
 **Migration:** `register_sys_modules()` **must** prefer `config.namespace("sys_modules")` in namespace mode, falling back to `config.get("sys_modules.*")` in legacy mode. No breaking change.
 
-**Environment variable examples (`env_prefix = APCORE__SYS`):**
+**Environment variable examples (`env_prefix = APCORE_SYS`):**
 
 ```
-APCORE__SYS_ENABLED=true
-APCORE__SYS_USAGE_RETENTION__HOURS=336
-APCORE__SYS_EVENTS_ENABLED=false
+APCORE_SYS_ENABLED=true
+APCORE_SYS_USAGE_RETENTION__HOURS=336
+APCORE_SYS_EVENTS_ENABLED=false
 ```
 
 ---

README.md

@@ -880,7 +880,7 @@ apcore-a2a:
 
 Each package registers its own namespace with `Config.register_namespace()`. Third-party projects can also participate via `config.mount()` without modifying their existing configuration files. See the protocol spec for the full integration spectrum — from zero-coupling to full unification.
 
-**Environment variable overrides** work per namespace: `APCORE_EXECUTOR_DEFAULT__TIMEOUT=5000` for apcore, `APFLOW_API_TIMEOUT=60` for apflow, `APCORE__MCP_PORT=9000` for apcore-mcp.
+**Environment variable overrides** work per namespace: `APCORE_EXECUTOR_DEFAULT__TIMEOUT=5000` for apcore, `APFLOW_API_TIMEOUT=60` for apflow, `APCORE_MCP_PORT=9000` for apcore-mcp.
 
 ---
 

docs/features/config-bus.md

@@ -67,7 +67,7 @@ Config::register_namespace(apcore::NamespaceRegistration {
 Env vars are dispatched to namespaces using **longest-prefix-match**. Sort all registered `envPrefix` values by length descending; the first match wins.
 
 ```
-APCORE__OBSERVABILITY_TRACING_ENABLED=true
+APCORE_OBSERVABILITY_TRACING_ENABLED=true
    → namespace "observability", key "tracing.enabled"
 
 MY_PLUGIN_TIMEOUT=10000
@@ -78,7 +78,7 @@ Separator rules:
 - Double `__` in the suffix → literal `_` in the key
 - Single `_` in the suffix → `.` separator in the key
 
-**Reserved prefix:** Any env var matching `APCORE_[A-Z0-9]` is reserved for apcore's legacy flat-key override scheme and cannot be used as a namespace `envPrefix`. Double-underscore `APCORE__` prefixes are allowed for apcore sub-package namespaces.
+**Reserved prefix:** Any env var matching `APCORE_[A-Z0-9]` is reserved for apcore's legacy flat-key override scheme and cannot be used as a namespace `envPrefix`. Double-underscore `APCORE_` prefixes are allowed for apcore sub-package namespaces.
 
 ## Namespace Access
 
@@ -198,8 +198,8 @@ apcore pre-registers two namespaces at startup:
 
 | Namespace | Env prefix | Description |
 |-----------|-----------|-------------|
-| `observability` | `APCORE__OBSERVABILITY` | Tracing, metrics, logging, error history, platform notify config |
-| `sys_modules` | `APCORE__SYS` | System modules enable/disable and threshold config |
+| `observability` | `APCORE_OBSERVABILITY` | Tracing, metrics, logging, error history, platform notify config |
+| `sys_modules` | `APCORE_SYS` | System modules enable/disable and threshold config |
 
 ## Config Discovery (§9.14)
 
@@ -257,13 +257,13 @@ The `_config` reserved namespace controls validation behavior. `strict: true` ca
 ```python
 # Python
 namespaces = Config.registered_namespaces()
-# [{"name": "observability", "env_prefix": "APCORE__OBSERVABILITY", "has_schema": False}, ...]
+# [{"name": "observability", "env_prefix": "APCORE_OBSERVABILITY", "has_schema": False}, ...]
 ```
 
 ```typescript
 // TypeScript
 const namespaces = Config.registeredNamespaces();
-// [{ name: 'observability', envPrefix: 'APCORE__OBSERVABILITY', hasSchema: false }, ...]
+// [{ name: 'observability', envPrefix: 'APCORE_OBSERVABILITY', hasSchema: false }, ...]
 ```
 
 ## Key Files