# Story 4.20a: Remove Deprecated IntegrityPlugin Protocol

**Status:** Draft  
**Priority:** Medium  
**Depends on:** 4.20 (Migrate fapilog-tamper to Standard Plugin Architecture)  
**Effort:** 1-2 days

---

## Problem Statement

Story 4.20 migrates `fapilog-tamper` to the standard plugin architecture while maintaining backward compatibility. After a deprecation period, the legacy `IntegrityPlugin` protocol and all associated special-case handling must be removed to:

1. **Reduce maintenance burden**: Two parallel code paths require double testing and documentation
2. **Simplify core codebase**: Special-case handling in `_build_pipeline()` adds complexity
3. **Clean API surface**: Remove deprecated exports that confuse new users
4. **Reduce code size**: Remove dead code paths and unused entry points

This story performs the final cleanup after the deprecation period established in 4.20.

---

## Scope

### Code to Remove

#### 1. Core fapilog

| File | What to Remove |
|------|----------------|
| `src/fapilog/plugins/integrity.py` | Entire file (deprecated `IntegrityPlugin` protocol and `load_integrity_plugin`) |
| `src/fapilog/plugins/__init__.py` | Exports: `IntegrityPlugin`, `load_integrity_plugin` |
| `src/fapilog/__init__.py` | Special-case integrity handling in `_build_pipeline()` |
| `src/fapilog/core/settings.py` | `core.integrity_plugin` and `core.integrity_config` fields |

#### 2. fapilog-tamper Package

| File | What to Remove |
|------|----------------|
| `packages/fapilog-tamper/src/fapilog_tamper/plugin.py` | Entire file (`_TamperSealedPlugin` class) |
| `packages/fapilog-tamper/pyproject.toml` | Entry point: `[project.entry-points."fapilog.integrity"]` |
| `packages/fapilog-tamper/src/fapilog_tamper/__init__.py` | Export: `TamperSealedPlugin` |

#### 3. Tests

| File | What to Remove/Update |
|------|----------------------|
| `tests/unit/test_plugin_loader.py` | Tests for `load_integrity_plugin` |
| `tests/unit/test_plugin_pipeline.py` | Tests for integrity plugin wrapping |
| `tests/integration/` | Any integration tests using legacy `integrity_plugin` config |

#### 4. Documentation

| File | Action |
|------|--------|
| `docs/plugins/index.md` | Remove IntegrityPlugin references |
| `docs/addons/tamper-evident-logging.md` | Remove legacy configuration examples |
| `docs/api-reference/plugins/index.md` | Remove IntegrityPlugin from catalog |
| `docs/enterprise.md` | Update to reference only standard plugin config |

---

## Implementation Plan

### Phase 1: Verify Deprecation Period Complete

**Prerequisites Check:**
- [ ] Story 4.20 fully implemented and released
- [ ] At least one minor version released with deprecation warnings
- [ ] No open issues from users about migration difficulties
- [ ] Telemetry/logs show minimal usage of deprecated API (if tracked)

### Phase 2: Remove Core fapilog Code

#### Step 2.1: Delete `src/fapilog/plugins/integrity.py`

```bash
git rm src/fapilog/plugins/integrity.py
```

#### Step 2.2: Update `src/fapilog/plugins/__init__.py`

```diff
 from fapilog.plugins.base import (
     BaseEnricher,
     BaseProcessor,
     BaseRedactor,
     BaseSink,
 )
-from fapilog.plugins.integrity import IntegrityPlugin, load_integrity_plugin
 from fapilog.plugins.loader import (
     list_available_plugins,
     load_plugin,
     register_builtin,
 )
 from fapilog.plugins.metadata import PluginMetadata
 from fapilog.plugins.versioning import PLUGIN_API_VERSION

 __all__ = [
     "BaseEnricher",
-    "IntegrityPlugin",
-    "load_integrity_plugin",
     "load_plugin",
     "list_available_plugins",
     "register_builtin",
     "PluginMetadata",
     "BaseProcessor",
     "BaseRedactor",
     "BaseSink",
     "PLUGIN_API_VERSION",
 ]
```

