apcore-js 0.9.0 → 0.11.0

package/dist/index.js

@@ -1,6 +1,8 @@
 /**
  * apcore - Schema-driven module development framework.
  */
+// Client
+export { APCore } from './client.js';
 // Core
 export { CancelToken, ExecutionCancelledError } from './cancel.js';
 export { Context, createIdentity } from './context.js';
@@ -13,15 +15,19 @@ export { Config } from './config.js';
 // Approval
 export { createApprovalRequest, createApprovalResult, AlwaysDenyHandler, AutoApproveHandler, CallbackApprovalHandler, } from './approval.js';
 // Errors
-export { ModuleError, ConfigNotFoundError, ConfigError, ACLRuleError, ACLDeniedError, ApprovalError, ApprovalDeniedError, ApprovalTimeoutError, ApprovalPendingError, ModuleNotFoundError, ModuleTimeoutError, SchemaValidationError, SchemaNotFoundError, SchemaParseError, SchemaCircularRefError, CallDepthExceededError, CircularCallError, CallFrequencyExceededError, InvalidInputError, FuncMissingTypeHintError, FuncMissingReturnTypeError, BindingInvalidTargetError, BindingModuleNotFoundError, BindingCallableNotFoundError, BindingNotCallableError, BindingSchemaMissingError, BindingFileInvalidError, CircularDependencyError, ModuleLoadError, ModuleExecuteError, InternalError, ErrorCodes, } from './errors.js';
+export { ModuleError, ConfigNotFoundError, ConfigError, ACLRuleError, ACLDeniedError, ApprovalError, ApprovalDeniedError, ApprovalTimeoutError, ApprovalPendingError, ModuleNotFoundError, ModuleDisabledError, ModuleTimeoutError, SchemaValidationError, SchemaNotFoundError, SchemaParseError, SchemaCircularRefError, CallDepthExceededError, CircularCallError, CallFrequencyExceededError, InvalidInputError, FuncMissingTypeHintError, FuncMissingReturnTypeError, BindingInvalidTargetError, BindingModuleNotFoundError, BindingCallableNotFoundError, BindingNotCallableError, BindingSchemaMissingError, BindingFileInvalidError, CircularDependencyError, DependencyNotFoundError, FeatureNotImplementedError, ModuleLoadError, ReloadFailedError, ModuleExecuteError, InternalError, ErrorCodes, } from './errors.js';
 // ACL
 export { ACL } from './acl.js';
 // Middleware
-export { Middleware, MiddlewareManager, MiddlewareChainError, BeforeMiddleware, AfterMiddleware, LoggingMiddleware, RetryMiddleware, CTX_RETRY_COUNT_PREFIX, CTX_RETRY_DELAY_PREFIX } from './middleware/index.js';
+export { Middleware, MiddlewareManager, MiddlewareChainError, BeforeMiddleware, AfterMiddleware, LoggingMiddleware, RetryMiddleware, CTX_RETRY_COUNT_PREFIX, CTX_RETRY_DELAY_PREFIX, ErrorHistoryMiddleware, PlatformNotifyMiddleware } from './middleware/index.js';
 // Decorator
 export { module, FunctionModule, normalizeResult, makeAutoId } from './decorator.js';
 // Extensions
 export { ExtensionManager } from './extensions.js';
+// Events
+export { EventEmitter, createEvent, WebhookSubscriber, A2ASubscriber } from './events/index.js';
+// System Modules
+export { registerSysModules, registerSubscriberType, unregisterSubscriberType, resetSubscriberRegistry, ToggleState, ToggleFeatureModule, defaultToggleState, isModuleDisabled, checkModuleDisabled, HealthSummaryModule, HealthModuleModule, classifyHealthStatus, ManifestModuleModule, ManifestFullModule, UpdateConfigModule, ReloadModuleModule, UsageSummaryModule, UsageModuleModule, } from './sys-modules/index.js';
 // Async tasks
 export { AsyncTaskManager, TaskStatus } from './async-task.js';
 // Bindings
@@ -46,7 +52,10 @@ export { toStrictSchema, applyLlmDescriptions, stripExtensions } from './schema/
 export { TracingMiddleware, StdoutExporter, InMemoryExporter, OTLPExporter, createSpan } from './observability/tracing.js';
 export { MetricsCollector, MetricsMiddleware } from './observability/metrics.js';
 export { ContextLogger, ObsLoggingMiddleware } from './observability/context-logger.js';
