apcore-js 0.14.1 → 0.15.0

package/README.md

@@ -4,6 +4,10 @@
 
 # apcore
 
+[![TypeScript](https://img.shields.io/badge/TypeScript-Node_18+-blue.svg)](https://github.com/aiperceivable/apcore-typescript)
+[![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](https://opensource.org/licenses/Apache-2.0)
+[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/12294/badge)](https://www.bestpractices.dev/projects/12294)
+
 **AI-Perceivable Core**
 
 > **Build once, invoke by Code or AI.**
@@ -24,6 +28,7 @@ apcore is an AI-Perceivable module standard that makes every interface naturally
 - **Observability** — Tracing (spans + exporters), metrics (counters + histograms + Prometheus export), structured logging with redaction
 - **Schema export** — JSON/YAML schema export with strict and compact modes
 - **Caching & pagination annotations** — `cacheable`, `cacheTtl`, `cacheKeyFields` for result caching; `paginated`, `paginationStyle` for paginated modules
+- **Config Bus** — Namespace-based configuration registry with typed access, env prefix dispatch, hot-reload, and external config mounting (`Config.registerNamespace()`, `config.namespace()`, `config.bind<T>()`, `config.mount()`)
 
 ## Documentation
 
@@ -100,11 +105,141 @@ const result = await executor.call('example.greet', { name: 'World' });
 | `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, namespace bus, get/set/bind values |
 | `ACL` | Access control — rule-based caller/target authorization |
 | `Middleware` | Pipeline hooks — before/after/onError interception |
 | `EventEmitter` | Event system — subscribe, emit, flush |
 
+## Configuration
+
+### Config Bus
+
+`Config` acts as an ecosystem-level Config Bus. Any package can register a namespace with optional JSON Schema validation, environment variable prefix, and defaults.
+
+```typescript
+import { Config } from 'apcore-js';
+
+// Register a namespace (class-level, shared across all Config instances)
+Config.registerNamespace('myPlugin', {
+  envPrefix: 'MY_PLUGIN',
+  defaults: { timeout: 5000, retries: 3 },
+  schema: {
+    type: 'object',
+    properties: {
+      timeout: { type: 'number' },
+      retries: { type: 'number' },
+    },
+  },
+});
+
+const config = Config.load('apcore.yaml');
+
+// Dot-path access with namespace resolution
+const timeout = config.get('myPlugin.timeout');   // 5000 (or env override)
+
+// Full namespace subtree
+const pluginConfig = config.namespace('myPlugin');
+
+// Typed access — pass a class constructor; its constructor receives the namespace dict
+class MyPluginConfig {
+  timeout: number;
+  retries: number;
+  constructor(data: Record<string, unknown>) {
+    this.timeout = (data['timeout'] as number) ?? 5000;
+    this.retries = (data['retries'] as number) ?? 3;
+  }
+}
+const typed = config.bind('myPlugin', MyPluginConfig);
+
+// Mount an external config source (e.g. an existing config file)
+config.mount('myPlugin', { fromFile: './my-plugin.yaml' });
+// Or from an in-memory object:
+config.mount('myPlugin', { fromDict: { timeout: 10000 } });
+
+// Introspect registered namespaces
+const names = Config.registeredNamespaces(); // string[]
+```
+
+### Environment Variable Overrides
+
+Merge priority (highest wins): **environment variables > config file > namespace defaults**.
+
+Two prefix conventions are supported:
+
+| Convention | Applies to | Example |
+|------------|------------|---------|
+| `APCORE_` + `KEY_PATH` (single `_` → `.`) | Legacy flat keys | `APCORE_EXECUTOR_DEFAULT_TIMEOUT=5000` |
+| `APCORE__` + namespace prefix (double `__`) | apcore sub-package namespaces | `APCORE__OBSERVABILITY_TRACING_ENABLED=true` |
+
+apcore pre-registers the following namespaces and env prefixes:
+
+| Namespace | Env prefix | Wraps |
+|-----------|-----------|-------|
+| `observability` | `APCORE__OBSERVABILITY` | `apcore.observability.*` keys |
+| `sysModules` | `APCORE__SYS` | `apcore.sys_modules.*` keys |
+
+Third-party packages should use their own prefix (e.g. `APCORE__MCP` for apcore-mcp) to avoid collisions.
+
+### Hot Reload
+
+`config.reload()` re-reads the source YAML, re-detects legacy/namespace mode, re-applies all namespace defaults and env overrides, re-validates, and re-reads any mounted files.
+
+```typescript
+const config = Config.load('apcore.yaml');
+// ... runtime config change on disk ...
+config.reload(); // picks up all changes
+```
+
+### YAML File Format
+
+Configuration files support two modes. **Legacy mode** (no `apcore:` key) is fully backward compatible. **Namespace mode** is activated when an `apcore:` top-level key is present; each namespace occupies its own top-level section. The `_config` reserved namespace controls validation behavior.
+
+```yaml
+# Namespace mode
+apcore:
+  version: "0.15.0"
+
+_config:
+  strict: true
+
+observability:
+  tracing:
+    enabled: true
+    samplingRate: 1.0
+
+myPlugin:
+  timeout: 10000
+  retries: 5
+```
+
+### Error Codes
+
+New error codes added in v0.15.0:
+
+| Code | Description |
+|------|-------------|
+| `CONFIG_NAMESPACE_DUPLICATE` | `Config.registerNamespace()` called with an already-registered name |
+| `CONFIG_NAMESPACE_RESERVED` | `Config.registerNamespace()` called with a reserved name (e.g. `_config`) |
+| `CONFIG_ENV_PREFIX_CONFLICT` | Two namespaces declare the same `envPrefix` |
+| `CONFIG_MOUNT_ERROR` | `config.mount()` cannot read or parse the external source |
+| `CONFIG_BIND_ERROR` | `config.bind<T>()` or `config.getTyped<T>()` type guard fails |
+| `ERROR_FORMATTER_DUPLICATE` | `ErrorFormatterRegistry.register()` called for an already-registered surface |
+
+### Event Type Canonical Names
+
+apcore 0.15.0 resolves two event-type collisions. Canonical dot-namespaced names should be used in new code; legacy short-form names remain emitted as aliases during the transition period.
+
+| Legacy name (alias) | Canonical name | Meaning |
+|---------------------|----------------|---------|
+| `"module_health_changed"` | `"apcore.module.toggled"` | Module enabled/disabled toggle |
+| `"module_health_changed"` | `"apcore.health.recovered"` | Error-rate recovery after spike |
+| `"config_changed"` | `"apcore.config.updated"` | Config key updated at runtime |
+| `"config_changed"` | `"apcore.module.reloaded"` | Module reloaded from disk |
+
+Naming convention: `apcore.*` is reserved for core events. Adapter packages use their own prefix (`apcore-mcp.*`, `apcore-a2a.*`, `apcore-cli.*`).
+
+---
+
 ## Examples
 
 The `examples/` directory contains runnable demos:

package/dist/config.d.ts

@@ -1,21 +1,60 @@
 /**
  * Configuration loading, validation, and environment variable overrides (Algorithm A12).
+ * Supports legacy mode (flat YAML) and namespace mode (apcore top-level key).
  */
+/**
+ * Search for a config file in the standard discovery order (§9.14).
+ * Returns the path of the first found file, or null if none found.
+ */
+export declare function discoverConfigFile(): string | null;
 /**
  * Configuration system with YAML loading, env overrides, and validation.
  *
- * Merge priority (highest wins): environment variables > config file > defaults.
+ * Merge priority (highest wins): environment variables > mount data > config file > namespace defaults > defaults.
+ *
+ * Two modes:
+ * - Legacy mode: top-level YAML has no "apcore" key. Backward compatible.
+ * - Namespace mode: top-level YAML has "apcore" key. Enables namespace features.
  *
  * Backward compatible: `new Config(data)` still works for in-memory configuration.
  */
 export declare class Config {
     private _data;
     private _yamlPath;
+    private _mode;
+    private _mounts;
     constructor(data?: Record<string, unknown>);
+    /**
+     * Register a namespace globally.
+     *
+     * Throws:
+     * - ConfigNamespaceReservedError if name is in the reserved set.
+     * - ConfigNamespaceDuplicateError if name is already registered.
+     * - ConfigEnvPrefixConflictError if envPrefix is already used or matches the
+     *   APCORE_[A-Z0-9] pattern.
+     */
+    static registerNamespace(options: {
+        name: string;
+        schema?: object | string | null;
+        envPrefix?: string | null;
+        defaults?: Record<string, unknown> | null;
+    }): void;
+    /**
+     * Return a snapshot of all registered namespaces.
+     */
+    static registeredNamespaces(): Array<{
+        name: string;
+        envPrefix: string | null;
+        hasSchema: boolean;
+    }>;
     /**
      * Load configuration from a YAML file with env overrides.
+     *
+     * Auto-detects mode:
+     * - Namespace mode: top-level "apcore" key present.
+     * - Legacy mode: otherwise (backward compatible).
      */
-    static load(yamlPath: string, options?: {
+    static load(yamlPath?: string, options?: {
         validate?: boolean;
     }): Config;
     /** Create a Config from default values with env overrides applied. */
@@ -26,16 +65,48 @@ export declare class Config {
     set(key: string, value: unknown): void;
     /** Return a deep copy of the raw config data. */
     get data(): Record<string, unknown>;
+    /** Return the detected mode: 'legacy' or 'namespace'. */
+    get mode(): 'legacy' | 'namespace';
+    /**
+     * Attach external config data to a namespace.
+     *
+     * Exactly one of fromFile or fromDict must be provided.
+     * Throws ConfigMountError if namespace is "_config" or file not found.
+     */
+    mount(namespace: string, options: {
+        fromFile?: string;
+        fromDict?: Record<string, unknown>;
+    }): void;
+    /**
+     * Return a deep copy of a namespace subtree.
+     */
+    namespace(name: string): Record<string, unknown>;
+    /**
+     * Typed get with coercion and validation.
+     * Applies the coerce function to the raw value and returns the result.
+     * Throws ConfigError if the raw value is undefined.
+     */
+    getTyped<T>(path: string, coerce: (v: unknown) => T): T;
+    /**
+     * Deserialize a namespace subtree into a class instance.
+     * The schema constructor receives the namespace data as a plain object.
+     * Throws ConfigBindError if instantiation fails.
+     */
+    bind<T>(namespace: string, schema: new (data: Record<string, unknown>) => T): T;
     /**
      * Validate the configuration per Algorithm A12.
      *
-     * Checks required fields, type constraints, and semantic rules.
+     * In legacy mode: checks required fields, type constraints, and semantic rules.
+     * In namespace mode (A12-NS): validates data.apcore; throws on unknown namespaces
+     * if strict mode is enabled via data._config.strict.
      * Collects all errors before raising.
      */
     validate(): void;
+    private _validateNamespaceMode;
     /**
      * Re-read configuration from the original YAML file.
      * Only works if the Config was created via Config.load().
+     * In namespace mode, re-applies namespace defaults, env overrides, and mount data.
      */
     reload(): void;
 }

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAsKH;;;;;;GAMG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,SAAS,CAAuB;gBAE5B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAI1C;;OAEG;IACH,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,MAAM;IAoCvE,sEAAsE;IACtE,MAAM,CAAC,YAAY,IAAI,MAAM;IAK7B,iDAAiD;IACjD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,OAAO,GAAG,OAAO;IAIjD,iDAAiD;IACjD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAItC,iDAAiD;IACjD,IAAI,IAAI,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAElC;IAED;;;;;OAKG;IACH,QAAQ,IAAI,IAAI;IA2BhB;;;OAGG;IACH,MAAM,IAAI,IAAI;CAOf"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAiRH;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,MAAM,GAAG,IAAI,CA2BlD;AAMD;;;;;;;;;;GAUG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,KAAK,CAAoC;IACjD,OAAO,CAAC,OAAO,CAAmD;gBAEtD,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAQ1C;;;;;;;;OAQG;IACH,MAAM,CAAC,iBAAiB,CAAC,OAAO,EAAE;QAChC,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;QAChC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC1B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;KAC3C,GAAG,IAAI;IAqBR;;OAEG;IACH,MAAM,CAAC,oBAAoB,IAAI,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;QAAC,SAAS,EAAE,OAAO,CAAA;KAAE,CAAC;IAYpG;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,MAAM;IA4ExE,sEAAsE;IACtE,MAAM,CAAC,YAAY,IAAI,MAAM;IAS7B,iDAAiD;IACjD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,OAAO,GAAG,OAAO;IAYjD,iDAAiD;IACjD,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI;IAoBtC,iDAAiD;IACjD,IAAI,IAAI,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAElC;IAED,yDAAyD;IACzD,IAAI,IAAI,IAAI,QAAQ,GAAG,WAAW,CAEjC;IAED;;;;;OAKG;IACH,KAAK,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,GAAG,IAAI;IAmDlG;;OAEG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAQhD;;;;OAIG;IACH,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,CAAC,GAAG,CAAC;IAQvD;;;;OAIG;IACH,IAAI,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC;IAS/E;;;;;;;OAOG;IACH,QAAQ,IAAI,IAAI;IAgChB,OAAO,CAAC,sBAAsB;IAuC9B;;;;OAIG;IACH,MAAM,IAAI,IAAI;CAoBf"}