feat: implement config discovery logic and add comprehensive error handling for configuration and registry operations

Signed-off-by: tercel <[email protected]>

Author: tercel

.githooks/prepare-commit-msg

@@ -0,0 +1,9 @@
+#!/bin/sh
+# Automatically add Signed-off-by line (DCO) if not already present
+
+SOB=$(git var GIT_COMMITTER_IDENT | sed -n 's/^\(.*>\).*$/Signed-off-by: \1/p')
+
+if ! grep -qs "^$SOB" "$1"; then
+  echo "" >> "$1"
+  echo "$SOB" >> "$1"
+fi

CHANGELOG.md

@@ -5,6 +5,43 @@ 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.0] - 2026-03-30
+
+### Added
+
+#### Config Bus Architecture (§9.4–§9.14)
+- **`Config.register_namespace(name, schema=None, env_prefix=None, defaults=None)`** — Class-level namespace registration. Any package can claim a named config subtree with optional JSON Schema validation, env prefix, and default values. Global registry is shared across all `Config` instances. Late registration is allowed; call `config.reload()` afterward to apply defaults and env overrides.
+- **`config.get("namespace.key.path")`** — Dot-path access with namespace resolution. First segment resolves to a registered namespace; remaining segments traverse the subtree.
+- **`config.namespace(name)`** — Returns the full config subtree for a registered namespace as a dict.
+- **`config.bind(ns, type)` / `config.get_typed(path, type)`** — Typed namespace access; `bind` returns a view of the namespace deserialized into `type`, `get_typed` deserializes a single dot-path value.
+- **`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.
+- **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`
+
+#### Error Formatter Registry (§8.8)
+- **`ErrorFormatter` protocol** — Interface for adapter-specific error formatters. Implementations transform `ModuleError` into the surface-specific wire format (e.g., MCP camelCase, JSON-RPC code mapping).
+- **`ErrorFormatterRegistry`** — Shared registry for surface-specific formatters:
+  - `ErrorFormatterRegistry.register(surface, formatter)` — register a formatter for a named surface
+  - `ErrorFormatterRegistry.get(surface)` — retrieve a registered formatter
+  - `ErrorFormatterRegistry.format(surface, error)` — format an error, falling back to `error.to_dict()` if no formatter is registered for that surface
+- **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.
+
+#### Event Type Naming Convention and Collision Fix (§9.16)
+- **Canonical event names** — Two confirmed event type collisions in apcore-python are resolved:
+  - `"module_health_changed"` (previously used for both enable/disable toggles and error-rate recovery) split into `apcore.module.toggled` (toggle on/off) and `apcore.health.recovered` (error rate recovery)
+  - `"config_changed"` (previously used for both key updates and module reload) split into `apcore.config.updated` (runtime key update via `system.control.update_config`) and `apcore.module.reloaded` (hot-reload via `system.control.reload_module`)
+- **Naming convention** — `apcore.*` is reserved for core framework events. Adapter packages use their own prefix: `apcore-mcp.*`, `apcore-a2a.*`, `apcore-cli.*`.
+- **Transition aliases** — All four legacy short-form names (`module_health_changed`, `config_changed`) continue to be emitted alongside the canonical names during the transition period.
+
+---
+
 ## [0.14.0] - 2026-03-24
 
 ### Added

README.md

