# Story 4.44: Extract Audit/Tamper to Separate Package

**Status:** Complete
**Priority:** Medium
**Depends on:** None

---

## Context / Background

Strategic decision: Audit/tamper-evident logging is an add-on capability, not core functionality. Enterprise users in cloud environments typically rely on their SIEM/cloud platforms for audit trails. Users who need tamper-evident logs (self-hosted, regulated, edge/IoT) are a distinct audience.

Currently, audit code ships with core fapilog even though most users don't need it:

```
src/fapilog/core/
├── audit.py       ← 800+ lines
├── compliance.py  ← 200+ lines
└── ...
```

**Decision:** Extract to separate `fapilog-audit` package.

**Benefits:**

- Core fapilog stays lean (fast async logging + redaction)
- Audit users get focused package with independent release cycle
- No bloat for users who don't need audit capabilities
- Clear separation of concerns

---

## Scope (In / Out)

### In Scope

- Create new `fapilog-audit` package
- Move `AuditSink`, `AuditTrail`, `CompliancePolicy` to new package
- Move compliance validation functions
- Ensure `fapilog-audit` depends on `fapilog` core
- Register audit sink via entry point (not built-in)
- Update imports/documentation

### Out of Scope

- New audit features (separate stories in fapilog-audit roadmap)
- Fixing audit bugs before extraction (extract first, fix in new package)

---

## Acceptance Criteria

### AC1: Separate Package Created

**Description:** `fapilog-audit` is a standalone installable package.

**Validation:**

```bash
pip install fapilog-audit

# Installs fapilog as dependency
python -c "from fapilog_audit import AuditSink, AuditTrail"
```

### AC2: Core fapilog Has No Audit Code

**Description:** Audit-related modules removed from core.

**Validation:**

```bash
# These files should not exist in fapilog core
ls src/fapilog/core/audit.py    # Should fail
ls src/fapilog/core/compliance.py  # Should fail
```

### AC3: Entry Point Registration

**Description:** Audit sink registers via entry point, not built-in registry.

**Validation:**

```toml
# In fapilog-audit pyproject.toml
[project.entry-points."fapilog.sinks"]
audit = "fapilog_audit:AuditSink"
```

```python
# Works when fapilog-audit installed
from fapilog.plugins.loader import load_plugin
sink = load_plugin("fapilog.sinks", "audit", {})
```

### AC4: Backward Compatibility Path

**Description:** Users who currently use audit get clear migration path.

**Validation:**

```python
# Old way (no longer works after extraction)
from fapilog.core.audit import AuditTrail  # ImportError

# New way
from fapilog_audit import AuditTrail  # Works
```

Documentation explains migration.

---

## Implementation Notes

### New Package Structure

```
fapilog-audit/
├── pyproject.toml
├── src/
│   └── fapilog_audit/
│       ├── __init__.py
│       ├── audit.py        ← moved from core
│       ├── compliance.py   ← moved from core
│       ├── sink.py         ← AuditSink
│       └── trail.py        ← AuditTrail, hash chains
└── tests/
```

### pyproject.toml

```toml
[project]
name = "fapilog-audit"
dependencies = [
    "fapilog>=0.4.0",
]

[project.entry-points."fapilog.sinks"]
audit = "fapilog_audit:AuditSink"
```

### Stories That Move to fapilog-audit

| Story | Description |
|-------|-------------|
| 4.28 | Audit async blocking I/O |
| 4.29 | Audit encryption config accuracy |
| 4.43 | Audit trail instance management |
| 1.22 | Compliance validation integration |
| 4.10-4.18 | Tamper-evident features |

These become the `fapilog-audit` roadmap.

---

## Tasks

### Phase 1: Create Package

- [ ] Create `fapilog-audit` repository/directory
- [ ] Set up pyproject.toml with fapilog dependency
- [ ] Move audit.py, compliance.py to new package
- [ ] Set up entry point registration

### Phase 2: Remove from Core

- [ ] Remove audit.py from fapilog/core
- [ ] Remove compliance.py from fapilog/core
- [ ] Remove AuditSink from built-in registry
- [ ] Update core __init__.py exports

### Phase 3: Testing

- [ ] Move audit tests to new package
- [ ] Verify entry point loading works
- [ ] Verify core fapilog works without audit

### Phase 4: Documentation

- [ ] Migration guide for existing audit users
- [ ] Update README (remove audit mentions from core)
- [ ] Update CHANGELOG

---

## Tests

### fapilog-audit Tests

- All existing audit tests move to new package
- Test entry point registration works

### fapilog Core Tests

- Verify no import errors without audit
- Verify audit sink not in built-in registry

---

## Definition of Done

- [x] `fapilog-audit` package created and installable
- [x] Core fapilog has no audit code
- [x] Entry point registration works
- [x] Migration documented
- [x] All tests pass in both packages

---

## Risks / Rollback

### Risks

1. **Risk:** Breaking change for audit users
   - **Mitigation:** Clear migration guide; deprecation period if needed

2. **Risk:** Two packages to maintain
   - **Mitigation:** Audit is stable; infrequent releases expected

### Rollback Plan

Keep audit in core if extraction proves problematic.

---

## Related Stories

- **Supersedes:** Stories 4.10-4.18, 4.28, 4.29, 4.43, 1.22 (move to fapilog-audit)
- **Related:** Story 3.5 - Plugin security (entry point loading)

---

## Change Log

| Date       | Change        | Author |
|------------|---------------|--------|
| 2026-01-16 | Initial draft | Claude |
