npm - @wildo-ai/saas-backend-lib - Versions diffs - 1.1.2 → 1.1.3 - Mend

@wildo-ai/saas-backend-lib 1.1.2 → 1.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (853) hide show

package/dist/esm/errors/services/error-handler.backend.service.js CHANGED Viewed

@@ -19,12 +19,121 @@ import { getCurrentCorrelationId } from '../../runtime/models/request-context.al
 // Import the unified error system
 import { ErrorType, WildoHeaderKeys, } from '@wildo-ai/saas-models';
 /**
- * Narrowly isolates uncaught exceptions that originate inside
- * `@opentelemetry/sdk-logs`'s background batch-flush timer from every other
- * uncaught exception. Matched ONLY by the presence of the `sdk-logs` package
- * segment in the stack trace — this is deliberately conservative: any error
- * whose stack does not clearly point into that package still hard-exits via
- * the default path, so a real host-state-corrupting bug is never masked.
+ * The package-path segments that identify Wildo's OTLP **export pipeline** in a
+ * stack trace: the signal processors that own the background flush timers, the
+ * exporters they hand batches to, and the shared OTLP serialize/send layer
+ * every exporter delegates into.
+ *
+ * The membership criterion is NOT "is this an OpenTelemetry package" — it is
+ * **"can a frame from this package ever appear in the stack of a HOST error?"**
+ * Every package listed here answers no: nothing in it invokes a caller-supplied
+ * callback, so it is reached only from a telemetry export tick (or from
+ * `sdk.shutdown()`). That is what makes a plain "does the stack mention it"
+ * substring test sound: a frame from one of these packages cannot be
+ * *routed through*, only *raised in*.
+ *
+ * `@opentelemetry/exporter-` is a PREFIX on purpose — it covers the three
+ * exporters `otel-preload.ts` wires today (`exporter-trace-otlp-http`,
+ * `exporter-metrics-otlp-http`, `exporter-logs-otlp-http`) and every transport
+ * sibling (`-proto`, `-grpc`, zipkin, prometheus) a future provider selection
+ * could swap in, without this list having to be revisited. Each is export-only
+ * by construction.
+ *
+ * Kept in step with the package's real OpenTelemetry dependency set by the
+ * totality pin in `__tests__/error-handler.backend.service.test.ts`, which
+ * enumerates every `@opentelemetry/*` entry in this package's own
+ * `package.json` and fails unless each one is either matched here or named in
+ * {@link TELEMETRY_PACKAGES_DELIBERATELY_NOT_ISOLATED}. A name list with no
+ * link to whatever owns those names is the drift this carve-out already had
+ * once; the pin is that link. It is test-time rather than compile-time because
+ * the owning vocabulary is a JSON manifest, not a TypeScript symbol.
+ */
+export const TELEMETRY_EXPORT_PIPELINE_STACK_MARKERS = [
+    // Log signal: `BatchLogRecordProcessor`'s periodic `_flushOneBatch` timer —
+    // the frame the 2026-08-06 incident was raised in (see below).
+    '@opentelemetry/sdk-logs',
+    // Metric signal: `PeriodicExportingMetricReader`'s collect/export interval.
+    // Safe as a whole-stack match only while this application declares no
+    // OBSERVABLE instrument: an observable callback is host code invoked by the
+    // reader, and would put host frames under an `sdk-metrics` frame. None exist
+    // (no `createObservable*`/`addCallback` call site in engine/, platform/ or
+    // examples/ as of 2026-09-09), and such a callback would in any case be
+    // telemetry-collection code failing on the collection tick.
+    '@opentelemetry/sdk-metrics',
+    // Every OTLP/zipkin/prometheus exporter — see the prefix note above.
+    '@opentelemetry/exporter-',
+    // The shared OTLP serialize + send layer the exporters above delegate into,
+    // and where a transport/serialization fault is actually raised.
+    '@opentelemetry/otlp-exporter-base',
+    '@opentelemetry/otlp-grpc-exporter-base',
+    '@opentelemetry/otlp-transformer',
+];
+/**
+ * The OpenTelemetry packages this carve-out deliberately does NOT isolate, each
+ * with the reason. This is not a leftover list: it is the other half of the
+ * totality pin, so that adding an OTel dependency forces a decision instead of
+ * silently landing outside both sets.
+ *
+ * The reason is the same for the whole first group and it is the one that
+ * matters: **these packages invoke host code**, so their frames appear in the
+ * stack of ordinary host crashes. Matching them would not widen a telemetry
+ * carve-out — it would suppress genuine host faults.
+ */
+export const TELEMETRY_PACKAGES_DELIBERATELY_NOT_ISOLATED = [
+    // --- Runs host code, so a host crash's stack passes through it ---
+    // `Tracer.startActiveSpan(name, fn)` calls `fn` — the host's own work — so
+    // under HTTP auto-instrumentation practically EVERY synchronous server-side
+    // crash carries an `sdk-trace-base` frame. Matching it would carve out the
+    // whole application. The consequence is a stated gap, not an oversight: a
+    // fault raised INSIDE `BatchSpanProcessor` itself (the span-tier analogue of
+    // the 2026-08-06 log-tier incident) still hard-exits. Closing it needs a
+    // discriminator this predicate does not have — either "raised in the TOP
+    // frame" or "the stack shows a timer tick" — and neither is worth the
+    // false-negative risk until a span-tier incident is actually evidenced. The
+    // span EXPORT half is already covered, via `exporter-trace-otlp-http`.
+    '@opentelemetry/sdk-trace-base',
+    '@opentelemetry/sdk-trace-node',
+    // Instrumentation WRAPS host handlers, middleware and driver calls; its
+    // frames sit directly beneath host frames on every instrumented request.
+    '@opentelemetry/instrumentation',
+    '@opentelemetry/instrumentation-express',
+    '@opentelemetry/instrumentation-http',
+    '@opentelemetry/instrumentation-mongoose',
+    '@opentelemetry/instrumentation-redis',
+    '@opentelemetry/auto-instrumentations-node',
+    // `context.with(ctx, fn)` runs the host callback; the API/core/context tier
+    // is on the synchronous path of anything traced.
+    '@opentelemetry/api',
+    '@opentelemetry/api-logs',
+    '@opentelemetry/core',
+    // --- Not an export tick ---
+    // The SDK facade. Its one dangerous call, `sdk.start()`, is already guarded
+    // where it happens (`otel-preload.ts`, Audit A-17) and is a BOOT failure: a
+    // host that cannot start telemetry has no export tick to isolate.
+    '@opentelemetry/sdk-node',
+    // Static data / attribute helpers, resolved at startup. Nothing periodic to
+    // isolate, and their frames appear during host bootstrap.
+    '@opentelemetry/resources',
+    '@opentelemetry/semantic-conventions',
+];
+/**
+ * Isolates an uncaught exception RAISED INSIDE the OTLP export pipeline —
+ * the background machinery that flushes logs, metrics and spans to the
+ * collector on a timer, independent of any request — from every other uncaught
+ * exception, which still hard-exits via the default path.
+ *
+ * WHAT THIS SUPPRESSES: a failure whose stack mentions one of
+ * {@link TELEMETRY_EXPORT_PIPELINE_STACK_MARKERS}. Those packages never call
+ * host code (see that constant's note), so a stack that mentions one of them
+ * is a stack that was raised in one of them.
+ *
+ * WHAT IT MUST NOT SUPPRESS, and does not: anything raised in the host's own
+ * request/business logic, anything raised in OTel INSTRUMENTATION (which wraps
+ * host code), and anything in the trace/context tier a host stack routes
+ * through — see {@link TELEMETRY_PACKAGES_DELIBERATELY_NOT_ISOLATED}. A
+ * carve-out that swallowed a genuine fault into a silently degraded process
+ * would be strictly worse than the crash it prevents, which is why the
+ * criterion is "cannot be on a host stack" rather than "is telemetry".
  *
  * Root cause (2026-08-06): the timer callback in
  * `BatchLogRecordProcessorBase` does `this._flushOneBatch().then(...).catch(...)`
@@ -34,9 +143,20 @@ import { ErrorType, WildoHeaderKeys, } from '@wildo-ai/saas-models';
  * `globalErrorHandler` safety net could catch it, so the failure escaped as a
  * process-level uncaught exception — killing an otherwise-healthy host over a
  * background telemetry-export housekeeping tick.
+ *
+ * WIDENED 2026-09-09. The original predicate matched the single literal
+ * `@opentelemetry/sdk-logs`, which is where that one incident happened to be
+ * raised — so the identical promise-chain/transport failure arriving from the
+ * METRIC reader or from ANY of the three OTLP exporters was not isolated and
+ * hard-exited the host. Keying a carve-out on one package NAME makes its reach
+ * an accident of which pipeline failed first; the property that actually
+ * distinguishes the case is the export pipeline itself.
  */
 export function isNonFatalTelemetryPipelineException(error) {
-    return typeof error.stack === 'string' && error.stack.includes('@opentelemetry/sdk-logs');
+    if (typeof error.stack !== 'string')
+        return false;
+    const stack = error.stack;
+    return TELEMETRY_EXPORT_PIPELINE_STACK_MARKERS.some((marker) => stack.includes(marker));
 }
 /**
  * Unified Error Handler Service
@@ -240,7 +360,8 @@ let ErrorHandlerService = class ErrorHandlerService {
      * isolated by {@link isNonFatalTelemetryPipelineException}. Node's own
      * guidance ("uncaught exception means unknown state, exit") assumes the
      * failure came from the host's own request/business logic. A background
-     * telemetry batch-flush timer (OTel's `BatchLogRecordProcessor`, ticking
+     * telemetry export tick (OTel's `BatchLogRecordProcessor` or
+     * `PeriodicExportingMetricReader`, and the OTLP exporters they feed, ticking
      * every few seconds independently of any request) is a different failure
      * domain: its own state corruption says nothing about whether the host's
      * actual work is safe to continue, and `otel-preload.ts` already commits to

package/dist/esm/errors/services/error-handler.backend.service.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"error-handler.backend.service.js","sourceRoot":"","sources":["../../../../../src/errors/services/error-handler.backend.service.ts"],"names":[],"mappings":"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","sourcesContent":["import { NextFunction, Request, Response } from 'express';\nimport { inject, injectable } from 'inversify';\nimport { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';\nimport { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';\nimport { ErrorBuilderBackendService } from './error-builder.backend.service';\nimport { logWildoBackendErrorAtClassifiedSeverity, describeCaughtError } from '~wildo-backend-lib/errors/utils/error-log-level-classification.backend.utils';\nimport { getCurrentCorrelationId } from '~wildo-backend-lib/runtime/models/request-context.als.backend';\n\n// Import the unified error system\nimport {\n ErrorResponse,\n ErrorType,\n ExecutionContext_InitiatorIds,\n WildoError_Backend,\n ValidationErrors,\n ValidationErrorEntry,\n WildoHeaderKeys,\n} from '@wildo-ai/saas-models';\nimport { ExecutionContext, } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';\n\n/*\n Narrowly isolates uncaught exceptions that originate inside\n * `@opentelemetry/sdk-logs`'s background batch-flush timer from every other\n * uncaught exception. Matched ONLY by the presence of the `sdk-logs` package\n * segment in the stack trace — this is deliberately conservative: any error\n * whose stack does not clearly point into that package still hard-exits via\n * the default path, so a real host-state-corrupting bug is never masked.\n \n Root cause (2026-08-06): the timer callback in\n * `BatchLogRecordProcessorBase` does `this._flushOneBatch().then(...).catch(...)`\n * on a fixed interval, independent of any request. Observed in production dev\n * use as `TypeError: this._flushOneBatch(...).then(...).catch is not a\n * function`. The processor's own promise chain broke down before its internal\n * `globalErrorHandler` safety net could catch it, so the failure escaped as a\n * process-level uncaught exception — killing an otherwise-healthy host over a\n * background telemetry-export housekeeping tick.\n /\nexport function isNonFatalTelemetryPipelineException(error: Error): boolean {\n return typeof error.stack === 'string' && error.stack.includes('@opentelemetry/sdk-logs');\n}\n\n/\n Unified Error Handler Service\n * Handles all errors using the new unified error management system\n /\n@injectable()\nexport class ErrorHandlerService {\n protected logDebug: (message: string, context?: Record<string, unknown>) => void;\n\n constructor(\n @inject(SAAS_SERVICE_TYPES.Logger) private logger: LoggerService,\n @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) private errorBuilder: ErrorBuilderBackendService\n ) {\n this.logDebug = this.logger.debugByType('ErrorHandlerService');\n this.logger.setDebugTypeLogging('ErrorHandlerService', false);\n }\n\n /\n Express error handling middleware with unified error system\n * Express requires exactly 4 parameters: (err, req, res, next)\n /\n expressErrorHandler(): (error: Error\|WildoError_Backend, req: Request, res: Response, next: NextFunction) => void {\n return (error: Error\|WildoError_Backend, req: Request, res: Response, next: NextFunction): void => {\n // Check if response has already been sent\n if (res.headersSent) {\n // If headers are already sent, delegate to Express default handler\n return next(error);\n }\n\n // Extract executionContext from request if available\n const executionContext = (req as any).executionContext as ExecutionContext<any> \| undefined;\n\n const errorToHandle = error instanceof Error\n ? this.errorBuilder.buildFromStandardError(error, executionContext)\n : error;\n errorToHandle.ipAddress = this.getClientIpAddress(req);\n\n // Single, central log for every HTTP error — emitted at the classified\n // operational severity rather than a blanket `error`. This is the one\n // true HTTP error boundary (mounted globally in http-server and per\n // sub-router), so logging here guarantees exactly one line per failed\n // request: expected client conditions (e.g. an expired token the client\n // will refresh) stay at `debug`, genuine server faults stay at `error`\n // with a stack. Per-controller boundaries no longer log — they forward\n // here — which removes the historic double-logging and the noise flood.\n logWildoBackendErrorAtClassifiedSeverity(\n this.logger,\n 'HTTP request failed',\n errorToHandle,\n // Boundary-specific extras only — the error's own fields (errorType,\n // statusCode, customMessageReference, operationPath, …) are projected\n // by the helper.\n {\n method: req.method,\n path: req.path,\n },\n );\n\n this.sendErrorResponse(errorToHandle, res);\n };\n }\n\n handleBatchesCronjobsError(error: Error\|WildoError_Backend, executionContext?: ExecutionContext<any>): void {\n const errorToHandle = error instanceof Error ? this.errorBuilder.buildFromStandardError(error, executionContext) : error;\n\n // Batch/cron is a non-HTTP boundary (no `expressErrorHandler` downstream),\n // so this is where the line must be emitted — at the classified severity.\n // The error's own fields are projected by the helper; the stack is attached\n // only when the level is `error`.\n logWildoBackendErrorAtClassifiedSeverity(this.logger, 'Batch/cronjob execution failed', errorToHandle);\n }\n\n\n private sendErrorResponse(saasError: WildoError_Backend, res: Response, initiatorIds?: ExecutionContext_InitiatorIds): void {\n // Double-check if headers are already sent\n if (res.headersSent) {\n this.logger.warn('Cannot send error response - headers already sent', {\n errorType: saasError.type,\n statusCode: saasError.statusCode\n });\n return;\n }\n\n try {\n // Build validationErrors for responses that carry field-level error information.\n // Values can be plain strings (Zod errors) or structured ValidationErrorEntry objects (unique constraints).\n //\n // C3: Intentional extraction order — validationErrors are extracted from the raw error\n // BEFORE sanitizeErrorForClient() runs. This is by design: zodIssues contain field-level\n // validation messages that must appear in the response for form UX, even though the\n // sanitization layer may strip them from `details`. If zodIssues are removed from the\n // sanitization allowlist in the future, validationErrors will still be included because\n // they are extracted independently above the sanitization call.\n let validationErrors: ValidationErrors \| undefined;\n\n // CONFLICT (409): Unique constraint violations — use structured i18n entries\n if (saasError.type === ErrorType.CONFLICT && saasError.context?.fieldName) {\n const fieldName = saasError.context.fieldName as string;\n const duplicateValue = saasError.context.duplicateValue as string \| undefined;\n const customErrorMessage = saasError.context.customErrorMessage as string \| undefined;\n const fallbackMessage = customErrorMessage\n ? customErrorMessage.replace('{fieldName}', fieldName)\n : duplicateValue\n ? `\"${duplicateValue}\" already exists`\n : 'Value already exists';\n\n const entry: ValidationErrorEntry = {\n key: 'validation.unique.conflict',\n message: fallbackMessage,\n params: {\n fieldName,\n ...(duplicateValue ? { value: duplicateValue } : {}),\n },\n };\n validationErrors = { [fieldName]: entry };\n }\n\n // VALIDATION (400): Zod validation errors — plain strings (already localized by Zod)\n if (saasError.type === ErrorType.VALIDATION && saasError.context?.zodIssues) {\n const zodIssues = saasError.context.zodIssues as Array<{ path: (string \| number)[]; message: string }>;\n validationErrors = zodIssues.reduce((acc, issue) => {\n const fieldPath = issue.path.join('.');\n acc[fieldPath] = issue.message;\n return acc;\n }, {} as ValidationErrors);\n }\n\n // H9 fix: Sanitize error at serialization boundary — backend logs retain full context,\n // but the HTTP response strips internal details (emails, stack traces, session IDs, etc.)\n const sanitizedError = this.errorBuilder.sanitizeErrorForClient(saasError);\n const retryAfterSeconds = sanitizedError.context?.retryAfterSeconds;\n if (\n (typeof retryAfterSeconds === 'number' \|\| typeof retryAfterSeconds === 'string')\n && retryAfterSeconds !== ''\n && typeof res.getHeader === 'function'\n && typeof res.setHeader === 'function'\n && res.getHeader('Retry-After') === undefined\n ) {\n res.setHeader('Retry-After', String(retryAfterSeconds));\n }\n\n const response: ErrorResponse = {\n error: {\n type: saasError.type,\n severity: saasError.severity,\n message: saasError.customMessageReference,\n customMessage: saasError.customMessageReference,\n ...(saasError.customMessageReference && { customMessageReference: saasError.customMessageReference }),\n operationPath: saasError.operationPathKey,\n // A stable, operation-specific refusal code (e.g. `LAST_ORGANIZATION_OWNER`) is the\n // contract clients branch on. It is authored in `context.code` and allow-listed by the\n // sanitizer, so it also appears under `details.code`; hoisting it to the top-level field the\n // schema reserves is what lets the customer documentation say \"branch on `error.code`\".\n ...(typeof sanitizedError.context?.code === 'string' && { code: sanitizedError.context.code }),\n // Phase 3 (SD5) — a safe, non-PII support/trace id the user can quote; joins this response to\n // the backend logs + audit for the same request. The error's captured id, else the ambient frame.\n correlationId: saasError.correlationId ?? getCurrentCorrelationId(),\n timestamp: saasError.timestamp.toISOString(),\n initiatorIds: saasError.initiatorIds,\n // executionType: saasError.executionType,\n // stack: saasError.stack,\n ...(sanitizedError.context && { details: sanitizedError.context }),\n // FIX-P6-H1: Include validationErrors at top level for frontend parsing\n ...(validationErrors && { validationErrors }),\n // Phase 1b: Include user guidance if present on the error\n ...(saasError.userGuidance && { userGuidance: saasError.userGuidance }),\n }\n };\n\n res.status(saasError.statusCode).json(response);\n } catch (sendError) {\n // If sending the error response fails, log it but don't throw\n // This prevents Express default HTML error handler from being triggered\n this.logger.error('Failed to send error response', {\n originalError: saasError.type,\n sendError: describeCaughtError(sendError)\n });\n }\n }\n\n\n /\n Get client IP address\n /\n private getClientIpAddress(req: Request): string {\n const xForwardedFor = req.headers[WildoHeaderKeys.FORWARDED_FOR];\n if (xForwardedFor) {\n return Array.isArray(xForwardedFor) ? xForwardedFor[0] : xForwardedFor.split(',')[0];\n }\n\n return req.headers[WildoHeaderKeys.REAL_IP] as string \|\|\n req.connection?.remoteAddress \|\|\n req.socket?.remoteAddress \|\|\n 'unknown';\n }\n\n /\n Create async error wrapper for route handlers\n /\n asyncHandler(fn: Function): (req: Request, res: Response, next: NextFunction) => void {\n return (req: Request, res: Response, next: NextFunction): void => {\n Promise.resolve(fn(req, res, next)).catch(next);\n };\n }\n\n /\n Global unhandled rejection handler\n /\n handleUnhandledRejection(): void {\n process.on('unhandledRejection', (reason: any, promise: Promise<any>) => {\n const errorToHandle = this.errorBuilder.buildError(ErrorType.UNHANDLED_REJECTION, undefined, {\n stack: reason?.stack,\n context: {\n name: reason?.name,\n message: reason?.message,\n promise: promise.toString()\n }\n });\n this.logger.fatal('Unhandled Promise Rejection', { ...errorToHandle });\n\n // Graceful shutdown\n process.exit(1);\n });\n }\n\n /\n Global uncaught exception handler.\n \n Exits the process for every uncaught exception EXCEPT the narrow class\n * isolated by {@link isNonFatalTelemetryPipelineException}. Node's own\n * guidance (\"uncaught exception means unknown state, exit\") assumes the\n * failure came from the host's own request/business logic. A background\n * telemetry batch-flush timer (OTel's `BatchLogRecordProcessor`, ticking\n * every few seconds independently of any request) is a different failure\n * domain: its own state corruption says nothing about whether the host's\n * actual work is safe to continue, and `otel-preload.ts` already commits to\n * \"telemetry failures must never affect host availability\" for SDK-start\n * failures (Audit A-17) — this extends the same policy to a runtime\n * telemetry failure. Every other uncaught exception keeps today's hard-exit\n * behavior unchanged.\n \n NOTE: this method is not wired into any production entrypoint today (no\n * caller reaches `initializeGlobalHandlers`/`handleUncaughtException`) —\n * kept for any future/direct caller, and as the tested home of the shared\n * {@link isNonFatalTelemetryPipelineException} predicate. It cannot simply\n * become \"the\" global handler: it depends on DI (`ErrorBuilderBackendService`\n * via the container), so it is only constructible AFTER\n * `setupSaasBackendInjection()` — every real crash boundary below registers\n * a RAW `process.on(...)` listener at module load, before the container\n * exists, specifically so container-construction failures and early-startup\n * throws are still caught. The listeners that actually apply this predicate\n * in production, all against the SAME exported function:\n \n - `runPlatformServiceEntrypoint` (platform\n * `platform-shared-lib/src/core/startup/platform-service-process-boundary.ts`)\n * — protects `platform-apps-manager`, `platform-crontabs-batches-manager`,\n * `platform-module-registry`. This is the process that actually crashed\n * on 2026-08-06, on `this._flushOneBatch(...).then(...).catch is not a\n * function` inside `@opentelemetry/sdk-logs`'s batch timer.\n * - `WorkerShutdownManagerBackendService.registerSignalHandlers` (this\n * package, `queue/worker-shutdown-manager.backend.service.ts`) — the\n * engine-shared listener reached by every NON-PLATFORM host\n * (backend-api, workers, minions) that runs a queue worker OR has\n * telemetry active, via `StartApplicationBackendService`'s\n * `!isPlatformApplication`/`!isPlatformMode`-gated calls into\n * `ObservabilityBackendService.initialize`/`QueueWorkerInitializer.initialize`.\n * Platform hosts skip both gates entirely and are NOT covered by this\n * listener — they rely solely on the `runPlatformServiceEntrypoint` entry\n * above.\n * - The hand-rolled bootstrap `process.on('uncaughtException'/'unhandledRejection', ...)`\n * blocks in each application entrypoint (Wonder Todos:\n * `backend-api/src/index.ts`, `minions/marketing-scrapper/src/index.ts`,\n * `workers/my-node-worker/src/index.ts`) — these are hand-authored\n * per-app boilerplate, not generated from a shared template, so a future\n * app scaffolded the same way needs the same carve-out applied by hand\n * until this pattern is consolidated into a shared bootstrap helper.\n /\n handleUncaughtException(): void {\n process.on('uncaughtException', (error: Error) => {\n const errorToHandle = this.errorBuilder.buildError(ErrorType.UNCAUGHT_EXCEPTION, undefined, {\n stack: error.stack,\n context: {\n name: error.name,\n message: error.message,\n }\n });\n\n if (isNonFatalTelemetryPipelineException(error)) {\n this.logger.error('Uncaught exception isolated to the telemetry pipeline; host stays up', { ...errorToHandle });\n return;\n }\n\n this.logger.fatal('Uncaught Exception', { ...errorToHandle });\n\n // Graceful shutdown\n process.exit(1);\n });\n }\n\n /\n Initialize global error handlers\n */\n initializeGlobalHandlers(): void {\n this.handleUnhandledRejection();\n this.handleUncaughtException();\n }\n\n}\n"]}
1	+ {"version":3,"file":"error-handler.backend.service.js","sourceRoot":"","sources":["../../../../../src/errors/services/error-handler.backend.service.ts"],"names":[],"mappings":"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","sourcesContent":["import { NextFunction, Request, Response } from 'express';\nimport { inject, injectable } from 'inversify';\nimport { LoggerService } from '~wildo-backend-lib/monitoring/logger/services/logger.service';\nimport { SAAS_SERVICE_TYPES } from '~wildo-backend-lib/inject/models/service-types';\nimport { ErrorBuilderBackendService } from './error-builder.backend.service';\nimport { logWildoBackendErrorAtClassifiedSeverity, describeCaughtError } from '~wildo-backend-lib/errors/utils/error-log-level-classification.backend.utils';\nimport { getCurrentCorrelationId } from '~wildo-backend-lib/runtime/models/request-context.als.backend';\n\n// Import the unified error system\nimport {\n ErrorResponse,\n ErrorType,\n ExecutionContext_InitiatorIds,\n WildoError_Backend,\n ValidationErrors,\n ValidationErrorEntry,\n WildoHeaderKeys,\n} from '@wildo-ai/saas-models';\nimport { ExecutionContext, } from '~wildo-backend-lib/runtime/models/execution-context.backend.schemas';\n\n/*\n The package-path segments that identify Wildo's OTLP export pipeline in a\n * stack trace: the signal processors that own the background flush timers, the\n * exporters they hand batches to, and the shared OTLP serialize/send layer\n * every exporter delegates into.\n \n The membership criterion is NOT \"is this an OpenTelemetry package\" — it is\n * \"can a frame from this package ever appear in the stack of a HOST error?\"\n * Every package listed here answers no: nothing in it invokes a caller-supplied\n * callback, so it is reached only from a telemetry export tick (or from\n * `sdk.shutdown()`). That is what makes a plain \"does the stack mention it\"\n * substring test sound: a frame from one of these packages cannot be\n * routed through, only raised in.\n \n `@opentelemetry/exporter-` is a PREFIX on purpose — it covers the three\n * exporters `otel-preload.ts` wires today (`exporter-trace-otlp-http`,\n * `exporter-metrics-otlp-http`, `exporter-logs-otlp-http`) and every transport\n * sibling (`-proto`, `-grpc`, zipkin, prometheus) a future provider selection\n * could swap in, without this list having to be revisited. Each is export-only\n * by construction.\n \n Kept in step with the package's real OpenTelemetry dependency set by the\n * totality pin in `__tests__/error-handler.backend.service.test.ts`, which\n * enumerates every `@opentelemetry/` entry in this package's own\n `package.json` and fails unless each one is either matched here or named in\n * {@link TELEMETRY_PACKAGES_DELIBERATELY_NOT_ISOLATED}. A name list with no\n * link to whatever owns those names is the drift this carve-out already had\n * once; the pin is that link. It is test-time rather than compile-time because\n * the owning vocabulary is a JSON manifest, not a TypeScript symbol.\n /\nexport const TELEMETRY_EXPORT_PIPELINE_STACK_MARKERS: readonly string[] = [\n // Log signal: `BatchLogRecordProcessor`'s periodic `_flushOneBatch` timer —\n // the frame the 2026-08-06 incident was raised in (see below).\n '@opentelemetry/sdk-logs',\n // Metric signal: `PeriodicExportingMetricReader`'s collect/export interval.\n // Safe as a whole-stack match only while this application declares no\n // OBSERVABLE instrument: an observable callback is host code invoked by the\n // reader, and would put host frames under an `sdk-metrics` frame. None exist\n // (no `createObservable`/`addCallback` call site in engine/, platform/ or\n // examples/ as of 2026-09-09), and such a callback would in any case be\n // telemetry-collection code failing on the collection tick.\n '@opentelemetry/sdk-metrics',\n // Every OTLP/zipkin/prometheus exporter — see the prefix note above.\n '@opentelemetry/exporter-',\n // The shared OTLP serialize + send layer the exporters above delegate into,\n // and where a transport/serialization fault is actually raised.\n '@opentelemetry/otlp-exporter-base',\n '@opentelemetry/otlp-grpc-exporter-base',\n '@opentelemetry/otlp-transformer',\n];\n\n/*\n The OpenTelemetry packages this carve-out deliberately does NOT isolate, each\n * with the reason. This is not a leftover list: it is the other half of the\n * totality pin, so that adding an OTel dependency forces a decision instead of\n * silently landing outside both sets.\n \n The reason is the same for the whole first group and it is the one that\n * matters: these packages invoke host code, so their frames appear in the\n * stack of ordinary host crashes. Matching them would not widen a telemetry\n * carve-out — it would suppress genuine host faults.\n /\nexport const TELEMETRY_PACKAGES_DELIBERATELY_NOT_ISOLATED: readonly string[] = [\n // --- Runs host code, so a host crash's stack passes through it ---\n // `Tracer.startActiveSpan(name, fn)` calls `fn` — the host's own work — so\n // under HTTP auto-instrumentation practically EVERY synchronous server-side\n // crash carries an `sdk-trace-base` frame. Matching it would carve out the\n // whole application. The consequence is a stated gap, not an oversight: a\n // fault raised INSIDE `BatchSpanProcessor` itself (the span-tier analogue of\n // the 2026-08-06 log-tier incident) still hard-exits. Closing it needs a\n // discriminator this predicate does not have — either \"raised in the TOP\n // frame\" or \"the stack shows a timer tick\" — and neither is worth the\n // false-negative risk until a span-tier incident is actually evidenced. The\n // span EXPORT half is already covered, via `exporter-trace-otlp-http`.\n '@opentelemetry/sdk-trace-base',\n '@opentelemetry/sdk-trace-node',\n // Instrumentation WRAPS host handlers, middleware and driver calls; its\n // frames sit directly beneath host frames on every instrumented request.\n '@opentelemetry/instrumentation',\n '@opentelemetry/instrumentation-express',\n '@opentelemetry/instrumentation-http',\n '@opentelemetry/instrumentation-mongoose',\n '@opentelemetry/instrumentation-redis',\n '@opentelemetry/auto-instrumentations-node',\n // `context.with(ctx, fn)` runs the host callback; the API/core/context tier\n // is on the synchronous path of anything traced.\n '@opentelemetry/api',\n '@opentelemetry/api-logs',\n '@opentelemetry/core',\n // --- Not an export tick ---\n // The SDK facade. Its one dangerous call, `sdk.start()`, is already guarded\n // where it happens (`otel-preload.ts`, Audit A-17) and is a BOOT failure: a\n // host that cannot start telemetry has no export tick to isolate.\n '@opentelemetry/sdk-node',\n // Static data / attribute helpers, resolved at startup. Nothing periodic to\n // isolate, and their frames appear during host bootstrap.\n '@opentelemetry/resources',\n '@opentelemetry/semantic-conventions',\n];\n\n/\n Isolates an uncaught exception RAISED INSIDE the OTLP export pipeline —\n * the background machinery that flushes logs, metrics and spans to the\n * collector on a timer, independent of any request — from every other uncaught\n * exception, which still hard-exits via the default path.\n \n WHAT THIS SUPPRESSES: a failure whose stack mentions one of\n * {@link TELEMETRY_EXPORT_PIPELINE_STACK_MARKERS}. Those packages never call\n * host code (see that constant's note), so a stack that mentions one of them\n * is a stack that was raised in one of them.\n \n WHAT IT MUST NOT SUPPRESS, and does not: anything raised in the host's own\n * request/business logic, anything raised in OTel INSTRUMENTATION (which wraps\n * host code), and anything in the trace/context tier a host stack routes\n * through — see {@link TELEMETRY_PACKAGES_DELIBERATELY_NOT_ISOLATED}. A\n * carve-out that swallowed a genuine fault into a silently degraded process\n * would be strictly worse than the crash it prevents, which is why the\n * criterion is \"cannot be on a host stack\" rather than \"is telemetry\".\n \n Root cause (2026-08-06): the timer callback in\n * `BatchLogRecordProcessorBase` does `this._flushOneBatch().then(...).catch(...)`\n * on a fixed interval, independent of any request. Observed in production dev\n * use as `TypeError: this._flushOneBatch(...).then(...).catch is not a\n * function`. The processor's own promise chain broke down before its internal\n * `globalErrorHandler` safety net could catch it, so the failure escaped as a\n * process-level uncaught exception — killing an otherwise-healthy host over a\n * background telemetry-export housekeeping tick.\n \n WIDENED 2026-09-09. The original predicate matched the single literal\n * `@opentelemetry/sdk-logs`, which is where that one incident happened to be\n * raised — so the identical promise-chain/transport failure arriving from the\n * METRIC reader or from ANY of the three OTLP exporters was not isolated and\n * hard-exited the host. Keying a carve-out on one package NAME makes its reach\n * an accident of which pipeline failed first; the property that actually\n * distinguishes the case is the export pipeline itself.\n /\nexport function isNonFatalTelemetryPipelineException(error: Error): boolean {\n if (typeof error.stack !== 'string') return false;\n const stack = error.stack;\n return TELEMETRY_EXPORT_PIPELINE_STACK_MARKERS.some((marker) => stack.includes(marker));\n}\n\n/\n Unified Error Handler Service\n * Handles all errors using the new unified error management system\n /\n@injectable()\nexport class ErrorHandlerService {\n protected logDebug: (message: string, context?: Record<string, unknown>) => void;\n\n constructor(\n @inject(SAAS_SERVICE_TYPES.Logger) private logger: LoggerService,\n @inject(SAAS_SERVICE_TYPES.ErrorBuilderService) private errorBuilder: ErrorBuilderBackendService\n ) {\n this.logDebug = this.logger.debugByType('ErrorHandlerService');\n this.logger.setDebugTypeLogging('ErrorHandlerService', false);\n }\n\n /\n Express error handling middleware with unified error system\n * Express requires exactly 4 parameters: (err, req, res, next)\n /\n expressErrorHandler(): (error: Error\|WildoError_Backend, req: Request, res: Response, next: NextFunction) => void {\n return (error: Error\|WildoError_Backend, req: Request, res: Response, next: NextFunction): void => {\n // Check if response has already been sent\n if (res.headersSent) {\n // If headers are already sent, delegate to Express default handler\n return next(error);\n }\n\n // Extract executionContext from request if available\n const executionContext = (req as any).executionContext as ExecutionContext<any> \| undefined;\n\n const errorToHandle = error instanceof Error\n ? this.errorBuilder.buildFromStandardError(error, executionContext)\n : error;\n errorToHandle.ipAddress = this.getClientIpAddress(req);\n\n // Single, central log for every HTTP error — emitted at the classified\n // operational severity rather than a blanket `error`. This is the one\n // true HTTP error boundary (mounted globally in http-server and per\n // sub-router), so logging here guarantees exactly one line per failed\n // request: expected client conditions (e.g. an expired token the client\n // will refresh) stay at `debug`, genuine server faults stay at `error`\n // with a stack. Per-controller boundaries no longer log — they forward\n // here — which removes the historic double-logging and the noise flood.\n logWildoBackendErrorAtClassifiedSeverity(\n this.logger,\n 'HTTP request failed',\n errorToHandle,\n // Boundary-specific extras only — the error's own fields (errorType,\n // statusCode, customMessageReference, operationPath, …) are projected\n // by the helper.\n {\n method: req.method,\n path: req.path,\n },\n );\n\n this.sendErrorResponse(errorToHandle, res);\n };\n }\n\n handleBatchesCronjobsError(error: Error\|WildoError_Backend, executionContext?: ExecutionContext<any>): void {\n const errorToHandle = error instanceof Error ? this.errorBuilder.buildFromStandardError(error, executionContext) : error;\n\n // Batch/cron is a non-HTTP boundary (no `expressErrorHandler` downstream),\n // so this is where the line must be emitted — at the classified severity.\n // The error's own fields are projected by the helper; the stack is attached\n // only when the level is `error`.\n logWildoBackendErrorAtClassifiedSeverity(this.logger, 'Batch/cronjob execution failed', errorToHandle);\n }\n\n\n private sendErrorResponse(saasError: WildoError_Backend, res: Response, initiatorIds?: ExecutionContext_InitiatorIds): void {\n // Double-check if headers are already sent\n if (res.headersSent) {\n this.logger.warn('Cannot send error response - headers already sent', {\n errorType: saasError.type,\n statusCode: saasError.statusCode\n });\n return;\n }\n\n try {\n // Build validationErrors for responses that carry field-level error information.\n // Values can be plain strings (Zod errors) or structured ValidationErrorEntry objects (unique constraints).\n //\n // C3: Intentional extraction order — validationErrors are extracted from the raw error\n // BEFORE sanitizeErrorForClient() runs. This is by design: zodIssues contain field-level\n // validation messages that must appear in the response for form UX, even though the\n // sanitization layer may strip them from `details`. If zodIssues are removed from the\n // sanitization allowlist in the future, validationErrors will still be included because\n // they are extracted independently above the sanitization call.\n let validationErrors: ValidationErrors \| undefined;\n\n // CONFLICT (409): Unique constraint violations — use structured i18n entries\n if (saasError.type === ErrorType.CONFLICT && saasError.context?.fieldName) {\n const fieldName = saasError.context.fieldName as string;\n const duplicateValue = saasError.context.duplicateValue as string \| undefined;\n const customErrorMessage = saasError.context.customErrorMessage as string \| undefined;\n const fallbackMessage = customErrorMessage\n ? customErrorMessage.replace('{fieldName}', fieldName)\n : duplicateValue\n ? `\"${duplicateValue}\" already exists`\n : 'Value already exists';\n\n const entry: ValidationErrorEntry = {\n key: 'validation.unique.conflict',\n message: fallbackMessage,\n params: {\n fieldName,\n ...(duplicateValue ? { value: duplicateValue } : {}),\n },\n };\n validationErrors = { [fieldName]: entry };\n }\n\n // VALIDATION (400): Zod validation errors — plain strings (already localized by Zod)\n if (saasError.type === ErrorType.VALIDATION && saasError.context?.zodIssues) {\n const zodIssues = saasError.context.zodIssues as Array<{ path: (string \| number)[]; message: string }>;\n validationErrors = zodIssues.reduce((acc, issue) => {\n const fieldPath = issue.path.join('.');\n acc[fieldPath] = issue.message;\n return acc;\n }, {} as ValidationErrors);\n }\n\n // H9 fix: Sanitize error at serialization boundary — backend logs retain full context,\n // but the HTTP response strips internal details (emails, stack traces, session IDs, etc.)\n const sanitizedError = this.errorBuilder.sanitizeErrorForClient(saasError);\n const retryAfterSeconds = sanitizedError.context?.retryAfterSeconds;\n if (\n (typeof retryAfterSeconds === 'number' \|\| typeof retryAfterSeconds === 'string')\n && retryAfterSeconds !== ''\n && typeof res.getHeader === 'function'\n && typeof res.setHeader === 'function'\n && res.getHeader('Retry-After') === undefined\n ) {\n res.setHeader('Retry-After', String(retryAfterSeconds));\n }\n\n const response: ErrorResponse = {\n error: {\n type: saasError.type,\n severity: saasError.severity,\n message: saasError.customMessageReference,\n customMessage: saasError.customMessageReference,\n ...(saasError.customMessageReference && { customMessageReference: saasError.customMessageReference }),\n operationPath: saasError.operationPathKey,\n // A stable, operation-specific refusal code (e.g. `LAST_ORGANIZATION_OWNER`) is the\n // contract clients branch on. It is authored in `context.code` and allow-listed by the\n // sanitizer, so it also appears under `details.code`; hoisting it to the top-level field the\n // schema reserves is what lets the customer documentation say \"branch on `error.code`\".\n ...(typeof sanitizedError.context?.code === 'string' && { code: sanitizedError.context.code }),\n // Phase 3 (SD5) — a safe, non-PII support/trace id the user can quote; joins this response to\n // the backend logs + audit for the same request. The error's captured id, else the ambient frame.\n correlationId: saasError.correlationId ?? getCurrentCorrelationId(),\n timestamp: saasError.timestamp.toISOString(),\n initiatorIds: saasError.initiatorIds,\n // executionType: saasError.executionType,\n // stack: saasError.stack,\n ...(sanitizedError.context && { details: sanitizedError.context }),\n // FIX-P6-H1: Include validationErrors at top level for frontend parsing\n ...(validationErrors && { validationErrors }),\n // Phase 1b: Include user guidance if present on the error\n ...(saasError.userGuidance && { userGuidance: saasError.userGuidance }),\n }\n };\n\n res.status(saasError.statusCode).json(response);\n } catch (sendError) {\n // If sending the error response fails, log it but don't throw\n // This prevents Express default HTML error handler from being triggered\n this.logger.error('Failed to send error response', {\n originalError: saasError.type,\n sendError: describeCaughtError(sendError)\n });\n }\n }\n\n\n /\n Get client IP address\n /\n private getClientIpAddress(req: Request): string {\n const xForwardedFor = req.headers[WildoHeaderKeys.FORWARDED_FOR];\n if (xForwardedFor) {\n return Array.isArray(xForwardedFor) ? xForwardedFor[0] : xForwardedFor.split(',')[0];\n }\n\n return req.headers[WildoHeaderKeys.REAL_IP] as string \|\|\n req.connection?.remoteAddress \|\|\n req.socket?.remoteAddress \|\|\n 'unknown';\n }\n\n /\n Create async error wrapper for route handlers\n /\n asyncHandler(fn: Function): (req: Request, res: Response, next: NextFunction) => void {\n return (req: Request, res: Response, next: NextFunction): void => {\n Promise.resolve(fn(req, res, next)).catch(next);\n };\n }\n\n /\n Global unhandled rejection handler\n /\n handleUnhandledRejection(): void {\n process.on('unhandledRejection', (reason: any, promise: Promise<any>) => {\n const errorToHandle = this.errorBuilder.buildError(ErrorType.UNHANDLED_REJECTION, undefined, {\n stack: reason?.stack,\n context: {\n name: reason?.name,\n message: reason?.message,\n promise: promise.toString()\n }\n });\n this.logger.fatal('Unhandled Promise Rejection', { ...errorToHandle });\n\n // Graceful shutdown\n process.exit(1);\n });\n }\n\n /\n Global uncaught exception handler.\n \n Exits the process for every uncaught exception EXCEPT the narrow class\n * isolated by {@link isNonFatalTelemetryPipelineException}. Node's own\n * guidance (\"uncaught exception means unknown state, exit\") assumes the\n * failure came from the host's own request/business logic. A background\n * telemetry export tick (OTel's `BatchLogRecordProcessor` or\n * `PeriodicExportingMetricReader`, and the OTLP exporters they feed, ticking\n * every few seconds independently of any request) is a different failure\n * domain: its own state corruption says nothing about whether the host's\n * actual work is safe to continue, and `otel-preload.ts` already commits to\n * \"telemetry failures must never affect host availability\" for SDK-start\n * failures (Audit A-17) — this extends the same policy to a runtime\n * telemetry failure. Every other uncaught exception keeps today's hard-exit\n * behavior unchanged.\n \n NOTE: this method is not wired into any production entrypoint today (no\n * caller reaches `initializeGlobalHandlers`/`handleUncaughtException`) —\n * kept for any future/direct caller, and as the tested home of the shared\n * {@link isNonFatalTelemetryPipelineException} predicate. It cannot simply\n * become \"the\" global handler: it depends on DI (`ErrorBuilderBackendService`\n * via the container), so it is only constructible AFTER\n * `setupSaasBackendInjection()` — every real crash boundary below registers\n * a RAW `process.on(...)` listener at module load, before the container\n * exists, specifically so container-construction failures and early-startup\n * throws are still caught. The listeners that actually apply this predicate\n * in production, all against the SAME exported function:\n \n - `runPlatformServiceEntrypoint` (platform\n * `platform-shared-lib/src/core/startup/platform-service-process-boundary.ts`)\n * — protects `platform-apps-manager`, `platform-crontabs-batches-manager`,\n * `platform-module-registry`. This is the process that actually crashed\n * on 2026-08-06, on `this._flushOneBatch(...).then(...).catch is not a\n * function` inside `@opentelemetry/sdk-logs`'s batch timer.\n * - `WorkerShutdownManagerBackendService.registerSignalHandlers` (this\n * package, `queue/worker-shutdown-manager.backend.service.ts`) — the\n * engine-shared listener reached by every NON-PLATFORM host\n * (backend-api, workers, minions) that runs a queue worker OR has\n * telemetry active, via `StartApplicationBackendService`'s\n * `!isPlatformApplication`/`!isPlatformMode`-gated calls into\n * `ObservabilityBackendService.initialize`/`QueueWorkerInitializer.initialize`.\n * Platform hosts skip both gates entirely and are NOT covered by this\n * listener — they rely solely on the `runPlatformServiceEntrypoint` entry\n * above.\n * - The hand-rolled bootstrap `process.on('uncaughtException'/'unhandledRejection', ...)`\n * blocks in each application entrypoint (Wonder Todos:\n * `backend-api/src/index.ts`, `minions/marketing-scrapper/src/index.ts`,\n * `workers/my-node-worker/src/index.ts`) — these are hand-authored\n * per-app boilerplate, not generated from a shared template, so a future\n * app scaffolded the same way needs the same carve-out applied by hand\n * until this pattern is consolidated into a shared bootstrap helper.\n /\n handleUncaughtException(): void {\n process.on('uncaughtException', (error: Error) => {\n const errorToHandle = this.errorBuilder.buildError(ErrorType.UNCAUGHT_EXCEPTION, undefined, {\n stack: error.stack,\n context: {\n name: error.name,\n message: error.message,\n }\n });\n\n if (isNonFatalTelemetryPipelineException(error)) {\n this.logger.error('Uncaught exception isolated to the telemetry pipeline; host stays up', { ...errorToHandle });\n return;\n }\n\n this.logger.fatal('Uncaught Exception', { ...errorToHandle });\n\n // Graceful shutdown\n process.exit(1);\n });\n }\n\n /\n Initialize global error handlers\n */\n initializeGlobalHandlers(): void {\n this.handleUnhandledRejection();\n this.handleUncaughtException();\n }\n\n}\n"]}