@@ -6,6 +6,7 @@
 
 ![Python](https://img.shields.io/badge/python-3.11+-blue.svg)
 ![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/12294/badge)](https://www.bestpractices.dev/projects/12294)
 
 > **Build once, invoke by Code or AI.**
 
@@ -40,7 +41,7 @@ A schema-enforced module standard for the AI-Perceivable era.
 | `Registry` | Module storage -- discover, register, get, list, watch |
 | `Executor` | Execution engine -- call with middleware pipeline, ACL, approval |
 | `Context` | Request context -- trace ID, identity, call chain, cancel token |
-| `Config` | Configuration -- load from YAML, get/set values |
+| `Config` | Configuration -- load from YAML, get/set values, namespace-partitioned Config Bus |
 | `Identity` | Caller identity -- id, type, roles, attributes |
 | `FunctionModule` | Wrapped function module created by `@module` decorator |
 
@@ -99,6 +100,84 @@ A schema-enforced module standard for the AI-Perceivable era.
 | `CancelToken` | Cooperative cancellation token |
 | `BindingLoader` | Load modules from YAML binding files |
 | `ErrorCodeRegistry` | Central registry for structured error codes |
+| `ErrorFormatterRegistry` | Surface-specific error formatter registry (MCP, A2A, CLI adapters) |
+
+## Configuration
+
+### Config Bus and Namespace Registration
+
+`Config` doubles as an ecosystem-level Config Bus. Any package can register a named namespace with optional JSON Schema validation, env prefix, and default values:
+
+```python
+from apcore import Config
+
+# Register a namespace (class-level, shared across all Config instances)
+Config.register_namespace(
+    "my_plugin",
+    schema={"type": "object", "properties": {"timeout_ms": {"type": "integer"}}},
+    env_prefix="MY_PLUGIN__",
+    defaults={"timeout_ms": 5000},
+)
+
+# Load config as usual
+config = Config.load("project.yaml")
+
+# Namespace-aware access
+timeout = config.get("my_plugin.timeout_ms")   # dot-path with namespace resolution
+subtree = config.namespace("my_plugin")          # full subtree as dict
+
+# Typed access
+config.get_typed("my_plugin.timeout_ms", int)
+
+# Mount an external source (no unified YAML required)
+config.mount("my_plugin", from_dict={"timeout_ms": 3000})
+
+# Introspect registered namespaces
+names = Config.registered_namespaces()
+```
+
+### Built-in Namespaces
+
+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 |
+
+### 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` |
+| 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 `_`.
+
+### New Error Codes (0.15.0)
+
+| Code | Meaning |
+|------|---------|
+| `CONFIG_NAMESPACE_DUPLICATE` | A namespace with this name is already registered |
+| `CONFIG_NAMESPACE_RESERVED` | The namespace name is reserved (`_config`, `apcore`) |
+| `CONFIG_ENV_PREFIX_CONFLICT` | Two namespaces share the same env prefix |
+| `CONFIG_MOUNT_ERROR` | Failed to load or parse a mounted config source |
+| `CONFIG_BIND_ERROR` | Failed to deserialize a namespace subtree into the requested type |
+| `ERROR_FORMATTER_DUPLICATE` | A formatter for this surface is already registered |
+
+### Event Type Names
+
+Canonical event type names use dot-namespaced identifiers. `apcore.*` is reserved for core framework events; adapter packages use their own prefix (e.g., `apcore-mcp.*`).
+
+| Canonical name | Replaces | Emitted by |
+|---------------|---------|-----------|
+| `apcore.module.toggled` | `module_health_changed` | `system.control.toggle_feature` |
+| `apcore.health.recovered` | `module_health_changed` | `PlatformNotifyMiddleware` (error rate recovery) |
+| `apcore.config.updated` | `config_changed` | `system.control.update_config` |
+| `apcore.module.reloaded` | `config_changed` | `system.control.reload_module` |
+
+The legacy short-form names are still emitted alongside the canonical names during the transition period.
 
 ## Documentation
 

examples/global_client.py

@@ -1,10 +1,12 @@
 import apcore
 
+
 # 1. No need to initialize anything if using the default global client
 @apcore.module(id="math.add")
 def add(a: int, b: int) -> int:
     return a + b
 
+
 if __name__ == "__main__":
     # 2. Call directly via apcore.call
     result = apcore.call("math.add", {"a": 10, "b": 5})

examples/simple_client.py

@@ -3,12 +3,14 @@
 # 1. Initialize the simplified client
 client = APCore()
 
+
 # 2. Define a module using the client's decorator (auto-registers to client.registry)
 @client.module(id="math.add", description="Add two integers")
 def add(a: int, b: int) -> int:
     """Adds two numbers."""
     return a + b
 
+
 # 3. Call the module directly through the client
 if __name__ == "__main__":
     # Sync call

src/apcore/__init__.py

@@ -42,7 +42,10 @@
 )
 
 # Config