+export { ErrorHistory } from './observability/error-history.js';
+export { UsageCollector, UsageMiddleware, bucketKey } from './observability/usage.js';
+export { computeModuleErrorRate, estimateP99FromHistogram, matchesModuleId, METRIC_CALLS_TOTAL, METRIC_DURATION_SECONDS } from './observability/metrics-utils.js';
 // Trace Context
 export { TraceContext } from './trace-context.js';
-export const VERSION = '0.9.0';
+export const VERSION = '0.11.0';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/middleware/error-history.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Middleware that records ModuleError details into ErrorHistory.
+ */
+import type { Context } from '../context.js';
+import { Middleware } from './base.js';
+import type { ErrorHistory } from '../observability/error-history.js';
+/**
+ * Records ModuleError instances into ErrorHistory on every onError() call.
+ * Generic exceptions are ignored. This middleware never recovers from errors.
+ */
+export declare class ErrorHistoryMiddleware extends Middleware {
+    private readonly _errorHistory;
+    constructor(errorHistory: ErrorHistory);
+    onError(moduleId: string, _inputs: Record<string, unknown>, error: Error, _context: Context): Record<string, unknown> | null;
+}
+//# sourceMappingURL=error-history.d.ts.map

package/dist/middleware/error-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-history.d.ts","sourceRoot":"","sources":["../../src/middleware/error-history.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mCAAmC,CAAC;AAEtE;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,UAAU;IACpD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAe;gBAEjC,YAAY,EAAE,YAAY;IAK7B,OAAO,CACd,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,KAAK,EAAE,KAAK,EACZ,QAAQ,EAAE,OAAO,GAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;CAMlC"}

package/dist/middleware/error-history.js

@@ -0,0 +1,23 @@
+/**
+ * Middleware that records ModuleError details into ErrorHistory.
+ */
+import { ModuleError } from '../errors.js';
+import { Middleware } from './base.js';
+/**
+ * Records ModuleError instances into ErrorHistory on every onError() call.
+ * Generic exceptions are ignored. This middleware never recovers from errors.
+ */
+export class ErrorHistoryMiddleware extends Middleware {
+    _errorHistory;
+    constructor(errorHistory) {
+        super();
+        this._errorHistory = errorHistory;
+    }
+    onError(moduleId, _inputs, error, _context) {
+        if (error instanceof ModuleError) {
+            this._errorHistory.record(moduleId, error);
+        }
+        return null;
+    }
+}
+//# sourceMappingURL=error-history.js.map

package/dist/middleware/error-history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-history.js","sourceRoot":"","sources":["../../src/middleware/error-history.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAGvC;;;GAGG;AACH,MAAM,OAAO,sBAAuB,SAAQ,UAAU;IACnC,aAAa,CAAe;IAE7C,YAAY,YAA0B;QACpC,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,aAAa,GAAG,YAAY,CAAC;IACpC,CAAC;IAEQ,OAAO,CACd,QAAgB,EAChB,OAAgC,EAChC,KAAY,EACZ,QAAiB;QAEjB,IAAI,KAAK,YAAY,WAAW,EAAE,CAAC;YACjC,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QAC7C,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/middleware/index.d.ts

@@ -6,4 +6,6 @@ export { LoggingMiddleware } from './logging.js';
 export type { Logger } from './logging.js';
 export { RetryMiddleware, CTX_RETRY_COUNT_PREFIX, CTX_RETRY_DELAY_PREFIX } from './retry.js';
 export type { RetryConfig } from './retry.js';
+export { ErrorHistoryMiddleware } from './error-history.js';
+export { PlatformNotifyMiddleware } from './platform-notify.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/middleware/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAClE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,YAAY,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAC7F,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAClE,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACjD,YAAY,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAC7F,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/middleware/index.js

@@ -3,4 +3,6 @@ export { MiddlewareManager, MiddlewareChainError } from './manager.js';
 export { BeforeMiddleware, AfterMiddleware } from './adapters.js';
 export { LoggingMiddleware } from './logging.js';
 export { RetryMiddleware, CTX_RETRY_COUNT_PREFIX, CTX_RETRY_DELAY_PREFIX } from './retry.js';
