# Story 4.32: Remove Unimplemented Alerting Plugin Type

**Status:** Complete  
**Priority:** Critical  
**Depends on:** None  
**Effort:** 0.5 days

---

## Problem Statement

The plugin metadata validation accepts `"alerting"` as a valid plugin type:

```python
# src/fapilog/plugins/metadata.py:92
valid_types = {"sink", "processor", "enricher", "redactor", "alerting"}
```

And the authoring documentation mentions an `fapilog.alerting` entry point group:

```python
# docs/plugins/authoring.md
[project.entry-points."fapilog.alerting"]
"my-alert" = "my_package.my_alert"
```

**However, the alerting plugin type is NOT actually implemented:**

- ❌ No `BaseAlerting` protocol exists
- ❌ No `BUILTIN_ALERTING` registry in loader
- ❌ No `fapilog.alerting` entry point group in loader
- ❌ No alerting plugins can be discovered or loaded
- ❌ No built-in alerting plugins exist

### Impact

1. **Misleading documentation**: Users may try to create alerting plugins that cannot be loaded
2. **Validation allows invalid plugins**: A plugin with `plugin_type: "alerting"` passes metadata validation but cannot be used
3. **Confusion about feature completeness**: Suggests alerting is supported when it's not

---

## Background

Reviewing `docs/stories/4.12.alerting-interface.md`, the alerting interface was **designed but never implemented**. The alerting functionality that exists in fapilog is:

1. **Compliance alerts** in `core/audit.py` - Internal mechanism, not plugin-based
2. **Alerting settings** in `core/observability.py` - Configuration only, no plugin loading

These are independent of the plugin system.

---

## Options

### Option A: Remove Alerting Plugin Type (Recommended)

Remove `"alerting"` from valid types and update documentation.

**Pros:**

- Honest about current capabilities
- Removes dead code/documentation
- Fast to implement

**Cons:**

- Could be seen as feature removal (but it never worked)

### Option B: Implement Alerting Plugin Type

Add `BaseAlerting` protocol, loader registry, and discovery.

**Pros:**

- Feature completeness
- Matches original design intent

**Cons:**

- Significant effort
- Unclear use case vs. custom sinks with alerting logic
- No user demand demonstrated

### Option C: Mark as Experimental/Future

Keep the type but document it as "reserved for future use."

**Pros:**

- Reserves the namespace
- Transparent about status

**Cons:**

- Still allows invalid plugin metadata
- Confusing state

---

## Recommendation

**Option A (Remove)** - The alerting plugin type was designed but never implemented. Alerting functionality can be achieved via custom sinks. If there's future demand, a new story can add it properly.

---

## Implementation Plan

### Phase 1: Remove from Metadata Validation

**File: `src/fapilog/plugins/metadata.py`**

```python
# Before
valid_types = {"sink", "processor", "enricher", "redactor", "alerting"}

# After
valid_types = {"sink", "processor", "enricher", "redactor"}
```

### Phase 2: Update Documentation

**File: `docs/plugins/authoring.md`**

Remove the alerting entry point example:

```markdown
# DELETE these lines:

# [project.entry-points."fapilog.alerting"]

# "my-alert" = "my_package.my_alert"
```

**File: `docs/plugins/index.md`**

Ensure no mention of alerting as a plugin type.

### Phase 3: Archive the Alerting Story

**File: `docs/stories/4.12.alerting-interface.md`**

Add a note at the top:

```markdown
> **Status:** Cancelled - Not Implemented
>
> This interface was designed but never implemented. Alerting functionality
> is available via custom sinks or the built-in compliance alert mechanism
> in `fapilog.core.audit`. The `"alerting"` plugin type has been removed.
```

### Phase 4: Add Test

**File: `tests/unit/test_plugin_metadata.py`**

Add test to verify alerting is not a valid type:

```python
def test_alerting_not_valid_plugin_type():
    """Alerting is not a valid plugin type (was designed but never implemented)."""
    from fapilog.plugins.metadata import PluginMetadata
    import pytest

    with pytest.raises(ValueError, match="Invalid plugin type"):
        PluginMetadata(
            name="test",
            version="1.0.0",
            plugin_type="alerting",  # Should fail
            entry_point="test:Test",
            description="test",
            author="test",
            compatibility={"min_fapilog_version": "0.3.0"},
        )
```

---

## Acceptance Criteria

- [x] `"alerting"` removed from `valid_types` in metadata.py
- [x] Alerting entry point example removed from authoring.md
- [x] Story 4.12 marked as cancelled with explanation
- [x] Test confirms alerting metadata is rejected
- [x] No runtime errors from existing code

---

## Files Changed

| File                                      | Change                              |
| ----------------------------------------- | ----------------------------------- |
| `src/fapilog/plugins/metadata.py`         | Remove "alerting" from valid_types  |
| `docs/plugins/authoring.md`               | Remove alerting entry point example |
| `docs/stories/4.12.alerting-interface.md` | Mark as cancelled                   |
| `tests/unit/test_plugin_metadata.py`      | Add rejection test                  |