package/dist/esm/errors/services/rate-limit.backend.service.d.ts CHANGED Viewed

@@ -202,6 +202,72 @@ export declare class RateLimitBackendService {
      */
     /** @wildo_source:part:end saas.backend.rate-limit-service.check-policy */
     checkPolicy(req: Request, res: Response, policy: RateLimitConfiguration, scopeKey: string, organizationId?: string, clientIdOverride?: string): Promise<void>;
+    /**
+     * Enforce a declared policy for a caller that has NO express request/response —
+     * the non-HTTP planes that dispatch a resource operation directly. There are TWO today, and
+     * they do not share a core: the MCP `tools/call` plane
+     * (`McpServerBackendService.assertOperationRateLimitPolicy`, plus any future transport that
+     * re-uses that core) and the agent function-tool plane
+     * (`assertDeclaredOperationRateLimit` in `function-tools.backend.definitions.ts`, reached from a
+     * conversational turn and therefore from A2A). An earlier revision of this sentence named only
+     * the first and framed the second as "any future transport that re-uses
+     * `McpServerBackendService`" — which the function-tool plane does not, and that framing is part
+     * of why it went unnoticed. Expect further planes, and expect them to arrive from elsewhere.
+     *
+     * ## Why a second entry point rather than a fabricated `req`/`res`
+     *
+     * {@link checkPolicy} is an HTTP-seam method in two load-bearing ways: it derives the
+     * counter's client identifier from the request IP, and it publishes the outcome as
+     * `X-RateLimit-*` / `Retry-After` RESPONSE HEADERS. Neither exists on a JSON-RPC tool
+     * dispatch — the MCP core is deliberately transport-agnostic, so it holds no `res` to
+     * write headers onto, and the IP is the wrong identity axis for a credentialed agent
+     * anyway (see the subject-key discussion at the call site). Handing it a stub `req`/`res`
+     * would make the throttle key on the literal string the IP extractor returns for a
+     * request-shaped object it was never given — i.e. ONE bucket for every agent on the
+     * planet, which is worse than no enforcement because it looks enforced.
+     *
+     * So the WINDOW ARITHMETIC is shared (`evaluatePolicyWindows` — the AND semantics, the
+     * environment relaxation, the custom-window dedupe, the latest-tripped `Retry-After`
+     * pick) and only the identity + reporting halves differ. There must never be a second
+     * implementation of "what does this policy mean"; there are legitimately two answers to
+     * "who is the client, and how do we tell them".
+     *
+     * ## Failure posture: the SAME as HTTP, deliberately
+     *
+     * A limiter outage propagates rather than being swallowed, exactly as it does for
+     * {@link checkPolicy} / {@link checkPolicyForVariant}. An AUTHORED per-endpoint policy is
+     * a statement the application made about that endpoint; degrading it to "unbounded" on
+     * one plane and to a 500 on the other would make the same declaration mean two different
+     * things. (Contrast `assertExternalTurnWithinRate`, the framework-default per-principal
+     * abuse throttle, which fails OPEN — nobody declared it, so it must never be the reason
+     * an external endpoint stops working.)
+     *
+     * @param policy — the declared policy. No enforced window ⇒ no-op, zero Redis traffic.
+     * @param scopeKey — author-supplied namespace, composed with `subjectKey` into the Redis key.
+     * @param subjectKey — WHO is counted. The caller owns this choice; it replaces the IP
+     *   that {@link checkPolicy} would derive, and it must be a server-verified identity —
+     *   never a value the caller (or a model) supplied.
+     * @param organizationId — optional tenant scope forwarded to the Redis key namespace.
+     * @throws RATE_LIMIT (429) carrying `context.retryAfterSeconds`, the same envelope the
+     *   HTTP seam throws, so one refusal vocabulary covers both planes.
+     */
+    checkPolicyForSubject(policy: RateLimitConfiguration, scopeKey: string, subjectKey: string, organizationId?: string): Promise<void>;
+    /**
+     * Count one request against every window a policy declares, and report the two facts
+     * every caller needs: the TIGHTEST still-active window (for `X-RateLimit-*`) and the
+     * LATEST tripped one (for `Retry-After`).
+     *
+     * Extracted from {@link checkPolicy} when {@link checkPolicyForSubject} was added, so the
+     * meaning of a declared policy has exactly one implementation. Declared windows are
+     * AND-ed — recovery requires EVERY exceeded window to reset, not just the shortest — which
+     * is why the retry hint is the latest reset rather than the first trip.
+     *
+     * A policy with no enforced window yields `{}` without touching Redis (the no-policy fast
+     * path the resource-variant seam relies on, since most operations declare nothing).
+     *
+     * @param identifier — `${scopeKey}:${clientOrSubjectId}`; the window name is appended per key.
+     */
+    private evaluatePolicyWindows;
     /**
      * Pre-flight enforcement for resource operations — the consumer behind
      * the `rateLimit?` field on `API_CALL` / `API_CALL_WITH_CALLBACK` variants.

package/dist/esm/errors/services/rate-limit.backend.service.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"rate-limit.backend.service.d.ts","sourceRoot":"","sources":["../../../../../src/errors/services/rate-limit.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH,OAAO,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,EACL,2BAA2B,EAC3B,SAAS,EACT,4BAA4B,EAE5B,KAAK,sBAAsB,EAC3B,KAAK,YAAY,EAClB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,YAAY,EAAE,MAAM,qDAAqD,CAAC;AAEnF,OAAO,EAAE,uBAAuB,EAAE,MAAM,sEAAsE,CAAC;AAE/G,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AA0B7E,qBACa,uBAAuB;IAES,OAAO,CAAC,QAAQ,CAAC,YAAY;IACtB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAChC,OAAO,CAAC,QAAQ,CAAC,gBAAgB;gBAFpB,YAAY,EAAE,YAAY,EACnB,YAAY,EAAE,0BAA0B,EAC3C,gBAAgB,EAAE,uBAAuB;IAGzG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2DG;IACU,cAAc,CACzB,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,EACrB,cAAc,CAAC,EAAE,MAAM,EACvB,eAAe,CAAC,EAAE,MAAM,EACxB,OAAO,CAAC,EAAE;QACR,SAAS,CAAC,EAAE,SAAS,CAAC;QACtB,sBAAsB,CAAC,EAAE,2BAA2B,CAAC;QACrD,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACxC,GACA,OAAO,CAAC,IAAI,CAAC;IA6BhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgEG;IACH,0EAA0E;IAC7D,WAAW,CACtB,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,MAAM,EAAE,sBAAsB,EAC9B,QAAQ,EAAE,MAAM,EAChB,cAAc,CAAC,EAAE,MAAM,EACvB,gBAAgB,CAAC,EAAE,MAAM,GACxB,OAAO,CAAC,IAAI,CAAC;~~IA8FhB~~;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACU,qBAAqB,CAChC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE;QACP,QAAQ,CAAC,WAAW,EAAE,4BAA4B,CAAC;QACnD,QAAQ,CAAC,kBAAkB,EAAE,YAAY,CAAC;QAO1C,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;QACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,sBAAsB,CAAC;KAC7C,GACA,OAAO,CAAC,IAAI,CAAC;IAehB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAAO,CAAC,aAAa;IAsDrB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,uBAAuB;YAIjB,mBAAmB;CAmBlC"}
1	+ {"version":3,"file":"rate-limit.backend.service.d.ts","sourceRoot":"","sources":["../../../../../src/errors/services/rate-limit.backend.service.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4DG;AAEH,OAAO,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,EACL,2BAA2B,EAC3B,SAAS,EACT,4BAA4B,EAE5B,KAAK,sBAAsB,EAC3B,KAAK,YAAY,EAClB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,YAAY,EAAE,MAAM,qDAAqD,CAAC;AAEnF,OAAO,EAAE,uBAAuB,EAAE,MAAM,sEAAsE,CAAC;AAE/G,OAAO,EAAE,0BAA0B,EAAE,MAAM,iCAAiC,CAAC;AA0B7E,qBACa,uBAAuB;IAES,OAAO,CAAC,QAAQ,CAAC,YAAY;IACtB,OAAO,CAAC,QAAQ,CAAC,YAAY;IAChC,OAAO,CAAC,QAAQ,CAAC,gBAAgB;gBAFpB,YAAY,EAAE,YAAY,EACnB,YAAY,EAAE,0BAA0B,EAC3C,gBAAgB,EAAE,uBAAuB;IAGzG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2DG;IACU,cAAc,CACzB,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,MAAM,EACrB,cAAc,CAAC,EAAE,MAAM,EACvB,eAAe,CAAC,EAAE,MAAM,EACxB,OAAO,CAAC,EAAE;QACR,SAAS,CAAC,EAAE,SAAS,CAAC;QACtB,sBAAsB,CAAC,EAAE,2BAA2B,CAAC;QACrD,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACxC,GACA,OAAO,CAAC,IAAI,CAAC;IA6BhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgEG;IACH,0EAA0E;IAC7D,WAAW,CACtB,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,MAAM,EAAE,sBAAsB,EAC9B,QAAQ,EAAE,MAAM,EAChB,cAAc,CAAC,EAAE,MAAM,EACvB,gBAAgB,CAAC,EAAE,MAAM,GACxB,OAAO,CAAC,IAAI,CAAC;IAiEhB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgDG;IACU,qBAAqB,CAChC,MAAM,EAAE,sBAAsB,EAC9B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,EAClB,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC,IAAI,CAAC;IAehB;;;;;;;;;;;;;;OAcG;YACW,qBAAqB;IAoCnC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACU,qBAAqB,CAChC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE;QACP,QAAQ,CAAC,WAAW,EAAE,4BAA4B,CAAC;QACnD,QAAQ,CAAC,kBAAkB,EAAE,YAAY,CAAC;QAO1C,QAAQ,CAAC,mBAAmB,EAAE,OAAO,CAAC;QACtC,QAAQ,CAAC,SAAS,CAAC,EAAE,sBAAsB,CAAC;KAC7C,GACA,OAAO,CAAC,IAAI,CAAC;IAehB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAAO,CAAC,aAAa;IAsDrB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,uBAAuB;YAIjB,mBAAmB;CAmBlC"}

package/dist/esm/errors/services/rate-limit.backend.service.js CHANGED Viewed

@@ -237,32 +237,8 @@ let RateLimitBackendService = class RateLimitBackendService {
      */
     /** @wildo_source:part:end saas.backend.rate-limit-service.check-policy */
     async checkPolicy(req, res, policy, scopeKey, organizationId, clientIdOverride) {
-        const windows = this.deriveWindows(policy);
-        if (windows.length === 0) {
-            return;
-        }
         const clientId = clientIdOverride ?? getClientIpFromRequest(req);
-        const identifier = `${scopeKey}:${clientId}`;
-        // Track the tightest active window (fewest `remaining` slots) for
-        // headers, and the latest tripped window for retry-after. Declared
-        // windows are AND-ed, so recovery requires every exceeded window to
-        // reset, not just the shortest one.
-        let tightestActive;
-        let latestTripped;
-        for (const window of windows) {
-            const key = `${identifier}:${window.name}`;
-            const count = await this.redisService.incrementRateLimit(key, window.seconds, organizationId);
-            const resetSeconds = await this.resolveRateLimitTtl(key, organizationId, window.seconds);
-            const remaining = Math.max(0, window.max - count);
-            if (count > window.max) {
-                if (!latestTripped || resetSeconds > latestTripped.retryAfterSeconds) {
-                    latestTripped = { retryAfterSeconds: resetSeconds };
-                }
-            }
-            if (!tightestActive || remaining < tightestActive.remaining) {
-                tightestActive = { max: window.max, remaining, resetSeconds };
-            }
-        }
+        const { tightestActive, latestTripped } = await this.evaluatePolicyWindows(policy, `${scopeKey}:${clientId}`, organizationId);
         if (tightestActive) {
             // F-9 compare-and-set guard. Multiple `checkPolicy` invocations can
             // run on the same response within a single request lifecycle — the
@@ -322,6 +298,107 @@ let RateLimitBackendService = class RateLimitBackendService {
             });
         }
     }