#### Step 2.3: Remove Special Handling from `src/fapilog/__init__.py`

Remove the `integrity_plugin` code path from `_build_pipeline()`:

```diff
 def _build_pipeline(settings: Settings) -> Pipeline:
     enrichers = _load_enrichers(settings)
     sinks = _load_sinks(settings)
-    
-    # Legacy integrity plugin handling (REMOVE)
-    if settings.core.integrity_plugin:
-        from fapilog.plugins import load_integrity_plugin
-        plugin = load_integrity_plugin(settings.core.integrity_plugin)
-        integrity_enricher = plugin.get_enricher(settings.core.integrity_config or {})
-        enrichers.append(integrity_enricher)
-        sinks = [plugin.wrap_sink(sink, settings.core.integrity_config or {}) for sink in sinks]
     
     return Pipeline(enrichers=enrichers, sinks=sinks)
```

#### Step 2.4: Update `src/fapilog/core/settings.py`

```diff
 class CoreSettings(BaseModel):
     """Core logging settings."""
     
     enrichers: list[str] = Field(default_factory=list)
     sinks: list[str] = Field(default_factory=lambda: ["stdout_json"])
     redactors: list[str] = Field(default_factory=list)
     processors: list[str] = Field(default_factory=list)
-    
-    # Deprecated - use enrichers=["integrity"], sinks=["sealed"] instead
-    integrity_plugin: str | None = Field(
-        default=None,
-        description="DEPRECATED: Use enrichers=['integrity'] and sinks=['sealed']",
-    )
-    integrity_config: dict[str, Any] | None = Field(
-        default=None,
-        description="DEPRECATED: Use enricher_config.integrity and sink_config.sealed",
-    )
```

### Phase 3: Remove fapilog-tamper Legacy Code

#### Step 3.1: Delete Legacy Plugin File

```bash
git rm packages/fapilog-tamper/src/fapilog_tamper/plugin.py
```

#### Step 3.2: Update Entry Points

**File: `packages/fapilog-tamper/pyproject.toml`**

```diff
 [project.entry-points."fapilog.enrichers"]
 integrity = "fapilog_tamper.enricher:IntegrityEnricher"

 [project.entry-points."fapilog.sinks"]
 sealed = "fapilog_tamper.sealed_sink:SealedSink"

-[project.entry-points."fapilog.integrity"]
-tamper-sealed = "fapilog_tamper:TamperSealedPlugin"
```

#### Step 3.3: Update Package Exports

**File: `packages/fapilog-tamper/src/fapilog_tamper/__init__.py`**

```diff
 from fapilog_tamper.enricher import IntegrityEnricher
 from fapilog_tamper.sealed_sink import SealedSink
-from fapilog_tamper.plugin import _TamperSealedPlugin as TamperSealedPlugin
 from fapilog_tamper.config import IntegrityEnricherConfig, SealedSinkConfig

 __all__ = [
     "IntegrityEnricher",
     "SealedSink",
-    "TamperSealedPlugin",
     "IntegrityEnricherConfig",
     "SealedSinkConfig",
 ]
```

### Phase 4: Update Tests

#### Step 4.1: Remove Deprecated API Tests

Delete or update tests that exercise the legacy code path:

```bash
# Identify tests to update
grep -r "load_integrity_plugin\|IntegrityPlugin\|integrity_plugin" tests/
```

#### Step 4.2: Ensure Standard Path Has Full Coverage

Verify tests exist for:
- Loading `IntegrityEnricher` via `load_plugin("fapilog.enrichers", "integrity")`
- Loading `SealedSink` via `load_plugin("fapilog.sinks", "sealed")`
- Full pipeline with standard configuration