+export { ErrorHistoryMiddleware } from './error-history.js';
+export { PlatformNotifyMiddleware } from './platform-notify.js';
 //# sourceMappingURL=index.js.map

package/dist/middleware/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAElE,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACvC,OAAO,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACvE,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAElE,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEjD,OAAO,EAAE,eAAe,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAE7F,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,wBAAwB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/middleware/platform-notify.d.ts

@@ -0,0 +1,30 @@
+/**
+ * PlatformNotifyMiddleware -- threshold sensor with hysteresis.
+ *
+ * Monitors error rates and latency, emits threshold events with hysteresis.
+ * Emits error_threshold_exceeded when a module's error rate crosses the
+ * configured threshold, latency_threshold_exceeded when p99 latency
+ * exceeds the limit, and module_health_changed when a previously alerted
+ * module recovers below threshold * 0.5.
+ */
+import type { Context } from '../context.js';
+import type { EventEmitter } from '../events/emitter.js';
+import type { MetricsCollector } from '../observability/metrics.js';
+import { Middleware } from './base.js';
+export declare class PlatformNotifyMiddleware extends Middleware {
+    private readonly _emitter;
+    private readonly _metricsCollector;
+    private readonly _errorRateThreshold;
+    private readonly _latencyP99ThresholdMs;
+    private readonly _alerted;
+    constructor(eventEmitter: EventEmitter, metricsCollector?: MetricsCollector | null, errorRateThreshold?: number, latencyP99ThresholdMs?: number);
+    after(moduleId: string, _inputs: Record<string, unknown>, _output: Record<string, unknown>, _context: Context): Record<string, unknown> | null;
+    onError(moduleId: string, _inputs: Record<string, unknown>, _error: Error, _context: Context): Record<string, unknown> | null;
+    private _getAlerted;
+    private _computeErrorRate;
+    private _checkErrorRateThreshold;
+    private _checkLatencyThreshold;
+    private _estimateP99Ms;
+    private _checkErrorRecovery;
+}
+//# sourceMappingURL=platform-notify.d.ts.map

package/dist/middleware/platform-notify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-notify.d.ts","sourceRoot":"","sources":["../../src/middleware/platform-notify.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,KAAK,EAAE,YAAY,EAAe,MAAM,sBAAsB,CAAC;AAEtE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAEpE,OAAO,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAEvC,qBAAa,wBAAyB,SAAQ,UAAU;IACtD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAe;IACxC,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAA0B;IAC5D,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAS;IAC7C,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAS;IAChD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAuC;gBAG9D,YAAY,EAAE,YAAY,EAC1B,gBAAgB,GAAE,gBAAgB,GAAG,IAAW,EAChD,kBAAkB,GAAE,MAAY,EAChC,qBAAqB,GAAE,MAAa;IAS7B,KAAK,CACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,QAAQ,EAAE,OAAO,GAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAMxB,OAAO,CACd,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,MAAM,EAAE,KAAK,EACb,QAAQ,EAAE,OAAO,GAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAKjC,OAAO,CAAC,WAAW;IASnB,OAAO,CAAC,iBAAiB;IAKzB,OAAO,CAAC,wBAAwB;IAchC,OAAO,CAAC,sBAAsB;IAiB9B,OAAO,CAAC,cAAc;IAKtB,OAAO,CAAC,mBAAmB;CAe5B"}

package/dist/middleware/platform-notify.js

