@onlineapps/error-handler-core 3.0.0 → 3.1.0

package/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to this package. Follows [Keep a Changelog](https://keepacha
 
 ## [Unreleased]
 
+## [3.1.0] — 2026-09-25
+
+### Added — třída `ErrorTypes.DECLINED`: pravidlo práci zakázalo (d.831)
+
+Každá dosavadní třída pojmenovává způsob, jakým se práce NEPOVEDLA. `DECLINED` říká,
+že se dělat neměla: doklad už odeslaný byl, položku zdroj neprojednává. Je koncová,
+není to selhání, neopakuje se a nejde do DLQ — `ErrorHandlerCore` pro ni vrací verdikt
+`declined`, který je (stejně jako `dlq`) klasifikací pro volajícího, ne cestou, kterou
+by tenhle balíček sám šel.
+
+Deklaruje ji VYHAZUJÍCÍ přes `error.type`; ze stavového kódu se neodvozuje. Tabulka
+kódů zůstává beze změny — každé jiné `409` je dál `BUSINESS`, protože týž stav nese
+oba významy a jen vyhazující ví, který z nich myslel.
+
+Rozhodnutí vlastníka:
+`api/docs/governance/confirmations/workflow-failed-status-projection.md` 004
+(odmítnutí bránou komba není selhání běhu). Závažnost logu `info`, protože to není
+incident; mapa kategorií v `UnifiedLogSchema` ji kontroluje při načtení, takže třída
+bez závažnosti balíček neprojde.
+
 ## [3.0.0] — 2026-09-16
 
 ### Removed — **BREAKING** `DLQRouter`: dead-lettering má jednu kolej, a není v tomto balíčku

package/README.md

@@ -151,6 +151,22 @@ Branch on `error.code`, never on `error.message`: the wording follows
 `.claude/rules/architecture-principles.md` §5 and may be improved, the code and
 `details.name` are the contract.
 
+## `DECLINED` — a rule forbade the work
+
+Every class in `ErrorTypes` names a way the work FAILED, except this one. `DECLINED`
+says the work was refused: the domain rule that was asked says it must not happen —
+a document already sent, an item the source will not discuss. It is terminal, it is
+not a failure, it is not retried and it is not dead-lettered; `ErrorHandlerCore`
+answers it with the verdict `declined`, which — like `dlq` — is a classification
+returned to the caller, not a route this package takes.
+
+It is declared by the THROWER, through `error.type`, and never derived from a status:
+every other `409` stays `BUSINESS`, table and all. That is deliberate, because the
+same status carries both meanings and only the thrower knows which one it meant.
+
+@see api/docs/governance/confirmations/workflow-failed-status-projection.md — 004
+@see api/docs/biz/70-contracts/error-handling.md — the error classes
+
 ## API Reference
 
 See [ERROR_HANDLING.md](/docs/standards/ERROR_HANDLING.md) for the cross-cutting standard (classification table, fail-loudly rules).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlineapps/error-handler-core",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Core error handling functionality for OA Drive microservices - classification, retry, circuit breaker, DLQ routing",
   "oa": {
     "category": "connector"

package/src/ErrorClassifier.js

@@ -11,6 +11,13 @@ const ErrorTypes = {
   VALIDATION: 'VALIDATION',    // Input validation - DLQ
   TIMEOUT: 'TIMEOUT',          // Operation timeout - RETRY
   RATE_LIMIT: 'RATE_LIMIT',    // Rate limiting - RETRY with backoff
+  // A rule forbade the work. TERMINAL and NOT a failure: the caller asked for
+  // something the domain says must not happen — a document already sent, an
+  // item the source will not discuss — so there is nothing to retry and nothing
+  // to dead-letter. It is declared by the thrower through `error.type`, never
+  // derived from a status: every other 409 stays BUSINESS.
+  // @see api/docs/governance/confirmations/workflow-failed-status-projection.md 004
+  DECLINED: 'DECLINED',        // Refused by a rule - TERMINAL, no retry, no DLQ
   UNKNOWN: 'UNKNOWN'           // Unclassified - LOG and THROW
 };
 

package/src/ErrorHandlerCore.js

@@ -316,6 +316,14 @@ class ErrorHandlerCore {
       case ErrorTypes.FATAL:
         // Fatal errors, throw immediately
         return { type: 'throw' };
+
+      case ErrorTypes.DECLINED:
+        // A rule forbade the work: terminal, and neither a retry nor a failure.
+        // Its own verdict rather than `dlq`, because dead-lettering says "look at
+        // this", and there is nothing to look at — the refusal IS the outcome
+        // (conf `workflow-failed-status-projection` 004). Like `dlq`, this is a
+        // CLASSIFICATION returned to the caller; this class routes nothing.
+        return { type: 'declined' };
         
       default:
         // Unknown errors, log and throw

package/src/UnifiedLogSchema.js

@@ -25,6 +25,11 @@ const SEVERITY_BY_TYPE = {
   [ErrorTypes.VALIDATION]: 'warn',
   [ErrorTypes.TIMEOUT]: 'error',
   [ErrorTypes.RATE_LIMIT]: 'warn',
+  // Not an incident: a rule said no, and the run ended on that. `info` is the
+  // severity of a thing that happened as designed — filing it as `error` would
+  // put every refused send into the operator's error stream, which is the noise
+  // conf `workflow-failed-status-projection` 004 exists to remove.
+  [ErrorTypes.DECLINED]: 'info',
   [ErrorTypes.UNKNOWN]: 'error'
 };