### Phase 5: Update Documentation

#### Step 5.1: Remove Migration Content

After cleanup, remove migration guides that reference the old API since there's nothing to migrate from.

#### Step 5.2: Simplify Documentation

Update docs to show only the standard plugin configuration without "before/after" comparisons.

---

## Acceptance Criteria

### Must Have

- [ ] `IntegrityPlugin` protocol removed from codebase
- [ ] `load_integrity_plugin()` function removed
- [ ] `core.integrity_plugin` and `core.integrity_config` settings removed
- [ ] `_TamperSealedPlugin` class removed from fapilog-tamper
- [ ] `fapilog.integrity` entry point group removed
- [ ] All tests pass with only standard plugin loading
- [ ] No references to deprecated API in documentation
- [ ] CHANGELOG entry documenting breaking change

### Should Have

- [ ] Clear error message if user tries to use removed settings
- [ ] Migration guide in release notes
- [ ] 90%+ coverage maintained

### Won't Have

- [ ] Automatic migration tooling
- [ ] Backward compatibility shims

---

## Version & Release Notes

### Recommended Version

This is a **breaking change** and should be released in a major version bump (e.g., 1.0.0) or clearly documented minor version if pre-1.0.

### CHANGELOG Entry

```markdown
## [0.5.0] - YYYY-MM-DD

### Removed

- **BREAKING**: Removed deprecated `IntegrityPlugin` protocol and `load_integrity_plugin()` function.
  Use standard plugin loading instead:
  ```yaml
  core:
    enrichers: ["integrity"]  # from fapilog-tamper
    sinks: ["sealed"]         # from fapilog-tamper
  ```
  
- **BREAKING**: Removed `core.integrity_plugin` and `core.integrity_config` settings.
  Use `enricher_config.integrity` and `sink_config.sealed` instead.

- Removed `TamperSealedPlugin` export from fapilog-tamper package.

### Migration

Users of the legacy integrity plugin API should migrate to standard plugin configuration.
See the [migration guide](docs/addons/tamper-evident-logging.md) for details.
```

---

## Test Plan

### Unit Tests

1. **Negative Tests**
   - Verify importing removed symbols raises `ImportError`
   - Verify using removed settings raises clear error (not silent failure)

2. **Positive Tests**
   - Standard plugin loading for `IntegrityEnricher` works
   - Standard plugin loading for `SealedSink` works
   - Full pipeline configuration with tamper plugins works

### Integration Tests

1. End-to-end tamper-evident logging with standard configuration
2. Hash chain verification after cleanup
3. Manifest generation with `SealedSink`

---

## Risks & Mitigations

| Risk | Impact | Mitigation |
|------|--------|------------|
| Users still on legacy API | High | Long deprecation period, clear warnings |
| Missed code references | Medium | Comprehensive grep before removal |
| Test gaps after removal | Medium | Run full test suite, check coverage |

---

## Estimated Effort

| Task | Effort |
|------|--------|
| Prerequisites verification | 0.25 day |
| Remove core fapilog code | 0.5 day |
| Remove fapilog-tamper legacy code | 0.25 day |
| Update tests | 0.5 day |
| Update documentation | 0.25 day |
| Review and release notes | 0.25 day |
| **Total** | **~2 days** |

---

## Checklist

Before starting this story:

- [ ] Story 4.20 is complete and released
- [ ] Deprecation warnings have been live for at least one release cycle
- [ ] No blocking user feedback about migration

During implementation:

- [ ] Run `grep -r "IntegrityPlugin\|load_integrity_plugin\|integrity_plugin" src/ packages/ tests/ docs/` to find all references
- [ ] Verify CI passes after each phase
- [ ] Update CHANGELOG before merging

---

## Related Stories

- **4.20**: Migrate fapilog-tamper to Standard Plugin Architecture (prerequisite)
- **4.19**: Simple Plugin Configuration API (foundation)



