apcore-js 0.18.0 → 0.20.0

package/README.md

@@ -20,12 +20,15 @@ apcore is an AI-Perceivable module standard that makes every interface naturally
 
 - **Schema-driven modules** — Define input/output schemas with TypeBox for runtime validation
 - **Executor pipeline** — Secured execution lifecycle: context → call chain guard → lookup → ACL → approval gate → middleware before → validation → execute → output validation → middleware after → return
-- **Registry system** — File-based module discovery with metadata, dependencies, and topological ordering
+- **Registry system** — File-based module discovery with metadata, dependencies, and topological ordering; multi-class discovery from a single file
 - **Binding loader** — YAML-based module registration for no-code integration
 - **Access control (ACL)** — Pattern-based rules with identity types, roles, and call-depth conditions
 - **Approval system** — Pluggable approval gate in the executor pipeline with sync and async (polling) flows, built-in handlers, and tracing integration
-- **Middleware** — Onion-model middleware with before/after/onError hooks and error recovery
-- **Observability** — Tracing (spans + exporters), metrics (counters + histograms + Prometheus export), structured logging with redaction
+- **Middleware** — Onion-model middleware with before/after/onError hooks and error recovery; built-in `CircuitBreakerMiddleware` (CLOSED/OPEN/HALF_OPEN) and OTel-compatible `TracingMiddleware`
+- **Observability** — Tracing (spans + `BatchSpanProcessor` + exporters), metrics (counters + histograms + Prometheus export with `/metrics`/`/healthz`/`/readyz`), structured logging with `RedactionConfig`
+- **System modules** — Built-in `system.*` modules for AI bidirectional introspection: health, manifest, usage, and runtime control (`update_config`, `reload_module`, `toggle_feature`). Audit trail via `AuditStore`, config persistence via `overridesPath`, usage metrics in Prometheus, bulk reload via `path_filter` glob
+- **Event system** — `EventEmitter` with subscriber-level `CircuitBreakerWrapper`, built-in `FileSubscriber`, `StdoutSubscriber`, `FilterSubscriber`, and pluggable custom types
+- **Async tasks** — `AsyncTaskManager` with injectable `TaskStore` (bring your own Redis/Postgres backend), `RetryConfig` with exponential backoff, and opt-in background reaper
 - **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()`)
@@ -46,6 +49,8 @@ For full documentation, including Quick Start guides and API reference, visit:
 npm install apcore-js
 ```
 
+> **Note:** The npm package is published as `apcore-js` (the `apcore` name is reserved on npm). Python uses `apcore`, Rust uses the `apcore` crate.
+
 ## Quick Start
 
 ### Simplified Client (Recommended)
@@ -75,6 +80,39 @@ const preflight = await client.validate('math.add', { a: 10, b: 5 });
 // => { valid: true, checks: [...], requiresApproval: false, errors: [] }
 ```
 
+### Enabling sys_modules for control/events APIs
+
+`APCore.disable`, `APCore.enable`, `APCore.on`, and `APCore.off` are gated on the
+optional system-modules subsystem. They require a `Config` instance with
+`sys_modules.enabled: true` to be passed into the `APCore` constructor —
+otherwise the calls throw with a clear "sys_modules must be enabled" message.
+
+```typescript
+import { APCore, Config } from 'apcore-js';
+
+// Inline config (equivalent to writing the same YAML and calling Config.load):
+const config = new Config({
+  sys_modules: {
+    enabled: true,
+    // Optional sub-systems:
+    events: { enabled: true },     // required for on/off (event emitter)
+    control: { enabled: true },    // required for disable/enable (toggle)
+  },
+});
+
+const client = new APCore({ config });
+
+// Now safe to call:
+await client.disable('math.add');
+await client.enable('math.add');
+client.on('apcore.module.disabled', (event) => {
+  console.log('Disabled:', event.data);
+});
+```
+
+If you do not need these control/events APIs, omit the `Config` entirely (as in
+the basic Quick Start above).
+
 ### Advanced: Manual Registry + Executor
 
 ```typescript