@@ -0,0 +1,84 @@
+/**
+ * PlatformNotifyMiddleware -- threshold sensor with hysteresis.
+ *
+ * Monitors error rates and latency, emits threshold events with hysteresis.
+ * Emits error_threshold_exceeded when a module's error rate crosses the
+ * configured threshold, latency_threshold_exceeded when p99 latency
+ * exceeds the limit, and module_health_changed when a previously alerted
+ * module recovers below threshold * 0.5.
+ */
+import { createEvent } from '../events/emitter.js';
+import { computeModuleErrorRate, estimateP99FromHistogram } from '../observability/metrics-utils.js';
+import { Middleware } from './base.js';
+export class PlatformNotifyMiddleware extends Middleware {
+    _emitter;
+    _metricsCollector;
+    _errorRateThreshold;
+    _latencyP99ThresholdMs;
+    _alerted = new Map();
+    constructor(eventEmitter, metricsCollector = null, errorRateThreshold = 0.1, latencyP99ThresholdMs = 5000) {
+        super();
+        this._emitter = eventEmitter;
+        this._metricsCollector = metricsCollector;
+        this._errorRateThreshold = errorRateThreshold;
+        this._latencyP99ThresholdMs = latencyP99ThresholdMs;
+    }
+    after(moduleId, _inputs, _output, _context) {
+        this._checkLatencyThreshold(moduleId);
+        this._checkErrorRecovery(moduleId);
+        return null;
+    }
+    onError(moduleId, _inputs, _error, _context) {
+        this._checkErrorRateThreshold(moduleId);
+        return null;
+    }
+    _getAlerted(moduleId) {
+        let set = this._alerted.get(moduleId);
+        if (!set) {
+            set = new Set();
+            this._alerted.set(moduleId, set);
+        }
+        return set;
+    }
+    _computeErrorRate(moduleId) {
+        if (!this._metricsCollector)
+            return 0;
+        return computeModuleErrorRate(this._metricsCollector, moduleId).errorRate;
+    }
+    _checkErrorRateThreshold(moduleId) {
+        const errorRate = this._computeErrorRate(moduleId);
+        const alerted = this._getAlerted(moduleId);
+        if (errorRate >= this._errorRateThreshold && !alerted.has('error_rate')) {
+            this._emitter.emit(createEvent('error_threshold_exceeded', moduleId, 'warning', { error_rate: errorRate, threshold: this._errorRateThreshold }));
+            alerted.add('error_rate');
+        }
+    }
+    _checkLatencyThreshold(moduleId) {
+        if (!this._metricsCollector)
+            return;
+        const alerted = this._getAlerted(moduleId);
+        if (alerted.has('latency'))
+            return;
+        const p99Ms = this._estimateP99Ms(moduleId);
+        if (p99Ms >= this._latencyP99ThresholdMs) {
+            this._emitter.emit(createEvent('latency_threshold_exceeded', moduleId, 'warning', { p99_latency_ms: p99Ms, threshold_ms: this._latencyP99ThresholdMs }));
+            alerted.add('latency');
+        }
+    }
+    _estimateP99Ms(moduleId) {
+        if (!this._metricsCollector)
+            return 0;
+        return estimateP99FromHistogram(this._metricsCollector, moduleId).p99LatencyMs;
+    }
+    _checkErrorRecovery(moduleId) {
+        const alerted = this._alerted.get(moduleId);
+        if (!alerted || !alerted.has('error_rate'))
+            return;
+        const errorRate = this._computeErrorRate(moduleId);
+        if (errorRate < this._errorRateThreshold * 0.5) {
+            this._emitter.emit(createEvent('module_health_changed', moduleId, 'info', { status: 'recovered', error_rate: errorRate }));
+            alerted.delete('error_rate');
+        }
+    }
+}
+//# sourceMappingURL=platform-notify.js.map

package/dist/middleware/platform-notify.js.map

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

package/dist/module.d.ts

@@ -39,5 +39,13 @@ export interface Module {
     outputSchema: TSchema;
     description: string;
     execute(inputs: Record<string, unknown>, context: Context): Promise<Record<string, unknown>> | Record<string, unknown>;
+    /** Optional: Stream module output chunk by chunk. */
+    stream?(inputs: Record<string, unknown>, context: Context): AsyncGenerator<Record<string, unknown>>;
+    /** Optional: Custom input validation without execution. */
+    validate?(inputs: Record<string, unknown>): ValidationResult | Promise<ValidationResult>;
+    /** Optional: Called when module is loaded into the registry. */
+    onLoad?(): void | Promise<void>;
+    /** Optional: Called when module is unloaded from the registry. */
+    onUnload?(): void | Promise<void>;
 }
 //# sourceMappingURL=module.d.ts.map