-from apcore.config import Config
+from apcore.config import Config, discover_config_file
+
+# Error Formatter
+from apcore.error_formatter import ErrorFormatter, ErrorFormatterRegistry
 
 # Errors
 from apcore.errors import (
@@ -62,12 +65,18 @@
     CallFrequencyExceededError,
     CircularCallError,
     CircularDependencyError,
+    ConfigBindError,
+    ConfigEnvPrefixConflictError,
     ConfigError,
+    ConfigMountError,
+    ConfigNamespaceDuplicateError,
+    ConfigNamespaceReservedError,
     ConfigNotFoundError,
     DependencyNotFoundError,
     ErrorCodeCollisionError,
     ErrorCodeRegistry,
     ErrorCodes,
+    ErrorFormatterDuplicateError,
     FeatureNotImplementedError,
     FuncMissingReturnTypeError,
     FuncMissingTypeHintError,
@@ -352,6 +361,10 @@ def enable(module_id: str, reason: str = "Enabled via APCore client") -> dict[st
     "DependencyInfo",
     # Config
     "Config",
+    "discover_config_file",
+    # Error Formatter
+    "ErrorFormatter",
+    "ErrorFormatterRegistry",
     # Registry constants
     "REGISTRY_EVENTS",
     "MODULE_ID_PATTERN",
@@ -379,9 +392,15 @@ def enable(module_id: str, reason: str = "Enabled via APCore client") -> dict[st
     "CallFrequencyExceededError",
     "CircularCallError",
     "CircularDependencyError",
+    "ConfigBindError",
+    "ConfigEnvPrefixConflictError",
     "ConfigError",
+    "ConfigMountError",
+    "ConfigNamespaceDuplicateError",
+    "ConfigNamespaceReservedError",
     "ConfigNotFoundError",
     "DependencyNotFoundError",
+    "ErrorFormatterDuplicateError",
     "ErrorCodeCollisionError",
     "ErrorCodeRegistry",
     "FeatureNotImplementedError",

src/apcore/error_formatter.py

@@ -0,0 +1,82 @@
+"""ErrorFormatterRegistry -- per-adapter error formatting (§8.8)."""
+
+from __future__ import annotations
+
+import threading
+from typing import Any, Protocol, runtime_checkable
+
+from apcore.errors import ErrorFormatterDuplicateError, ModuleError
+
+__all__ = ["ErrorFormatter", "ErrorFormatterRegistry"]
+
+
+@runtime_checkable
+class ErrorFormatter(Protocol):
+    """Protocol for adapter-specific error formatters."""
+
+    def format(self, error: ModuleError, context: object) -> dict[str, Any]:
+        """Format a ModuleError into an adapter-specific dict."""
+        ...
+
+
+class ErrorFormatterRegistry:
+    """Registry of per-adapter error formatters (§8.8).
+
+    Thread-safe: all mutations are internally synchronized.
+    """
+
+    _registry: dict[str, ErrorFormatter] = {}
+    _lock: threading.Lock = threading.Lock()
+
+    @classmethod
+    def register(cls, adapter_name: str, formatter: ErrorFormatter) -> None:
+        """Register a formatter for the given adapter name.
+
+        Args:
+            adapter_name: Unique adapter identifier (e.g. "mcp", "http").
+            formatter: An object implementing the ErrorFormatter protocol.
+
+        Raises:
+            ErrorFormatterDuplicateError: If a formatter is already registered
+                for ``adapter_name``.
+        """
+        with cls._lock:
+            if adapter_name in cls._registry:
+                raise ErrorFormatterDuplicateError(adapter_name=adapter_name)
+            cls._registry[adapter_name] = formatter
+
+    @classmethod
+    def get(cls, adapter_name: str) -> ErrorFormatter | None:
+        """Return the registered formatter for ``adapter_name``, or None."""
+        with cls._lock:
+            return cls._registry.get(adapter_name)
+
+    @classmethod
+    def format(
+        cls,
+        adapter_name: str,
+        error: ModuleError,
+        context: object = None,
+    ) -> dict[str, Any]:
+        """Format ``error`` using the registered formatter for ``adapter_name``.
+
+        Falls back to ``error.to_dict()`` if no formatter is registered.
+
+        Args:
+            adapter_name: The adapter whose formatter to use.
+            error: The ModuleError to format.
+            context: Optional adapter-specific context object.
+
+        Returns:
+            A dict representation of the error.
+        """
+        formatter = cls.get(adapter_name)
+        if formatter is None:
+            return error.to_dict()
+        return formatter.format(error, context)
+
+    @classmethod
+    def _reset(cls) -> None:
+        """Clear all registrations (for testing only)."""
+        with cls._lock:
+            cls._registry.clear()