chore(OMN-6665): Document undocumented BLE001 suppressions and fix invalid noqa directives

src/omnibase_core/cli/cli_install.py

@@ -379,7 +379,7 @@ def cli_install(
                     click.echo(f"Warning: {package_path} is unsigned", err=True)
         except click.ClickException:
             raise
-        except Exception:  # noqa: BLE001
+        except Exception:  # noqa: BLE001  # fallback-ok: signature check failure is a warning, not a fatal install error
             click.echo("Warning: could not check package signature", err=True)
 
     if dry_run:

src/omnibase_core/decorators/decorator_error_handling.py

@@ -80,7 +80,7 @@ def _has_pydantic_error_count_method(exc: Exception) -> bool:
     try:
         result = error_count_attr()
         return isinstance(result, int)
-    except Exception:  # noqa: BLE001
+    except Exception:  # noqa: BLE001  # fallback-ok: error_count() call failure means not a Pydantic-like error
         # fallback-ok: error_count() call failed, not Pydantic-like
         return False
 
@@ -179,7 +179,7 @@ def _is_validation_error(exc: Exception) -> bool:
             errors_result = errors_attr()
             if _is_pydantic_validation_error_structure(errors_result):
                 return True
-        except Exception:  # noqa: BLE001
+        except Exception:  # noqa: BLE001  # fallback-ok: errors() call failure means not Pydantic-structured, check next tier
             # fallback-ok: errors() call failed, continue to next tier
             pass
 
@@ -234,7 +234,7 @@ def process(self, input_state):
             raise  # Never suppress async cancellation
         except ModelOnexError:
             raise  # Always re-raise ModelOnexError as-is
-        except Exception as e:  # noqa: BLE001
+        except Exception as e:  # noqa: BLE001  # boundary-ok: unknown exceptions wrapped in ModelOnexError at decorator boundary
             raise ModelOnexError(
                 f"{operation_name} failed: {str(e)}",
                 EnumCoreErrorCode.OPERATION_FAILED

src/omnibase_core/mixins/mixin_contract_publisher.py

@@ -300,7 +300,7 @@ async def _heartbeat_loop(self, interval_seconds: int) -> None:
                 await asyncio.sleep(interval_seconds)
             except asyncio.CancelledError:
                 raise  # Propagate cancellation
-            except Exception:  # noqa: BLE001
+            except Exception:  # noqa: BLE001  # fallback-ok: heartbeat transient errors must not stop liveness signals
                 # Swallow error and continue heartbeating - transient errors shouldn't
                 # stop liveness signals. Consumers can detect issues via heartbeat gaps.
                 await asyncio.sleep(interval_seconds)

src/omnibase_core/mixins/mixin_discovery_responder.py

@@ -207,7 +207,7 @@ async def stop_discovery_responder(self) -> None:
         if self._discovery_unsubscribe:
             try:
                 await self._discovery_unsubscribe()
-            except Exception:  # noqa: BLE001
+            except Exception:  # noqa: BLE001  # cleanup-resilience-ok: shutdown cleanup errors are non-critical
                 # cleanup-resilience-ok: cleanup errors during shutdown are non-critical
                 pass
 

src/omnibase_core/mixins/mixin_health_check.py

@@ -335,7 +335,7 @@ async def wrap_sync(
                 check_tasks.append((check_func.__name__, task))
 
             # fallback-ok: health check task creation should not crash the async health check
-            except Exception as e:  # noqa: BLE001
+            except Exception as e:  # noqa: BLE001  # fallback-ok: task creation error must not crash health check
                 emit_log_event(
                     LogLevel.ERROR,
                     f"Failed to create health check task: {check_func.__name__}",

src/omnibase_core/mixins/mixin_node_lifecycle.py

@@ -202,7 +202,7 @@ def _register_node(self) -> None:
             )
 
         # fallback-ok: event publishing is non-critical, log and continue
-        except Exception as e:  # noqa: BLE001
+        except Exception as e:  # noqa: BLE001  # fallback-ok: node announce publish error must not block registration
             context = ModelLogContext(
                 calling_module=_COMPONENT_NAME,
                 calling_function="_register_node",
@@ -265,7 +265,7 @@ def _publish_shutdown_event(self) -> None:
             )
 
         # fallback-ok: shutdown event is non-critical, log and continue
-        except Exception as e:  # noqa: BLE001
+        except Exception as e:  # noqa: BLE001  # fallback-ok: shutdown event publish error must not block shutdown
             context = ModelLogContext(
                 calling_module=_COMPONENT_NAME,
                 calling_function="_publish_shutdown_event",
@@ -481,7 +481,7 @@ def cleanup_lifecycle_resources(self) -> None:
             try:
                 self.cleanup_event_handlers()
             # fallback-ok: cleanup failure is non-critical, log and continue
-            except Exception as e:  # noqa: BLE001
+            except Exception as e:  # noqa: BLE001  # cleanup-resilience-ok: event handler cleanup must not block lifecycle cleanup
                 node_id = _get_node_id_as_uuid(self)
                 context = ModelLogContext(
                     calling_module=_COMPONENT_NAME,

src/omnibase_core/mixins/mixin_node_service.py

@@ -237,7 +237,7 @@ async def stop_service_mode(self) -> None:
             for callback in self._shutdown_callbacks:
                 try:
                     callback()
-                except Exception as e:  # noqa: BLE001
+                except Exception as e:  # noqa: BLE001  # fallback-ok: user shutdown callbacks must not crash service shutdown
                     # fallback-ok: user callbacks must not crash shutdown
                     self._log_error(f"Shutdown callback failed: {e}")
 
@@ -253,7 +253,7 @@ async def stop_service_mode(self) -> None:
             # Set service as not running before propagating cancellation.
             self._service_running = False
             raise
-        except Exception as e:  # noqa: BLE001
+        except Exception as e:  # noqa: BLE001  # cleanup-resilience-ok: shutdown must complete regardless of cleanup errors
             # cleanup-resilience-ok: shutdown must complete even if cleanup fails
             self._log_error(f"Error during service shutdown: {e}")
             self._service_running = False
@@ -372,7 +372,7 @@ async def handle_tool_invocation(self, event: ModelToolInvocationEvent) -> None:
 
         # fallback-ok: service must emit error response for any failure
         # Fallback for truly unexpected exceptions not covered above.
-        except Exception as e:  # noqa: BLE001
+        except Exception as e:  # noqa: BLE001  # fallback-ok: unexpected exceptions must produce error response, not crash service
             execution_time_ms = int((time.time() - start_time) * 1000)
             response_event = ModelToolResponseEvent.create_error_response(
                 correlation_id=correlation_id,

src/omnibase_core/models/container/model_onex_container.py

@@ -285,7 +285,7 @@ def __init__(
                     f"ServiceRegistry not available: {e}",
                 )
                 self._enable_service_registry = False
-            except Exception as e:  # noqa: BLE001
+            except Exception as e:  # noqa: BLE001  # init-errors-ok: ServiceRegistry init failure uses safe defaults
                 # init-errors-ok: use safe defaults if ServiceRegistry initialization fails
                 emit_log_event(
                     LogLevel.ERROR,

src/omnibase_core/models/core/model_event_type_registry.py

@@ -89,7 +89,7 @@ def discover_from_contracts(self, contracts_dir: Path) -> int:
         for contract_file in contract_files:
             try:
                 events_discovered += self._discover_from_contract(contract_file)
-            except Exception as e:  # noqa: BLE001
+            except Exception as e:  # noqa: BLE001  # fallback-ok: resilient discovery skips invalid contracts
                 # fallback-ok: resilient discovery - skip invalid contracts with debug logging
                 logger.debug("Failed to discover events from %s: %s", contract_file, e)
                 continue

src/omnibase_core/models/detection/__init__.py

@@ -18,6 +18,6 @@
     )
 
     ModelServiceDetectionConfig.model_rebuild()
-except Exception:  # noqa: BLE001
+except Exception:  # noqa: BLE001  # init-errors-ok: model_rebuild may fail during circular import resolution
     # init-errors-ok: may fail during circular import, safe to ignore
     pass

src/omnibase_core/models/health/__init__.py

@@ -43,7 +43,7 @@
 try:
     ModelHealthStatus.model_rebuild()
     ModelToolHealth.model_rebuild()
-except Exception:  # noqa: BLE001
+except Exception:  # noqa: BLE001  # init-errors-ok: model_rebuild may fail during circular import resolution
     # init-errors-ok: model_rebuild may fail during circular import resolution, safe to ignore
     pass
 
@@ -63,6 +63,6 @@
         _types_namespace={"ModelCustomFields": _ModelCustomFields}
     )
     ModelHealthCheckConfig.model_rebuild()
-except Exception:  # noqa: BLE001
+except Exception:  # noqa: BLE001  # init-errors-ok: model_rebuild may fail during circular import resolution
     # init-errors-ok: model_rebuild may fail during circular import resolution, safe to ignore
     pass

src/omnibase_core/models/health/model_health_check_config.py

@@ -242,7 +242,7 @@ def _resolve_forward_references() -> None:
         # model_rebuild(), so we just need to rebuild this class to pick up
         # the resolved types from ModelHealthCheckMetadata
         ModelHealthCheckConfig.model_rebuild()
-    except Exception:  # noqa: BLE001
+    except Exception:  # noqa: BLE001  # init-errors-ok: model_rebuild may fail during circular import resolution
         # init-errors-ok: model_rebuild may fail during circular import resolution
         pass
 

src/omnibase_core/models/health/model_health_check_metadata.py

@@ -124,7 +124,7 @@ def _resolve_forward_references() -> None:
         # init-errors-ok: Import may fail during early module loading
         # The forward reference will be resolved when health/__init__.py completes
         pass
-    except Exception:  # noqa: BLE001
+    except Exception:  # noqa: BLE001  # init-errors-ok: model_rebuild may fail during circular import resolution
         # init-errors-ok: model_rebuild may fail during circular import resolution
         # This is safe to ignore as the forward reference will be resolved
         # when the full module graph is loaded

src/omnibase_core/models/infrastructure/model_result.py

@@ -236,7 +236,7 @@ def map(self, f: Callable[[T], U]) -> ModelResult[U, E | Exception]:
             try:
                 new_value = f(self._get_value_or_raise())
                 return ModelResult.ok(new_value)
-            except Exception as e:  # noqa: BLE001
+            except Exception as e:  # noqa: BLE001  # fallback-ok: monadic map converts exceptions to Err result
                 # fallback-ok: Monadic error handling - converting exceptions to error results
                 return ModelResult.err(e)
         # Pass through the original error
@@ -257,7 +257,7 @@ def map_err(self, f: Callable[[E], F]) -> ModelResult[T, F | Exception]:
         try:
             new_error = f(self._get_error_or_raise())
             return ModelResult.err(new_error)
-        except Exception as e:  # noqa: BLE001
+        except Exception as e:  # noqa: BLE001  # fallback-ok: monadic map_err converts exceptions to Err result
             # fallback-ok: Monadic error handling - converting exceptions to error results
             return ModelResult.err(e)
 
@@ -282,7 +282,7 @@ def and_then(
                 # ModelResult[U, E | Exception] at runtime (same structure, wider error type)
                 result = f(self._get_value_or_raise())
                 return cast("ModelResult[U, E | Exception]", result)
-            except Exception as e:  # noqa: BLE001
+            except Exception as e:  # noqa: BLE001  # fallback-ok: monadic and_then converts exceptions to Err result
                 # fallback-ok: Monadic error handling - converting exceptions to error results
                 return ModelResult.err(e)
         # Pass through the original error
@@ -309,7 +309,7 @@ def or_else(
             # ModelResult[T, F | Exception] at runtime (same structure, wider error type)
             result = f(self._get_error_or_raise())
             return cast("ModelResult[T, F | Exception]", result)
-        except Exception as e:  # noqa: BLE001
+        except Exception as e:  # noqa: BLE001  # fallback-ok: monadic or_else converts exceptions to Err result
             # fallback-ok: Monadic error handling - converting exceptions to error results
             return ModelResult.err(e)
 
@@ -410,7 +410,7 @@ def try_result[T](f: Callable[[], T]) -> ModelResult[T, Exception]:
     """
     try:
         return ModelResult.ok(f())
-    except Exception as e:  # noqa: BLE001
+    except Exception as e:  # noqa: BLE001  # fallback-ok: try_result converts exceptions to Err result
         # fallback-ok: Monadic error handling - converting exceptions to error results
         return ModelResult.err(e)
 

src/omnibase_core/models/infrastructure/model_transaction.py

@@ -129,7 +129,7 @@
                         "error_type": type(e).__name__,
                     },
                 )
-            except BaseException as e:  # noqa: BLE001
+            except BaseException as e:  # noqa: BLE001  # cleanup-resilience-ok: deferred BaseException subclasses re-raised after cleanup
                 # cleanup-resilience-ok: catch-all for resilience
                 # Catch any remaining BaseException subclasses not explicitly handled
                 # above (e.g., custom BaseException subclasses). Store first occurrence

src/omnibase_core/nodes/node_contract_verify_replay_compute/handler.py

@@ -265,7 +265,7 @@ def _check_schema_validation(self, reader: OncpReader) -> ModelVerifyCheckResult
         """Check 1: all overlay YAMLs parse as ModelContractPatch."""
         try:
             patches = reader.get_overlay_patches()
-        except (ModelOnexError, Exception) as exc:  # noqa: BLE001
+        except (ModelOnexError, Exception) as exc:  # noqa: BLE001  # boundary-ok: check returns FAIL result, never raises
             return ModelVerifyCheckResult(
                 check_name="schema_validation",
                 status=EnumCheckStatus.FAIL,
@@ -301,7 +301,7 @@ def _check_capability_linting(self, reader: OncpReader) -> ModelVerifyCheckResul
         """
         try:
             patches = reader.get_overlay_patches()
-        except (ModelOnexError, Exception) as exc:  # noqa: BLE001
+        except (ModelOnexError, Exception) as exc:  # noqa: BLE001  # boundary-ok: check returns FAIL result, never raises
             return ModelVerifyCheckResult(
                 check_name="capability_linting",
                 status=EnumCheckStatus.FAIL,
@@ -376,7 +376,7 @@ def _check_fixture_presence(
                     raw_content = zf.read(scenario_entry.path)
                     try:
                         scenario_data = yaml.safe_load(raw_content.decode("utf-8"))
-                    except Exception:  # noqa: BLE001
+                    except Exception:  # noqa: BLE001  # fallback-ok: unparseable YAML skipped, not a bundle integrity failure
                         continue  # unparseable YAML — not our problem here
 
                     if not isinstance(scenario_data, dict):
@@ -389,7 +389,7 @@ def _check_fixture_presence(
                                 f"scenario '{scenario_entry.id}': "
                                 f"fixture_path '{fixture_path}' not in bundle"
                             )
-        except (zipfile.BadZipFile, Exception) as exc:  # noqa: BLE001
+        except (zipfile.BadZipFile, Exception) as exc:  # noqa: BLE001  # boundary-ok: check returns FAIL result, never raises
             return ModelVerifyCheckResult(
                 check_name="fixture_presence",
                 status=EnumCheckStatus.FAIL,
@@ -422,7 +422,7 @@ def _check_overlay_merge(  # stub-ok: uses a minimal in-process profile factory
         """
         try:
             patches = reader.get_overlay_patches()
-        except (ModelOnexError, Exception) as exc:  # noqa: BLE001
+        except (ModelOnexError, Exception) as exc:  # noqa: BLE001  # boundary-ok: check returns FAIL result, never raises
             return ModelVerifyCheckResult(
                 check_name="overlay_merge_correctness",
                 status=EnumCheckStatus.FAIL,
@@ -477,7 +477,7 @@ def _check_overlay_merge(  # stub-ok: uses a minimal in-process profile factory
                 # Single overlay — use simple merge.
                 engine.merge(patch=base_patch)
 
-        except (ModelOnexError, Exception) as exc:  # noqa: BLE001
+        except (ModelOnexError, Exception) as exc:  # noqa: BLE001  # boundary-ok: check returns FAIL result, never raises
             return ModelVerifyCheckResult(
                 check_name="overlay_merge_correctness",
                 status=EnumCheckStatus.FAIL,
@@ -561,7 +561,7 @@ def _check_all_scenarios_present(
                         missing.append(
                             f"scenario '{scenario.id}': path '{scenario.path}' missing"
                         )
-        except (zipfile.BadZipFile, Exception) as exc:  # noqa: BLE001
+        except (zipfile.BadZipFile, Exception) as exc:  # noqa: BLE001  # boundary-ok: check returns FAIL result, never raises
             return ModelVerifyCheckResult(
                 check_name="all_scenarios_present",
                 status=EnumCheckStatus.FAIL,
@@ -601,7 +601,7 @@ def _check_all_invariants_present(
                         missing.append(
                             f"invariant '{inv.id}': path '{inv.path}' missing"
                         )
-        except (zipfile.BadZipFile, Exception) as exc:  # noqa: BLE001
+        except (zipfile.BadZipFile, Exception) as exc:  # noqa: BLE001  # boundary-ok: check returns FAIL result, never raises
             return ModelVerifyCheckResult(
                 check_name="all_invariants_present",
                 status=EnumCheckStatus.FAIL,
@@ -684,7 +684,7 @@ def _sign_digest(self, report_digest: str) -> str | None:
 
             sig_bytes = private_key.sign(report_digest.encode("ascii"))
             return base64.b64encode(sig_bytes).decode("ascii")
-        except Exception:  # noqa: BLE001
+        except Exception:  # noqa: BLE001  # fallback-ok: signing is best-effort for MVP; report is still valid unsigned
             # fallback-ok: signing is best-effort for MVP; report is still valid
             return None
 

src/omnibase_core/nodes/node_reducer.py

@@ -1099,7 +1099,7 @@ def worker():
 
             try:
                 result = await node.process(input_data)
-            except Exception:  # noqa: BLE001
+            except Exception:  # noqa: BLE001  # boundary-ok: catch-all triggers FSM state restore on any failure before re-raise
                 # Restore to previous state on failure
                 if saved_snapshot:
                     node.restore_state(saved_snapshot)

src/omnibase_core/nodes/node_validation_orchestrator/node_cross_repo_validation_orchestrator.py

@@ -220,7 +220,7 @@ async def validate(
             rules_applied = (
                 (result.metadata.rules_applied or 0) if result.metadata else 0
             )
-        except Exception as exc:  # noqa: BLE001
+        except Exception as exc:  # noqa: BLE001  # boundary-ok: validation errors captured for result, lifecycle must complete
             # Capture exception - lifecycle must complete
             error_message = f"{type(exc).__name__}: {exc}"
             issues = []

src/omnibase_core/pipeline/manifest_generator.py

@@ -710,7 +710,7 @@ def build(self) -> ModelExecutionManifest:
         for callback in list(self._on_manifest_built):
             try:
                 callback(manifest)
-            except Exception as e:  # noqa: BLE001
+            except Exception as e:  # noqa: BLE001  # callback-resilience-ok: callbacks must not crash manifest build
                 # callback-resilience-ok: callbacks must not crash manifest build
                 warnings.warn(
                     f"on_manifest_built callback failed: {e!r}. "