package/dist/module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,eAAO,MAAM,mBAAmB,EAAE,iBAOhC,CAAC;AAEH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,oBAAoB,EAAE,CAAC;IACxC,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACjD;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,oBAAoB,EAAE,EAC9B,gBAAgB,GAAE,OAAe,GAChC,eAAe,CAMjB;AAED,MAAM,WAAW,MAAM;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACxH"}
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../src/module.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAE5C,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED,eAAO,MAAM,mBAAmB,EAAE,iBAOhC,CAAC;AAEH,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,oBAAoB,EAAE,CAAC;IACxC,QAAQ,CAAC,gBAAgB,EAAE,OAAO,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACjD;AAED,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,oBAAoB,EAAE,EAC9B,gBAAgB,GAAE,OAAe,GAChC,eAAe,CAMjB;AAED,MAAM,WAAW,MAAM;IACrB,WAAW,EAAE,OAAO,CAAC;IACrB,YAAY,EAAE,OAAO,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvH,qDAAqD;IACrD,MAAM,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,OAAO,GAAG,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpG,2DAA2D;IAC3D,QAAQ,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACzF,gEAAgE;IAChE,MAAM,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChC,kEAAkE;IAClE,QAAQ,CAAC,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnC"}

package/dist/observability/error-history.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Error history with ring-buffer eviction and deduplication.
+ */
+import { ModuleError } from '../errors.js';
+export interface ErrorEntry {
+    readonly moduleId: string;
+    readonly code: string;
+    readonly message: string;
+    readonly aiGuidance: string | null;
+    readonly timestamp: string;
+    count: number;
+    firstOccurred: string;
+    lastOccurred: string;
+}
+/**
+ * Ring buffer storing recent error details per module.
+ * Supports deduplication by (code, message) within each module,
+ * per-module eviction, and global total eviction.
+ */
+export declare class ErrorHistory {
+    private readonly _maxEntriesPerModule;
+    private readonly _maxTotalEntries;
+    private readonly _entries;
+    constructor(maxEntriesPerModule?: number, maxTotalEntries?: number);
+    record(moduleId: string, error: ModuleError): void;
+    get(moduleId: string, limit?: number): ErrorEntry[];
+    clear(): void;
+    clearModule(moduleId: string): void;
+    getAll(limit?: number): ErrorEntry[];
+    private _evictModule;
+    private _evictTotal;
+}
+//# sourceMappingURL=error-history.d.ts.map

package/dist/observability/error-history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-history.d.ts","sourceRoot":"","sources":["../../src/observability/error-history.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE3C,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAS;IAC9C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAS;IAC1C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAwC;gBAErD,mBAAmB,GAAE,MAAW,EAAE,eAAe,GAAE,MAAa;IAK5E,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,IAAI;IAgClD,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,UAAU,EAAE;IAMnD,KAAK,IAAI,IAAI;IAIb,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAInC,MAAM,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,UAAU,EAAE;IASpC,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,WAAW;CA0BpB"}

package/dist/observability/error-history.js

@@ -0,0 +1,96 @@
+/**
+ * Error history with ring-buffer eviction and deduplication.
+ */
+/**
+ * Ring buffer storing recent error details per module.
+ * Supports deduplication by (code, message) within each module,
+ * per-module eviction, and global total eviction.
+ */
+export class ErrorHistory {
+    _maxEntriesPerModule;
+    _maxTotalEntries;
+    _entries = new Map();
+    constructor(maxEntriesPerModule = 50, maxTotalEntries = 1000) {
+        this._maxEntriesPerModule = maxEntriesPerModule;
+        this._maxTotalEntries = maxTotalEntries;
+    }
+    record(moduleId, error) {
+        const now = new Date().toISOString();
+        let moduleEntries = this._entries.get(moduleId);
+        if (!moduleEntries) {
+            moduleEntries = [];
+            this._entries.set(moduleId, moduleEntries);
+        }
+        const existing = moduleEntries.find((e) => e.code === error.code && e.message === error.message);
+        if (existing) {
+            existing.count++;
+            existing.lastOccurred = now;
+            return;
+        }
+        const entry = {
+            moduleId,
+            code: error.code,
+            message: error.message,
+            aiGuidance: error.aiGuidance,
+            timestamp: now,
+            count: 1,
+            firstOccurred: now,
+            lastOccurred: now,
+        };
+        moduleEntries.push(entry);
+        this._evictModule(moduleEntries);
+        this._evictTotal();
+    }
+    get(moduleId, limit) {
+        const moduleEntries = this._entries.get(moduleId) ?? [];
+        const result = [...moduleEntries].reverse();
+        return limit !== undefined ? result.slice(0, limit) : result;
+    }
+    clear() {
+        this._entries.clear();
+    }
+    clearModule(moduleId) {
+        this._entries.delete(moduleId);
+    }
+    getAll(limit) {
+        const all = [];
+        for (const entries of this._entries.values()) {
+            all.push(...entries);
+        }
+        all.sort((a, b) => (a.lastOccurred > b.lastOccurred ? -1 : 1));
+        return limit !== undefined ? all.slice(0, limit) : all;
+    }
+    _evictModule(moduleEntries) {
+        while (moduleEntries.length > this._maxEntriesPerModule) {
+            moduleEntries.shift();
+        }
+    }
+    _evictTotal() {
+        let total = 0;
+        for (const entries of this._entries.values()) {
+            total += entries.length;
+        }
+        while (total > this._maxTotalEntries) {
+            let oldestEntry = null;
+            let oldestModuleId = null;
+            for (const [mid, entries] of this._entries) {
+                if (entries.length > 0) {
+                    const candidate = entries[0];
+                    if (oldestEntry === null || candidate.lastOccurred < oldestEntry.lastOccurred) {
+                        oldestEntry = candidate;
+                        oldestModuleId = mid;
+                    }
+                }
+            }
+            if (oldestModuleId === null)
+                break;
+            const entries = this._entries.get(oldestModuleId);
+            entries.shift();
+            if (entries.length === 0) {
+                this._entries.delete(oldestModuleId);
+            }
+            total--;
+        }
+    }
+}
+//# sourceMappingURL=error-history.js.map