+    /**
+     * Enforce a declared policy for a caller that has NO express request/response —
+     * the non-HTTP planes that dispatch a resource operation directly. There are TWO today, and
+     * they do not share a core: the MCP `tools/call` plane
+     * (`McpServerBackendService.assertOperationRateLimitPolicy`, plus any future transport that
+     * re-uses that core) and the agent function-tool plane
+     * (`assertDeclaredOperationRateLimit` in `function-tools.backend.definitions.ts`, reached from a
+     * conversational turn and therefore from A2A). An earlier revision of this sentence named only
+     * the first and framed the second as "any future transport that re-uses
+     * `McpServerBackendService`" — which the function-tool plane does not, and that framing is part
+     * of why it went unnoticed. Expect further planes, and expect them to arrive from elsewhere.
+     *
+     * ## Why a second entry point rather than a fabricated `req`/`res`
+     *
+     * {@link checkPolicy} is an HTTP-seam method in two load-bearing ways: it derives the
+     * counter's client identifier from the request IP, and it publishes the outcome as
+     * `X-RateLimit-*` / `Retry-After` RESPONSE HEADERS. Neither exists on a JSON-RPC tool
+     * dispatch — the MCP core is deliberately transport-agnostic, so it holds no `res` to
+     * write headers onto, and the IP is the wrong identity axis for a credentialed agent
+     * anyway (see the subject-key discussion at the call site). Handing it a stub `req`/`res`
+     * would make the throttle key on the literal string the IP extractor returns for a
+     * request-shaped object it was never given — i.e. ONE bucket for every agent on the
+     * planet, which is worse than no enforcement because it looks enforced.
+     *
+     * So the WINDOW ARITHMETIC is shared (`evaluatePolicyWindows` — the AND semantics, the
+     * environment relaxation, the custom-window dedupe, the latest-tripped `Retry-After`
+     * pick) and only the identity + reporting halves differ. There must never be a second
+     * implementation of "what does this policy mean"; there are legitimately two answers to
+     * "who is the client, and how do we tell them".
+     *
+     * ## Failure posture: the SAME as HTTP, deliberately
+     *
+     * A limiter outage propagates rather than being swallowed, exactly as it does for
+     * {@link checkPolicy} / {@link checkPolicyForVariant}. An AUTHORED per-endpoint policy is
+     * a statement the application made about that endpoint; degrading it to "unbounded" on
+     * one plane and to a 500 on the other would make the same declaration mean two different
+     * things. (Contrast `assertExternalTurnWithinRate`, the framework-default per-principal
+     * abuse throttle, which fails OPEN — nobody declared it, so it must never be the reason
+     * an external endpoint stops working.)
+     *
+     * @param policy — the declared policy. No enforced window ⇒ no-op, zero Redis traffic.
+     * @param scopeKey — author-supplied namespace, composed with `subjectKey` into the Redis key.
+     * @param subjectKey — WHO is counted. The caller owns this choice; it replaces the IP
+     *   that {@link checkPolicy} would derive, and it must be a server-verified identity —
+     *   never a value the caller (or a model) supplied.
+     * @param organizationId — optional tenant scope forwarded to the Redis key namespace.
+     * @throws RATE_LIMIT (429) carrying `context.retryAfterSeconds`, the same envelope the
+     *   HTTP seam throws, so one refusal vocabulary covers both planes.
+     */
+    async checkPolicyForSubject(policy, scopeKey, subjectKey, organizationId) {
+        const { latestTripped } = await this.evaluatePolicyWindows(policy, `${scopeKey}:${subjectKey}`, organizationId);
+        if (!latestTripped) {
+            return;
+        }
+        throw this.errorBuilder.buildError(ErrorType.RATE_LIMIT, undefined, {
+            customMessageReference: ErrorCustomMessageReference.RATE_LIMIT,
+            context: {
+                // Diagnostic (log-only) on the HTTP seam; on a header-less plane it is ALSO the only
+                // way the transport can learn the retry hint, so it is read back off the thrown error.
+                retryAfterSeconds: latestTripped.retryAfterSeconds,
+            },
+        });
+    }
+    /**
+     * Count one request against every window a policy declares, and report the two facts
+     * every caller needs: the TIGHTEST still-active window (for `X-RateLimit-*`) and the
+     * LATEST tripped one (for `Retry-After`).
+     *
+     * Extracted from {@link checkPolicy} when {@link checkPolicyForSubject} was added, so the
+     * meaning of a declared policy has exactly one implementation. Declared windows are
+     * AND-ed — recovery requires EVERY exceeded window to reset, not just the shortest — which
+     * is why the retry hint is the latest reset rather than the first trip.
+     *
+     * A policy with no enforced window yields `{}` without touching Redis (the no-policy fast
+     * path the resource-variant seam relies on, since most operations declare nothing).
+     *
+     * @param identifier — `${scopeKey}:${clientOrSubjectId}`; the window name is appended per key.
+     */
+    async evaluatePolicyWindows(policy, identifier, organizationId) {
+        const windows = this.deriveWindows(policy);
+        if (windows.length === 0) {
+            return {};
+        }
+        let tightestActive;
+        let latestTripped;
+        for (const window of windows) {
+            const key = `${identifier}:${window.name}`;
+            const count = await this.redisService.incrementRateLimit(key, window.seconds, organizationId);
+            const resetSeconds = await this.resolveRateLimitTtl(key, organizationId, window.seconds);
+            const remaining = Math.max(0, window.max - count);
+            if (count > window.max) {
+                if (!latestTripped || resetSeconds > latestTripped.retryAfterSeconds) {
+                    latestTripped = { retryAfterSeconds: resetSeconds };
+                }
+            }
+            if (!tightestActive || remaining < tightestActive.remaining) {
+                tightestActive = { max: window.max, remaining, resetSeconds };
+            }
+        }
+        return { tightestActive, latestTripped };
+    }
     /**
      * Pre-flight enforcement for resource operations — the consumer behind
      * the `rateLimit?` field on `API_CALL` / `API_CALL_WITH_CALLBACK` variants.