@@ -101,14 +139,20 @@ const result = await executor.call('example.greet', { name: 'World' });
 
 | Class | Description |
 |-------|-------------|
-| `APCore` | High-level client — register modules, call, stream, validate |
+| `APCore` | High-level client — register modules, call, stream, validate, listModules, describe, on/off, disable/enable. Note: `disable`, `enable`, `on`, and `off` require `sys_modules.enabled: true` in the `Config` passed to `APCore` (see [Quick Start: Enabling sys_modules](#enabling-sys_modules-for-controlevents-apis)). |
 | `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, namespace bus, get/set/bind values |
 | `ACL` | Access control — rule-based caller/target authorization |
 | `Middleware` | Pipeline hooks — before/after/onError interception |
+| `CircuitBreakerMiddleware` | Per-(module, caller) circuit breaker — CLOSED/OPEN/HALF_OPEN with configurable threshold and cooldown |
+| `TracingMiddleware` | OTel-compatible span tracing — accepts any `OtelTracer`/`OtelSpan` without runtime `@opentelemetry/*` dependency |
 | `EventEmitter` | Event system — subscribe, emit, flush |
+| `CircuitBreakerWrapper` | Subscriber-level circuit breaker — protects `EventEmitter` subscribers from cascading failures |
+| `AsyncTaskManager` | Background task execution — injectable store, retry with backoff, opt-in reaper |
+| `PrometheusExporter` | HTTP metrics server — `/metrics`, `/healthz`, `/readyz`; optional `usageCollector` for usage gauges |
+| `InMemoryAuditStore` | Control module audit log — records actor, action, before/after change for every control call |
 
 ## Configuration
 
@@ -197,7 +241,7 @@ Configuration files support two modes. **Legacy mode** (no `apcore:` key) is ful
 ```yaml
 # Namespace mode
 apcore:
-  version: "0.18.0"
+  version: "0.20.0"
 
 _config:
   strict: true
@@ -212,6 +256,51 @@ myPlugin:
   retries: 5
 ```
 
+### System Modules
+
+`registerSysModules()` auto-registers the built-in `system.*` modules that let AI agents query, monitor, and control the apcore runtime. Enable them via `sys_modules.enabled: true` in config, and pass the optional hardening options for production use:
+
+```typescript
+import { registerSysModules, InMemoryAuditStore } from 'apcore-js';
+
+const auditStore = new InMemoryAuditStore();
+
+registerSysModules(registry, executor, config, null, {
+  failOnError: true,              // throw on any registration failure (default: false)
+  overridesPath: '/etc/apcore/overrides.yaml',  // persist runtime changes across restarts
+  auditStore,                     // record every control-module action with actor + change
+});
+
+// Available system modules:
+// system.health.summary / system.health.module     — health status + error rates
+// system.manifest.module / system.manifest.full    — module introspection
+// system.usage.summary / system.usage.module       — call counts + latency trends
+// system.control.update_config                     — hot-patch config values
+// system.control.reload_module                     — hot-reload from disk; supports path_filter glob
+// system.control.toggle_feature                    — disable/enable modules at runtime
+
+// Query the audit log after control calls:
+const entries = auditStore.query({ moduleId: 'system.control.update_config' });
+// entries[0] = { timestamp, action, targetModuleId, actorId, actorType, traceId, change }
+```
+
+**Prometheus usage metrics** — wire `PrometheusExporter` with the `UsageCollector` returned by `registerSysModules`:
+
+```typescript
+import { PrometheusExporter, MetricsCollector } from 'apcore-js';
+
+const ctx = registerSysModules(registry, executor, config);
+const exporter = new PrometheusExporter({
+  collector: new MetricsCollector(),
+  usageCollector: ctx.usageCollector,  // adds apcore_usage_* metrics to /metrics
+});
+exporter.start({ port: 9090 });
+// GET /metrics now includes:
+//   apcore_usage_calls_total{module_id="math.add",status="success"} 5000
+//   apcore_usage_error_rate{module_id="math.add"} 0.0004
+//   apcore_usage_p99_latency_ms{module_id="math.add"} 45.0
+```
+
 ### Error Codes
 
 New error codes added in v0.15.0:
@@ -225,6 +314,17 @@ New error codes added in v0.15.0:
 | `CONFIG_BIND_ERROR` | `config.bind<T>()` or `config.getTyped<T>()` type guard fails |
 | `ERROR_FORMATTER_DUPLICATE` | `ErrorFormatterRegistry.register()` called for an already-registered surface |
 
+New error codes added in v0.20.0:
+
+| Code | Description |
+|------|-------------|
+| `CIRCUIT_BREAKER_OPEN` | `CircuitBreakerMiddleware` short-circuited a call because the circuit is OPEN |
+| `MODULE_RELOAD_CONFLICT` | Both `module_id` and `path_filter` supplied to `system.control.reload_module` |
+| `SYS_MODULE_REGISTRATION_FAILED` | `registerSysModules()` with `failOnError: true` and a module failed to register |
+| `MODULE_ID_CONFLICT` | Two classes in the same file produce the same module ID segment (`discoverMultiClass`) |
+| `INVALID_SEGMENT` | A derived class segment does not match `^[a-z][a-z0-9_]*$` |
+| `ID_TOO_LONG` | A derived module ID exceeds 192 characters |
+
 ### Event Type Canonical Names
 
 apcore 0.15.0 resolved two event-type collisions in favor of dot-namespaced canonical
@@ -443,12 +543,15 @@ npm run build
 
 - Core executor pipeline
 - Schema validation (strict mode, type coercion)
-- Middleware chain (ordering, transforms, error recovery)
+- Middleware chain (ordering, transforms, error recovery, circuit breaker)
 - ACL enforcement (patterns, conditions, identity types)
-- Registry system (scanner, metadata, entry points, dependencies)
+- Registry system (scanner, metadata, entry points, dependencies, multi-class discovery)
 - Binding loader (YAML loading, target resolution, schema modes)
-- Observability (tracing, metrics, structured logging)
-- Integration tests (end-to-end flows, error propagation, safety checks)
+- Observability (tracing, BatchSpanProcessor, metrics, Prometheus export, structured logging with redaction)
+- Event system (circuit breaker wrapper, subscriber types, filter/file/stdout)
+- System modules (health, manifest, usage, control, audit trail, overrides persistence, Prometheus usage metrics)
+- Async tasks (pluggable store, retry backoff, reaper)
+- Cross-language conformance suite (`tests/conformance.test.ts`) — canonical JSON fixtures from `apcore/conformance/fixtures/` run identically across Python, TypeScript, and Rust SDKs
 
 ## Links
 

package/dist/acl-handlers.d.ts

@@ -11,6 +11,8 @@ export interface ACLConditionHandler {
 }
 /** Type alias for the recursive evaluation function used by compound handlers. */
 export type EvalFn = (conditions: Record<string, unknown>, context: Context) => boolean;
+/** Async variant of EvalFn for use under asyncCheck(). */
+export type AsyncEvalFn = (conditions: Record<string, unknown>, context: Context) => Promise<boolean>;
 /** Check context.identity.type is in the allowed list. */
 export declare class IdentityTypesHandler implements ACLConditionHandler {
     evaluate(value: unknown, context: Context): boolean;
@@ -35,6 +37,18 @@ export declare class NotHandler implements ACLConditionHandler {
     constructor(evaluateFn: EvalFn);
     evaluate(value: unknown, context: Context): boolean;
 }
+/** $or async: list of condition dicts evaluated via the async evaluator. */
+export declare class OrHandlerAsync implements ACLConditionHandler {
+    private readonly _evaluate;
+    constructor(evaluateFn: AsyncEvalFn);
+    evaluate(value: unknown, context: Context): Promise<boolean>;
+}
+/** $not async: single condition dict evaluated via the async evaluator. */
+export declare class NotHandlerAsync implements ACLConditionHandler {
+    private readonly _evaluate;
+    constructor(evaluateFn: AsyncEvalFn);
+    evaluate(value: unknown, context: Context): Promise<boolean>;
+}
 /** Compare two arrays for element-wise equality. */
 export declare function arraysEqual(a: unknown[], b: unknown[]): boolean;
 /** Deep equality for plain objects (conditions comparison). */

package/dist/acl-handlers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"acl-handlers.d.ts","sourceRoot":"","sources":["../src/acl-handlers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,+DAA+D;AAC/D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACxE;AAED,kFAAkF;AAClF,MAAM,MAAM,MAAM,GAAG,CACnB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,OAAO,EAAE,OAAO,KACb,OAAO,CAAC;AAMb,0DAA0D;AAC1D,qBAAa,oBAAqB,YAAW,mBAAmB;IAC9D,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO;CAKpD;AAED,4EAA4E;AAC5E,qBAAa,YAAa,YAAW,mBAAmB;IACtD,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO;CAMpD;AAED,yDAAyD;AACzD,qBAAa,mBAAoB,YAAW,mBAAmB;IAC7D,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO;CAWpD;AAMD,wEAAwE;AACxE,qBAAa,SAAU,YAAW,mBAAmB;IACnD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,UAAU,EAAE,MAAM;IAI9B,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO;CAQpD;AAED,sEAAsE;AACtE,qBAAa,UAAW,YAAW,mBAAmB;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,UAAU,EAAE,MAAM;IAI9B,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO;CAIpD;AAMD,oDAAoD;AACpD,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAM/D;AAED,+DAA+D;AAC/D,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAyBzD"}
+{"version":3,"file":"acl-handlers.d.ts","sourceRoot":"","sources":["../src/acl-handlers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,+DAA+D;AAC/D,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACxE;AAED,kFAAkF;AAClF,MAAM,MAAM,MAAM,GAAG,CACnB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,OAAO,EAAE,OAAO,KACb,OAAO,CAAC;AAEb,0DAA0D;AAC1D,MAAM,MAAM,WAAW,GAAG,CACxB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACnC,OAAO,EAAE,OAAO,KACb,OAAO,CAAC,OAAO,CAAC,CAAC;AAMtB,0DAA0D;AAC1D,qBAAa,oBAAqB,YAAW,mBAAmB;IAC9D,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO;CAKpD;AAED,4EAA4E;AAC5E,qBAAa,YAAa,YAAW,mBAAmB;IACtD,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO;CAMpD;AAED,yDAAyD;AACzD,qBAAa,mBAAoB,YAAW,mBAAmB;IAC7D,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO;CAgBpD;AAMD,wEAAwE;AACxE,qBAAa,SAAU,YAAW,mBAAmB;IACnD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,UAAU,EAAE,MAAM;IAI9B,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO;CAQpD;AAED,sEAAsE;AACtE,qBAAa,UAAW,YAAW,mBAAmB;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,UAAU,EAAE,MAAM;IAI9B,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO;CAIpD;AAED,4EAA4E;AAC5E,qBAAa,cAAe,YAAW,mBAAmB;IACxD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;gBAE5B,UAAU,EAAE,WAAW;IAI7B,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;CAQnE;AAED,2EAA2E;AAC3E,qBAAa,eAAgB,YAAW,mBAAmB;IACzD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAc;gBAE5B,UAAU,EAAE,WAAW;IAI7B,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;CAInE;AAMD,oDAAoD;AACpD,wBAAgB,WAAW,CAAC,CAAC,EAAE,OAAO,EAAE,EAAE,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAM/D;AAED,+DAA+D;AAC/D,wBAAgB,SAAS,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,OAAO,CAyBzD"}

package/dist/acl-handlers.js

@@ -32,12 +32,15 @@ export class RolesHandler {
 export class MaxCallDepthHandler {
     evaluate(value, context) {
         let threshold;
-        if (typeof value === 'object' && value !== null && 'lte' in value) {
-            threshold = value.lte;
-        }
-        else if (typeof value === 'number') {
+        if (typeof value === 'number') {
             threshold = value;
         }
+        else if (typeof value === 'object' &&
+            value !== null &&
+            'lte' in value &&
+            typeof value.lte === 'number') {
+            threshold = value.lte;
+        }
         else {
             return false;
         }
@@ -77,6 +80,36 @@ export class NotHandler {
         return !this._evaluate(value, context);
     }
 }
+/** $or async: list of condition dicts evaluated via the async evaluator. */
+export class OrHandlerAsync {
+    _evaluate;
+    constructor(evaluateFn) {
+        this._evaluate = evaluateFn;
+    }
+    async evaluate(value, context) {
+        if (!Array.isArray(value))
+            return false;
+        for (const sub of value) {
+            if (typeof sub !== 'object' || sub === null || Array.isArray(sub))
+                continue;
+            if (await this._evaluate(sub, context))
+                return true;
+        }
+        return false;
+    }
+}
+/** $not async: single condition dict evaluated via the async evaluator. */
+export class NotHandlerAsync {
+    _evaluate;
+    constructor(evaluateFn) {
+        this._evaluate = evaluateFn;
+    }
+    async evaluate(value, context) {
+        if (typeof value !== 'object' || value === null || Array.isArray(value))
+            return false;
+        return !(await this._evaluate(value, context));
+    }
+}
 // ---------------------------------------------------------------------------
 // Utility functions for element-wise comparison (used by removeRule fix)
 // ---------------------------------------------------------------------------

package/dist/acl-handlers.js.map

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

package/dist/acl.d.ts

@@ -23,11 +23,32 @@ export interface AuditEntry {
     readonly roles: readonly string[];
     readonly callDepth: number | null;
     readonly traceId: string | null;
+    /** Error message from a condition handler that threw during evaluation, if any.
+     *  Cross-language parity with apcore-python AuditEntry.handler_error (sync A-D-024). */
+    readonly handlerError: string | null;
 }
 export type AuditLogger = (entry: AuditEntry) => void;
 export declare class ACL {
     private static conditionHandlers;
+    private static asyncConditionHandlers;
     static registerCondition(key: string, handler: ACLConditionHandler): void;
+    /** Register an async-aware handler for use specifically under asyncCheck(). Falls back to conditionHandlers. */
+    static registerAsyncCondition(key: string, handler: ACLConditionHandler): void;
+    /**
+     * Per-call-stack handler-error message captured by `_evaluateConditions[Async]`.
+     * Set inside catch blocks; consumed by `_buildAuditEntry` to populate
+     * `AuditEntry.handlerError`. Mirrors apcore-python's `_handler_error_var`
+     * contextvar (sync finding A-D-026). JS is single-threaded so a static field
+     * is sufficient — the accessor pair `_takeLastHandlerError()` and the
+     * implicit reset at each `check()` / `asyncCheck()` call ensures no leakage
+     * across evaluations.
+     */
+    private static _lastHandlerError;
+    /**
+     * Read-and-clear the most recent handler-error message captured by an
+     * `_evaluateConditions[Async]` invocation.
+     */
+    static _takeLastHandlerError(): string | null;
     static _evaluateConditions(conditions: Record<string, unknown>, context: Context): boolean;
     static _evaluateConditionsAsync(conditions: Record<string, unknown>, context: Context): Promise<boolean>;
     private _rules;
@@ -47,7 +68,7 @@ export declare class ACL {
     private _matchesRule;
     private _checkConditions;
     addRule(rule: ACLRule): void;
-    removeRule(callers: string[], targets: string[]): boolean;
+    removeRule(callers: string[], targets: string[], conditions?: Record<string, unknown> | null): boolean;
     reload(): void;
 }
 //# sourceMappingURL=acl.d.ts.map

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;AAG5C,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAc7D,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,CAAC,iBAAiB,CAA0C;IAE1E,MAAM,CAAC,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,mBAAmB,GAAG,IAAI;IAIzE,MAAM,CAAC,mBAAmB,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO;WAyB7E,wBAAwB,CAAC,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAkB9G,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;IA6B7E,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC;YA6BzF,mBAAmB;YAoBnB,iBAAiB;IAY/B,OAAO,CAAC,gBAAgB;IAsCxB,OAAO,CAAC,aAAa;IAQrB,OAAO,CAAC,cAAc;IAiBtB,OAAO,CAAC,YAAY;IAWpB,OAAO,CAAC,gBAAgB;IAKxB,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;IAI5B,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO;IAWzD,MAAM,IAAI,IAAI;CASf"}
+{"version":3,"file":"acl.d.ts","sourceRoot":"","sources":["../src/acl.ts"],"names":[],"mappings":"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"}

package/dist/acl.js

@@ -4,7 +4,7 @@
 import yaml from 'js-yaml';
 import { ACLRuleError, ConfigNotFoundError } from './errors.js';
 import { matchPattern } from './utils/pattern.js';
-import { IdentityTypesHandler, RolesHandler, MaxCallDepthHandler, OrHandler, NotHandler, arraysEqual, } from './acl-handlers.js';
+import { IdentityTypesHandler, RolesHandler, MaxCallDepthHandler, OrHandler, NotHandler, OrHandlerAsync, NotHandlerAsync, arraysEqual, deepEqual, } from './acl-handlers.js';
 // Lazy-load Node.js built-in modules for browser compatibility
 let _nodeFs = null;
 try {
@@ -43,28 +43,58 @@ function parseAclRule(rawRule, index) {
 }
 export class ACL {
     static conditionHandlers = new Map();
+    static asyncConditionHandlers = new Map();
     static registerCondition(key, handler) {
         ACL.conditionHandlers.set(key, handler);
     }
+    /** Register an async-aware handler for use specifically under asyncCheck(). Falls back to conditionHandlers. */
+    static registerAsyncCondition(key, handler) {
+        ACL.asyncConditionHandlers.set(key, handler);
+    }
+    /**
+     * Per-call-stack handler-error message captured by `_evaluateConditions[Async]`.
+     * Set inside catch blocks; consumed by `_buildAuditEntry` to populate
+     * `AuditEntry.handlerError`. Mirrors apcore-python's `_handler_error_var`
+     * contextvar (sync finding A-D-026). JS is single-threaded so a static field
+     * is sufficient — the accessor pair `_takeLastHandlerError()` and the
+     * implicit reset at each `check()` / `asyncCheck()` call ensures no leakage
+     * across evaluations.
+     */
+    static _lastHandlerError = null;
+    /**
+     * Read-and-clear the most recent handler-error message captured by an
+     * `_evaluateConditions[Async]` invocation.
+     */
+    static _takeLastHandlerError() {
+        const err = ACL._lastHandlerError;
+        ACL._lastHandlerError = null;
+        return err;
+    }
     static _evaluateConditions(conditions, context) {
         for (const [key, value] of Object.entries(conditions)) {
             const handler = ACL.conditionHandlers.get(key);
             if (handler === undefined) {
-                console.warn(`[apcore:acl] Unknown ACL condition '${key}' — treated as unsatisfied`);
+                const msg = `Unknown ACL condition '${key}'`;
+                ACL._lastHandlerError = msg;
+                console.warn(`[apcore:acl] ${msg} — treated as unsatisfied`);
                 return false;
             }
             try {
                 const result = handler.evaluate(value, context);
                 if (result instanceof Promise) {
                     // Async handler in sync context — fail-closed
-                    console.warn(`[apcore:acl] Async condition '${key}' in sync context — treated as unsatisfied. Use asyncCheck().`);
+                    const msg = `Async condition '${key}' in sync context — use asyncCheck()`;
+                    ACL._lastHandlerError = msg;
+                    console.warn(`[apcore:acl] ${msg}`);
                     return false;
                 }
                 if (!result)
                     return false;
             }
-            catch {
-                console.warn(`[apcore:acl] Handler for condition '${key}' threw — treated as unsatisfied`);
+            catch (e) {
+                const msg = `Handler for condition '${key}' threw: ${e instanceof Error ? e.message : String(e)}`;
+                ACL._lastHandlerError = msg;
+                console.warn(`[apcore:acl] ${msg} — treated as unsatisfied`);
                 return false;
             }
         }
@@ -72,9 +102,11 @@ export class ACL {
     }
     static async _evaluateConditionsAsync(conditions, context) {
         for (const [key, value] of Object.entries(conditions)) {
-            const handler = ACL.conditionHandlers.get(key);
+            const handler = ACL.asyncConditionHandlers.get(key) ?? ACL.conditionHandlers.get(key);
             if (handler === undefined) {
-                console.warn(`[apcore:acl] Unknown ACL condition '${key}' — treated as unsatisfied`);
+                const msg = `Unknown ACL condition '${key}'`;
+                ACL._lastHandlerError = msg;
+                console.warn(`[apcore:acl] ${msg} — treated as unsatisfied`);
                 return false;
             }
             try {
@@ -82,8 +114,10 @@ export class ACL {
                 if (!result)
                     return false;
             }
-            catch {
-                console.warn(`[apcore:acl] Handler for condition '${key}' threw — treated as unsatisfied`);
+            catch (e) {
+                const msg = `Handler for condition '${key}' threw: ${e instanceof Error ? e.message : String(e)}`;
+                ACL._lastHandlerError = msg;
+                console.warn(`[apcore:acl] ${msg} — treated as unsatisfied`);
                 return false;
             }
         }
@@ -137,44 +171,59 @@ export class ACL {
     check(callerId, targetId, context) {
         const effectiveCaller = callerId === null ? '@external' : callerId;
         const ctx = context ?? null;
-        for (let idx = 0; idx < this._rules.length; idx++) {
-            const rule = this._rules[idx];
+        // Snapshot rules + defaultEffect + auditLogger atomically so concurrent
+        // addRule/removeRule/setDefaultEffect calls cannot mutate state mid-evaluation.
+        // Mirrors asyncCheck snapshot semantics for sync/async parity.
+        const rules = this._rules.slice();
+        const defaultEffect = this._defaultEffect;
+        const auditLogger = this._auditLogger;
+        // Clear any leftover handler-error captured by a previous evaluation.
+        ACL._takeLastHandlerError();
+        for (let idx = 0; idx < rules.length; idx++) {
+            const rule = 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));
+                if (auditLogger) {
+                    auditLogger(this._buildAuditEntry(effectiveCaller, targetId, decision ? 'allow' : 'deny', 'rule_match', rule, idx, ctx, ACL._takeLastHandlerError()));
                 }
                 return decision;
             }
         }
-        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));
+        const defaultDecision = defaultEffect === 'allow';
+        if (auditLogger) {
+            const reason = rules.length === 0 ? 'no_rules' : 'default_effect';
+            auditLogger(this._buildAuditEntry(effectiveCaller, targetId, defaultDecision ? 'allow' : 'deny', reason, null, null, ctx, ACL._takeLastHandlerError()));
         }
         return defaultDecision;
     }
     async asyncCheck(callerId, targetId, context) {
         const effectiveCaller = callerId === null ? '@external' : callerId;
         const ctx = context ?? null;
-        for (let idx = 0; idx < this._rules.length; idx++) {
-            const rule = this._rules[idx];
+        // Snapshot mutable fields before any await to prevent async-gap races
+        // (e.g. a concurrent setDefaultEffect() or addRule() call mid-evaluation).
+        const rules = this._rules.slice();
+        const defaultEffect = this._defaultEffect;
+        const auditLogger = this._auditLogger;
+        // Clear any leftover handler-error captured by a previous evaluation.
+        ACL._takeLastHandlerError();
+        for (let idx = 0; idx < rules.length; idx++) {
+            const rule = rules[idx];
             if (await this._matchesRuleAsync(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));
+                if (auditLogger) {
+                    auditLogger(this._buildAuditEntry(effectiveCaller, targetId, decision ? 'allow' : 'deny', 'rule_match', rule, idx, ctx, ACL._takeLastHandlerError()));
                 }
                 return decision;
             }
         }
-        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));
+        const defaultDecision = defaultEffect === 'allow';
+        if (auditLogger) {
+            const reason = rules.length === 0 ? 'no_rules' : 'default_effect';
+            auditLogger(this._buildAuditEntry(effectiveCaller, targetId, defaultDecision ? 'allow' : 'deny', reason, null, null, ctx, ACL._takeLastHandlerError()));
         }
         return defaultDecision;
     }
-    async _matchPatternsAsync(patterns, value, context) {
+    _matchPatternsAsync(patterns, value, context) {
         if (patterns.length === 0)
             return false;
         // Check for compound operators
@@ -195,9 +244,9 @@ export class ACL {
         return patterns.some((p) => this._matchPattern(p, value, context));
     }
     async _matchesRuleAsync(rule, caller, target, context) {
-        if (!await this._matchPatternsAsync(rule.callers, caller, context))
+        if (!this._matchPatternsAsync(rule.callers, caller, context))
             return false;
-        if (!await this._matchPatternsAsync(rule.targets, target, context))
+        if (!this._matchPatternsAsync(rule.targets, target, context))
             return false;
         if (rule.conditions != null) {
             if (context === null)
@@ -207,7 +256,7 @@ export class ACL {
         }
         return true;
     }
-    _buildAuditEntry(callerId, targetId, decision, reason, matchedRule, matchedRuleIndex, context) {
+    _buildAuditEntry(callerId, targetId, decision, reason, matchedRule, matchedRuleIndex, context, handlerError = null) {
         let identityType = null;
         let roles = [];
         let callDepth = null;
@@ -232,6 +281,7 @@ export class ACL {
             roles,
             callDepth,
             traceId,
+            handlerError,
         };
     }
     _matchPattern(pattern, value, context) {
@@ -277,13 +327,15 @@ export class ACL {
     addRule(rule) {
         this._rules.unshift(rule);
     }
-    removeRule(callers, targets) {
+    removeRule(callers, targets, conditions) {
         for (let i = 0; i < this._rules.length; i++) {
             const rule = this._rules[i];
-            if (arraysEqual(rule.callers, callers) && arraysEqual(rule.targets, targets)) {
-                this._rules.splice(i, 1);
-                return true;
-            }
+            if (!arraysEqual(rule.callers, callers) || !arraysEqual(rule.targets, targets))
+                continue;
+            if (conditions !== undefined && !deepEqual(rule.conditions ?? null, conditions ?? null))
+                continue;
+            this._rules.splice(i, 1);
+            return true;
         }
         return false;
     }
@@ -309,4 +361,8 @@ ACL.registerCondition('roles', new RolesHandler());
 ACL.registerCondition('max_call_depth', new MaxCallDepthHandler());
 ACL.registerCondition('$or', new OrHandler(ACL._evaluateConditions.bind(ACL)));
 ACL.registerCondition('$not', new NotHandler(ACL._evaluateConditions.bind(ACL)));
+// Async-aware variants used by asyncCheck() so Promise-returning conditions
+// inside $or/$not are awaited rather than dropped via fail-closed.
+ACL.registerAsyncCondition('$or', new OrHandlerAsync(ACL._evaluateConditionsAsync.bind(ACL)));
+ACL.registerAsyncCondition('$not', new NotHandlerAsync(ACL._evaluateConditionsAsync.bind(ACL)));
 //# sourceMappingURL=acl.js.map