package/dist/observability/error-history.js.map

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

package/dist/observability/index.d.ts

@@ -2,4 +2,8 @@ export { TracingMiddleware, StdoutExporter, InMemoryExporter, createSpan } from
 export type { Span, SpanExporter } from './tracing.js';
 export { MetricsCollector, MetricsMiddleware } from './metrics.js';
 export { ContextLogger, ObsLoggingMiddleware } from './context-logger.js';
+export { ErrorHistory } from './error-history.js';
+export type { ErrorEntry } from './error-history.js';
+export { UsageCollector, UsageMiddleware, bucketKey } from './usage.js';
+export type { UsageRecord, CallerUsageSummary, HourlyBucket, ModuleUsageSummary, ModuleUsageDetail } from './usage.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/observability/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/F,YAAY,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/F,YAAY,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACxE,YAAY,EAAE,WAAW,EAAE,kBAAkB,EAAE,YAAY,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC"}

package/dist/observability/index.js

@@ -1,4 +1,6 @@
 export { TracingMiddleware, StdoutExporter, InMemoryExporter, createSpan } from './tracing.js';
 export { MetricsCollector, MetricsMiddleware } from './metrics.js';
 export { ContextLogger, ObsLoggingMiddleware } from './context-logger.js';
+export { ErrorHistory } from './error-history.js';
+export { UsageCollector, UsageMiddleware, bucketKey } from './usage.js';
 //# sourceMappingURL=index.js.map

package/dist/observability/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/F,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/observability/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAE/F,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AACnE,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AAC1E,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC"}

package/dist/observability/metrics-utils.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared utilities for extracting module-level metrics from MetricsCollector snapshots.
+ */
+import type { MetricsCollector } from './metrics.js';
+export declare const METRIC_CALLS_TOTAL = "apcore_module_calls_total";
+export declare const METRIC_DURATION_SECONDS = "apcore_module_duration_seconds";
+/**
+ * Check if a metric key's labels contain an exact module_id match.
+ * Keys have the format: "metric_name|module_id=foo,status=bar"
+ * This prevents false-matching when one module ID is a suffix of another.
+ */
+export declare function matchesModuleId(key: string, moduleId: string): boolean;
+/**
+ * Compute error rate for a module from a MetricsCollector snapshot.
+ */
+export declare function computeModuleErrorRate(metricsCollector: MetricsCollector, moduleId: string): {
+    totalCalls: number;
+    errorCount: number;
+    errorRate: number;
+};
+/**
+ * Estimate p99 latency in milliseconds from histogram buckets.
+ * Returns the upper bound of the first bucket that contains ≥99% of observations.
+ * If all observations exceed the largest bucket, returns the last bucket upper bound.
+ */
+export declare function estimateP99FromHistogram(metricsCollector: MetricsCollector, moduleId: string): {
+    avgLatencyMs: number;
+    p99LatencyMs: number;
+};
+//# sourceMappingURL=metrics-utils.d.ts.map

