apcore-js 0.7.1 → 0.9.0

package/README.md

@@ -1,5 +1,5 @@
 <div align="center">
-  <img src="https://raw.githubusercontent.com/aipartnerup/apcore-typescript/main/apcore-logo.svg" alt="apcore logo" width="200"/>
+  <img src="https://raw.githubusercontent.com/aipartnerup/apcore/main/apcore-logo.svg" alt="apcore logo" width="200"/>
 </div>
 
 # apcore
@@ -20,6 +20,11 @@ apcore provides a unified task orchestration framework with schema validation, a
 - **Observability** — Tracing (spans + exporters), metrics (counters + histograms + Prometheus export), structured logging with redaction
 - **Schema export** — JSON/YAML schema export with strict and compact modes
 
+## Documentation
+
+For full documentation, including Quick Start guides for both Python and TypeScript, visit:
+**[https://aipartnerup.github.io/apcore/getting-started.html](https://aipartnerup.github.io/apcore/getting-started.html)**
+
 ## Requirements
 
 - Node.js >= 18.0.0
@@ -65,10 +70,14 @@ src/
   config.ts             # Dot-path configuration accessor
   acl.ts                # Access control with pattern matching
   approval.ts           # Pluggable approval gate (handlers, request/result types)
+  async-task.ts         # Async task manager
+  cancel.ts             # Cancellation token support
   decorator.ts          # FunctionModule class and helpers
   bindings.ts           # YAML binding loader
-  errors.ts             # Error hierarchy (20+ typed errors)
+  errors.ts             # Error hierarchy (30+ typed errors)
+  extensions.ts         # Extension manager
   module.ts             # Module types and annotations
+  trace-context.ts     # W3C trace context (inject/extract)
   middleware/
     base.ts             # Middleware base class
     manager.ts          # MiddlewareManager (onion model)

package/dist/acl.d.ts

@@ -9,14 +9,31 @@ export interface ACLRule {
     description: string;
     conditions?: Record<string, unknown> | null;
 }
+/** Structured record of an ACL check decision. */
+export interface AuditEntry {
+    readonly timestamp: string;
+    readonly callerId: string;
+    readonly targetId: string;
+    readonly decision: string;
+    readonly reason: string;
+    readonly matchedRule: string | null;
+    readonly matchedRuleIndex: number | null;
+    readonly identityType: string | null;
+    readonly roles: readonly string[];
+    readonly callDepth: number | null;
+    readonly traceId: string | null;
+}
+export type AuditLogger = (entry: AuditEntry) => void;
 export declare class ACL {
     private _rules;
     private _defaultEffect;
     private _yamlPath;
+    private _auditLogger;
     debug: boolean;
-    constructor(rules: ACLRule[], defaultEffect?: string);
+    constructor(rules: ACLRule[], defaultEffect?: string, auditLogger?: AuditLogger | null);
     static load(yamlPath: string): ACL;
     check(callerId: string | null, targetId: string, context?: Context | null): boolean;
+    private _buildAuditEntry;
     private _matchPattern;
     private _matchesRule;
     private _checkConditions;

package/dist/acl.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"acl.d.ts","sourceRoot":"","sources":["../src/acl.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAQ5C,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC7C;AAsCD,qBAAa,GAAG;IACd,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,SAAS,CAAuB;IACxC,KAAK,EAAE,OAAO,CAAS;gBAEX,KAAK,EAAE,OAAO,EAAE,EAAE,aAAa,GAAE,MAAe;IAQ5D,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,GAAG;IAqClC,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO;IAYnF,OAAO,CAAC,aAAa;IAQrB,OAAO,CAAC,YAAY;IAcpB,OAAO,CAAC,gBAAgB;IAmCxB,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;IAI5B,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO;IAczD,MAAM,IAAI,IAAI;CAQf"}
+{"version":3,"file":"acl.d.ts","sourceRoot":"","sources":["../src/acl.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAQ5C,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC7C;AAED,kDAAkD;AAClD,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACjC;AAED,MAAM,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;AAsCtD,qBAAa,GAAG;IACd,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,YAAY,CAA4B;IAChD,KAAK,EAAE,OAAO,CAAS;gBAEX,KAAK,EAAE,OAAO,EAAE,EAAE,aAAa,GAAE,MAAe,EAAE,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI;IAS9F,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,GAAG;IAqClC,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO;IA6BnF,OAAO,CAAC,gBAAgB;IAsCxB,OAAO,CAAC,aAAa;IAQrB,OAAO,CAAC,YAAY;IAcpB,OAAO,CAAC,gBAAgB;IAmCxB,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;IAI5B,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO;IAczD,MAAM,IAAI,IAAI;CASf"}

package/dist/acl.js

@@ -44,13 +44,15 @@ export class ACL {
     _rules;
     _defaultEffect;
     _yamlPath = null;
+    _auditLogger = null;
     debug = false;
-    constructor(rules, defaultEffect = 'deny') {
+    constructor(rules, defaultEffect = 'deny', auditLogger) {
         if (defaultEffect !== 'allow' && defaultEffect !== 'deny') {
             throw new ACLRuleError(`Invalid default_effect '${defaultEffect}', must be 'allow' or 'deny'`);
         }
         this._rules = [...rules];
         this._defaultEffect = defaultEffect;
+        this._auditLogger = auditLogger ?? null;
     }
     static load(yamlPath) {
         const { existsSync, readFileSync } = _nodeFs;
@@ -86,12 +88,50 @@ export class ACL {
     }
     check(callerId, targetId, context) {
         const effectiveCaller = callerId === null ? '@external' : callerId;
-        for (const rule of this._rules) {
-            if (this._matchesRule(rule, effectiveCaller, targetId, context ?? null)) {
-                return rule.effect === 'allow';
+        const ctx = context ?? null;
+        for (let idx = 0; idx < this._rules.length; idx++) {
+            const rule = this._rules[idx];
+            if (this._matchesRule(rule, effectiveCaller, targetId, ctx)) {
+                const decision = rule.effect === 'allow';
+                if (this._auditLogger) {
+                    this._auditLogger(this._buildAuditEntry(effectiveCaller, targetId, decision ? 'allow' : 'deny', 'rule_match', rule, idx, ctx));
+                }
+                return decision;
             }
         }
-        return this._defaultEffect === 'allow';
+        const defaultDecision = this._defaultEffect === 'allow';
+        if (this._auditLogger) {
+            const reason = this._rules.length === 0 ? 'no_rules' : 'default_effect';
+            this._auditLogger(this._buildAuditEntry(effectiveCaller, targetId, defaultDecision ? 'allow' : 'deny', reason, null, null, ctx));
+        }
+        return defaultDecision;
+    }
+    _buildAuditEntry(callerId, targetId, decision, reason, matchedRule, matchedRuleIndex, context) {
+        let identityType = null;
+        let roles = [];
+        let callDepth = null;
+        let traceId = null;
+        if (context !== null) {
+            traceId = context.traceId;
+            callDepth = context.callChain.length;
+            if (context.identity !== null) {
+                identityType = context.identity.type;
+                roles = context.identity.roles;
+            }
+        }
+        return {
+            timestamp: new Date().toISOString(),
+            callerId,
+            targetId,
+            decision,
+            reason,
+            matchedRule: matchedRule?.description ?? null,
+            matchedRuleIndex,
+            identityType,
+            roles,
+            callDepth,
+            traceId,
+        };
     }
     _matchPattern(pattern, value, context) {
         if (pattern === '@external')
@@ -170,6 +210,7 @@ export class ACL {
         const reloaded = ACL.load(this._yamlPath);
         this._rules = reloaded._rules;
         this._defaultEffect = reloaded._defaultEffect;
+        // Preserve auditLogger — reload only refreshes rules and default effect
     }
 }
 //# sourceMappingURL=acl.js.map

package/dist/acl.js.map

@@ -1 +1 @@
-{"version":3,"file":"acl.js","sourceRoot":"","sources":["../src/acl.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"acl.js","sourceRoot":"","sources":["../src/acl.ts"],"names":[],"mappings":"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"}

package/dist/config.d.ts

@@ -1,9 +1,42 @@
 /**
- * Configuration accessor with dot-path key support.
+ * Configuration loading, validation, and environment variable overrides (Algorithm A12).
+ */
+/**
+ * Configuration system with YAML loading, env overrides, and validation.
+ *
+ * Merge priority (highest wins): environment variables > config file > defaults.
+ *
+ * Backward compatible: `new Config(data)` still works for in-memory configuration.
  */
 export declare class Config {
     private _data;
+    private _yamlPath;
     constructor(data?: Record<string, unknown>);
+    /**
+     * Load configuration from a YAML file with env overrides.
+     */
+    static load(yamlPath: string, options?: {
+        validate?: boolean;
+    }): Config;
+    /** Create a Config from default values with env overrides applied. */
+    static fromDefaults(): Config;
+    /** Get a configuration value by dot-path key. */
     get(key: string, defaultValue?: unknown): unknown;
+    /** Set a configuration value by dot-path key. */
+    set(key: string, value: unknown): void;
+    /** Return a deep copy of the raw config data. */
+    get data(): Record<string, unknown>;
+    /**
+     * Validate the configuration per Algorithm A12.
+     *
+     * Checks required fields, type constraints, and semantic rules.
+     * Collects all errors before raising.
+     */
+    validate(): void;
+    /**
+     * Re-read configuration from the original YAML file.
+     * Only works if the Config was created via Config.load().
+     */
+    reload(): void;
 }
 //# sourceMappingURL=config.d.ts.map

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,qBAAa,MAAM;IACjB,OAAO,CAAC,KAAK,CAA0B;gBAE3B,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAI1C,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,OAAO,GAAG,OAAO;CAYlD"}
+{"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"}

package/dist/config.js

@@ -1,23 +1,265 @@
 /**
- * Configuration accessor with dot-path key support.
+ * Configuration loading, validation, and environment variable overrides (Algorithm A12).
+ */
+import yaml from 'js-yaml';
+import { ConfigError, ConfigNotFoundError } from './errors.js';
+// Lazy-load Node.js built-in modules for browser compatibility
+let _nodeFs = null;
+try {
+    _nodeFs = await import('node:fs');
+}
+catch { /* browser environment */ }
+let _nodeProcess = null;
+try {
+    _nodeProcess = await import('node:process');
+}
+catch { /* browser environment */ }
+/** Environment variable prefix for overrides. */
+const ENV_PREFIX = 'APCORE_';
+/** Required configuration fields (dot-paths). */
+const REQUIRED_FIELDS = [
+    'version',
+    'extensions.root',
+    'schema.root',
+    'acl.root',
+    'acl.default_effect',
+    'project.name',
+];
+/** Field constraints: field -> [validator, errorMessage]. */
+const CONSTRAINTS = {
+    'acl.default_effect': [
+        (v) => v === 'allow' || v === 'deny',
+        "must be 'allow' or 'deny'",
+    ],
+    'observability.tracing.sampling_rate': [
+        (v) => typeof v === 'number' && v >= 0.0 && v <= 1.0,
+        'must be a number in [0.0, 1.0]',
+    ],
+    'extensions.max_depth': [
+        (v) => typeof v === 'number' && Number.isInteger(v) && v >= 1 && v <= 16,
+        'must be an integer in [1, 16]',
+    ],
+    'executor.default_timeout': [
+        (v) => typeof v === 'number' && Number.isInteger(v) && v >= 0,
+        'must be a non-negative integer (milliseconds)',
+    ],
+    'executor.global_timeout': [
+        (v) => typeof v === 'number' && Number.isInteger(v) && v >= 0,
+        'must be a non-negative integer (milliseconds)',
+    ],
+    'executor.max_call_depth': [
+        (v) => typeof v === 'number' && Number.isInteger(v) && v >= 1,
+        'must be a positive integer',
+    ],
+    'executor.max_module_repeat': [
+        (v) => typeof v === 'number' && Number.isInteger(v) && v >= 1,
+        'must be a positive integer',
+    ],
+};
+/** Default configuration values. */
+const DEFAULTS = {
+    version: '0.8.0',
+    extensions: {
+        root: './extensions',
+        auto_discover: true,
+        max_depth: 8,
+        follow_symlinks: false,
+    },
+    schema: {
+        root: './schemas',
+        strategy: 'yaml_first',
+        max_ref_depth: 32,
+    },
+    acl: {
+        root: './acl',
+        default_effect: 'deny',
+    },
+    executor: {
+        default_timeout: 30000,
+        global_timeout: 60000,
+        max_call_depth: 32,
+        max_module_repeat: 3,
+    },
+    observability: {
+        tracing: {
+            enabled: false,
+            sampling_rate: 1.0,
+        },
+        metrics: {
+            enabled: false,
+        },
+    },
+    project: {
+        name: 'apcore',
+    },
+};
+function deepMergeDicts(base, override) {
+    const result = { ...base };
+    for (const [key, value] of Object.entries(override)) {
+        if (key in result &&
+            typeof result[key] === 'object' && result[key] !== null && !Array.isArray(result[key]) &&
+            typeof value === 'object' && value !== null && !Array.isArray(value)) {
+            result[key] = deepMergeDicts(result[key], value);
+        }
+        else {
+            result[key] = value;
+        }
+    }
+    return result;
+}
+function getNested(data, dotPath, defaultValue) {
+    const parts = dotPath.split('.');
+    let current = data;
+    for (const part of parts) {
+        if (current !== null && typeof current === 'object' && part in current) {
+            current = current[part];
+        }
+        else {
+            return defaultValue;
+        }
+    }
+    return current;
+}
+function setNested(data, dotPath, value) {
+    const parts = dotPath.split('.');
+    let current = data;
+    for (const part of parts.slice(0, -1)) {
+        if (!(part in current) || typeof current[part] !== 'object' || current[part] === null) {
+            current[part] = {};
+        }
+        current = current[part];
+    }
+    current[parts[parts.length - 1]] = value;
+}
+function coerceEnvValue(value) {
+    if (value.toLowerCase() === 'true')
+        return true;
+    if (value.toLowerCase() === 'false')
+        return false;
+    const asInt = parseInt(value, 10);
+    if (!isNaN(asInt) && String(asInt) === value)
+        return asInt;
+    const asFloat = parseFloat(value);
+    if (!isNaN(asFloat) && String(asFloat) === value)
+        return asFloat;
+    return value;
+}
+function applyEnvOverrides(data) {
+    const result = JSON.parse(JSON.stringify(data));
+    const env = _nodeProcess?.env ?? {};
+    for (const [envKey, envValue] of Object.entries(env)) {
+        if (!envKey.startsWith(ENV_PREFIX) || envValue === undefined)
+            continue;
+        const suffix = envKey.slice(ENV_PREFIX.length);
+        if (!suffix)
+            continue;
+        // Convert: single _ -> . (separator), double __ -> literal _
+        const dotPath = suffix.toLowerCase().replace(/__/g, '\x00').replace(/_/g, '.').replace(/\x00/g, '_');
+        setNested(result, dotPath, coerceEnvValue(envValue));
+    }
+    return result;
+}
+/**
+ * Configuration system with YAML loading, env overrides, and validation.
+ *
+ * Merge priority (highest wins): environment variables > config file > defaults.
+ *
+ * Backward compatible: `new Config(data)` still works for in-memory configuration.
  */
 export class Config {
     _data;
+    _yamlPath = null;
     constructor(data) {
         this._data = data ?? {};
     }
+    /**
+     * Load configuration from a YAML file with env overrides.
+     */
+    static load(yamlPath, options) {
+        const { existsSync, readFileSync } = _nodeFs;
+        if (!existsSync(yamlPath)) {
+            throw new ConfigNotFoundError(yamlPath);
+        }
+        let fileData;
+        try {
+            const content = readFileSync(yamlPath, 'utf-8');
+            fileData = yaml.load(content);
+        }
+        catch (e) {
+            if (e instanceof ConfigNotFoundError)
+                throw e;
+            throw new ConfigError(`Invalid YAML in ${yamlPath}: ${e}`);
+        }
+        if (fileData === null || fileData === undefined) {
+            fileData = {};
+        }
+        if (typeof fileData !== 'object' || Array.isArray(fileData)) {
+            throw new ConfigError(`Config file must be a mapping, got ${typeof fileData}`);
+        }
+        // Merge: defaults < file < env
+        let merged = deepMergeDicts(DEFAULTS, fileData);
+        merged = applyEnvOverrides(merged);
+        const config = new Config(merged);
+        config._yamlPath = yamlPath;
+        if (options?.validate !== false) {
+            config.validate();
+        }
+        return config;
+    }
+    /** Create a Config from default values with env overrides applied. */
+    static fromDefaults() {
+        const data = applyEnvOverrides({ ...DEFAULTS });
+        return new Config(data);
+    }
+    /** Get a configuration value by dot-path key. */
     get(key, defaultValue) {
-        const parts = key.split('.');
-        let current = this._data;
-        for (const part of parts) {
-            if (current !== null && typeof current === 'object' && part in current) {
-                current = current[part];
+        return getNested(this._data, key, defaultValue);
+    }
+    /** Set a configuration value by dot-path key. */
+    set(key, value) {
+        setNested(this._data, key, value);
+    }
+    /** Return a deep copy of the raw config data. */
+    get data() {
+        return JSON.parse(JSON.stringify(this._data));
+    }
+    /**
+     * Validate the configuration per Algorithm A12.
+     *
+     * Checks required fields, type constraints, and semantic rules.
+     * Collects all errors before raising.
+     */
+    validate() {
+        const errors = [];
+        // 1. Required field check
+        for (const field of REQUIRED_FIELDS) {
+            const value = getNested(this._data, field);
+            if (value === undefined || value === null) {
+                errors.push(`Missing required field: '${field}'`);
             }
-            else {
-                return defaultValue;
+        }
+        // 2. Constraint validation
+        for (const [field, [checkFn, errMsg]] of Object.entries(CONSTRAINTS)) {
+            const value = getNested(this._data, field);
+            if (value !== undefined && value !== null && !checkFn(value)) {
+                errors.push(`Invalid value for '${field}': ${errMsg} (got ${JSON.stringify(value)})`);
             }
         }
-        return current;
+        if (errors.length > 0) {
+            throw new ConfigError(`Configuration validation failed (${errors.length} error(s)):\n` +
+                errors.map((e) => `  - ${e}`).join('\n'));
+        }
+    }
+    /**
+     * Re-read configuration from the original YAML file.
+     * Only works if the Config was created via Config.load().
+     */
+    reload() {
+        if (this._yamlPath === null) {
+            throw new ConfigError('Cannot reload: Config was not loaded from a YAML file');
+        }
+        const reloaded = Config.load(this._yamlPath);
+        this._data = reloaded._data;
     }
 }
 //# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,OAAO,MAAM;IACT,KAAK,CAA0B;IAEvC,YAAY,IAA8B;QACxC,IAAI,CAAC,KAAK,GAAG,IAAI,IAAI,EAAE,CAAC;IAC1B,CAAC;IAED,GAAG,CAAC,GAAW,EAAE,YAAsB;QACrC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,OAAO,GAAY,IAAI,CAAC,KAAK,CAAC;QAClC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,IAAI,IAAK,OAAmC,EAAE,CAAC;gBACpG,OAAO,GAAI,OAAmC,CAAC,IAAI,CAAC,CAAC;YACvD,CAAC;iBAAM,CAAC;gBACN,OAAO,YAAY,CAAC;YACtB,CAAC;QACH,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;CACF"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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"}

package/dist/context.d.ts

@@ -1,5 +1,6 @@
 import type { CancelToken } from './cancel.js';
 import type { TraceParent } from './trace-context.js';
+import { ContextLogger } from './observability/context-logger.js';
 /**
  * Execution context, identity, and context creation.
  */
@@ -10,7 +11,7 @@ export interface Identity {
     readonly attrs: Readonly<Record<string, unknown>>;
 }
 export declare function createIdentity(id: string, type?: string, roles?: string[], attrs?: Record<string, unknown>): Identity;
-export declare class Context {
+export declare class Context<T = null> {
     readonly traceId: string;
     readonly callerId: string | null;
     readonly callChain: readonly string[];
@@ -18,8 +19,9 @@ export declare class Context {
     readonly identity: Identity | null;
     redactedInputs: Record<string, unknown> | null;
     readonly data: Record<string, unknown>;
+    readonly services: T;
     readonly cancelToken: CancelToken | null;
-    constructor(traceId: string, callerId?: string | null, callChain?: string[], executor?: unknown, identity?: Identity | null, redactedInputs?: Record<string, unknown> | null, data?: Record<string, unknown>, cancelToken?: CancelToken | null);
+    constructor(traceId: string, callerId?: string | null, callChain?: string[], executor?: unknown, identity?: Identity | null, redactedInputs?: Record<string, unknown> | null, data?: Record<string, unknown>, cancelToken?: CancelToken | null, services?: T);
     /**
      * Create a new top-level Context with a generated UUID v4 traceId.
      *
@@ -27,16 +29,11 @@ export declare class Context {
      * converted to UUID format (8-4-4-4-12) and used instead of generating
      * a new one.
      */
-    static create(executor?: unknown, identity?: Identity | null, data?: Record<string, unknown>, traceParent?: TraceParent | null): Context;
+    static create<S = null>(executor?: unknown, identity?: Identity | null, data?: Record<string, unknown>, traceParent?: TraceParent | null, services?: S): Context<S>;
     toJSON(): Record<string, unknown>;
     static fromJSON(data: Record<string, unknown>, executor?: unknown): Context;
-    get logger(): {
-        debug: (...args: unknown[]) => void;
-        info: (...args: unknown[]) => void;
-        warn: (...args: unknown[]) => void;
-        error: (...args: unknown[]) => void;
-    };
-    child(targetModuleId: string): Context;
+    get logger(): ContextLogger;
+    child(targetModuleId: string): Context<T>;
 }
 /**
  * Interface for creating Context from framework-specific requests.

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;GAEG;AAEH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACnD;AAED,wBAAgB,cAAc,CAC5B,EAAE,EAAE,MAAM,EACV,IAAI,GAAE,MAAe,EACrB,KAAK,GAAE,MAAM,EAAO,EACpB,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAClC,QAAQ,CAEV;AAED,qBAAa,OAAO;IAClB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IACnC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,QAAQ,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;gBAGvC,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,MAAM,GAAG,IAAW,EAC9B,SAAS,GAAE,MAAM,EAAO,EACxB,QAAQ,GAAE,OAAc,EACxB,QAAQ,GAAE,QAAQ,GAAG,IAAW,EAChC,cAAc,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAW,EACrD,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EAClC,WAAW,GAAE,WAAW,GAAG,IAAW;IAYxC;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,CACX,QAAQ,GAAE,OAAc,EACxB,QAAQ,GAAE,QAAQ,GAAG,IAAW,EAChC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI,GAC/B,OAAO;IAmBV,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAsBjC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO;IAmB3E,IAAI,MAAM,IAAI;QAAE,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;QAAC,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;QAAC,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;QAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;KAAE,CAQjK;IAED,KAAK,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO;CAYvC;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC;CAC1C"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAElE;;GAEG;AAEH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACnD;AAED,wBAAgB,cAAc,CAC5B,EAAE,EAAE,MAAM,EACV,IAAI,GAAE,MAAe,EACrB,KAAK,GAAE,MAAM,EAAO,EACpB,KAAK,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAClC,QAAQ,CAEV;AAED,qBAAa,OAAO,CAAC,CAAC,GAAG,IAAI;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IACnC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC/C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;IACrB,QAAQ,CAAC,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;gBAGvC,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,MAAM,GAAG,IAAW,EAC9B,SAAS,GAAE,MAAM,EAAO,EACxB,QAAQ,GAAE,OAAc,EACxB,QAAQ,GAAE,QAAQ,GAAG,IAAW,EAChC,cAAc,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAW,EACrD,IAAI,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EAClC,WAAW,GAAE,WAAW,GAAG,IAAW,EACtC,QAAQ,GAAE,CAAa;IAazB;;;;;;OAMG;IACH,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,EACpB,QAAQ,GAAE,OAAc,EACxB,QAAQ,GAAE,QAAQ,GAAG,IAAW,EAChC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,WAAW,CAAC,EAAE,WAAW,GAAG,IAAI,EAChC,QAAQ,CAAC,EAAE,CAAC,GACX,OAAO,CAAC,CAAC,CAAC;IAqBb,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAsBjC,MAAM,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,QAAQ,CAAC,EAAE,OAAO,GAAG,OAAO;IAmB3E,IAAI,MAAM,IAAI,aAAa,CAE1B;IAED,KAAK,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC;CAa1C;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC;CAC1C"}