package/dist/observability/metrics-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics-utils.d.ts","sourceRoot":"","sources":["../../src/observability/metrics-utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAErD,eAAO,MAAM,kBAAkB,8BAA8B,CAAC;AAC9D,eAAO,MAAM,uBAAuB,mCAAmC,CAAC;AAMxE;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGtE;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,gBAAgB,EAAE,gBAAgB,EAClC,QAAQ,EAAE,MAAM,GACf;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAiB/D;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,gBAAgB,EAAE,gBAAgB,EAClC,QAAQ,EAAE,MAAM,GACf;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,CA8BhD"}

package/dist/observability/metrics-utils.js

@@ -0,0 +1,71 @@
+/**
+ * Shared utilities for extracting module-level metrics from MetricsCollector snapshots.
+ */
+export const METRIC_CALLS_TOTAL = 'apcore_module_calls_total';
+export const METRIC_DURATION_SECONDS = 'apcore_module_duration_seconds';
+const DEFAULT_HISTOGRAM_BUCKETS = [
+    0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0, 30.0, 60.0,
+];
+/**
+ * Check if a metric key's labels contain an exact module_id match.
+ * Keys have the format: "metric_name|module_id=foo,status=bar"
+ * This prevents false-matching when one module ID is a suffix of another.
+ */
+export function matchesModuleId(key, moduleId) {
+    const labelMatch = `|module_id=${moduleId}`;
+    return key.includes(`${labelMatch},`) || key.endsWith(labelMatch);
+}
+/**
+ * Compute error rate for a module from a MetricsCollector snapshot.
+ */
+export function computeModuleErrorRate(metricsCollector, moduleId) {
+    const snap = metricsCollector.snapshot();
+    const counters = snap['counters'];
+    if (!counters)
+        return { totalCalls: 0, errorCount: 0, errorRate: 0 };
+    let total = 0;
+    let errors = 0;
+    const prefix = `${METRIC_CALLS_TOTAL}|`;
+    for (const [key, value] of Object.entries(counters)) {
+        if (!key.startsWith(prefix))
+            continue;
+        if (!matchesModuleId(key, moduleId))
+            continue;
+        total += value;
+        if (key.includes('status=error')) {
+            errors += value;
+        }
+    }
+    return { totalCalls: total, errorCount: errors, errorRate: total === 0 ? 0 : errors / total };
+}
+/**
+ * Estimate p99 latency in milliseconds from histogram buckets.
+ * Returns the upper bound of the first bucket that contains ≥99% of observations.
+ * If all observations exceed the largest bucket, returns the last bucket upper bound.
+ */
+export function estimateP99FromHistogram(metricsCollector, moduleId) {
+    const snap = metricsCollector.snapshot();
+    const histograms = snap['histograms'];
+    if (!histograms)
+        return { avgLatencyMs: 0, p99LatencyMs: 0 };
+    const durationKey = `${METRIC_DURATION_SECONDS}|module_id=${moduleId}`;
+    const sumVal = histograms.sums?.[durationKey] ?? 0;
+    const countVal = histograms.counts?.[durationKey] ?? 0;
+    const avgLatencyMs = countVal > 0 ? (sumVal / countVal) * 1000 : 0;
+    let p99LatencyMs = 0;
+    if (countVal > 0 && histograms.buckets) {
+        const target = countVal * 0.99;
+        for (const b of DEFAULT_HISTOGRAM_BUCKETS) {
+            const bkey = `${durationKey}|${b}`;
+            const cumCount = histograms.buckets[bkey] ?? 0;
+            if (cumCount >= target) {
+                p99LatencyMs = b * 1000;
+                return { avgLatencyMs, p99LatencyMs };
+            }
+        }
+        // All observations exceed the largest bucket
+        p99LatencyMs = DEFAULT_HISTOGRAM_BUCKETS[DEFAULT_HISTOGRAM_BUCKETS.length - 1] * 1000;
+    }
+    return { avgLatencyMs, p99LatencyMs };
+}
+//# sourceMappingURL=metrics-utils.js.map

package/dist/observability/metrics-utils.js.map

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