# ━━━━━ KERNEL ━━━━━

Shared intelligence layer for media automation. Sourced by consumer scripts —
not run directly. Contains stateful scoring systems, adaptive logic, and
cross-domain engines that would pollute common.sh if placed there.

---

## ━━━ WHAT THIS FOLDER IS ━━━

**Not scripts. Not utilities. Engines.**

The Kernel holds logic that is:

- **Stateful** — maintains scores, decay state, or adaptive thresholds across calls
- **Domain-aware** — understands the difference between music, TV, and movie decisions
- **Shared across consumers** — one engine, multiple discovery scripts consuming it

This is distinct from:

| Location | Contains |
|----------|----------|
| `common.sh` | Reusable utility functions (logging, locking, arg parsing) |
| `master.conf` | Shared ecosystem configuration and tuning values |
| `Kernel/` | Stateful scoring systems and adaptive decision logic |

The rule: if the logic makes *decisions*, it lives here. If it's a helper or
config value, it lives in common.sh or master.conf.

---

## ━━━ WHY A SEPARATE KERNEL ━━━

Media automation decisions are not uniform. A Lidarr discovery script should be
highly selective. A Sonarr intake script should be family-aware and balanced. A
Radarr script should be broadly flexible. If scoring logic lives in each script,
it diverges and drifts independently.

Centralizing the decision layer:

- Keeps consumers thin — they define weights and thresholds, not scoring logic
- Prevents cross-domain bias pollution — music strictness does not contaminate TV
- Allows the scoring model to improve without touching every consumer script

---

## ━━━ WHAT BELONGS HERE ━━━

An engine belongs in Kernel if it:

- Implements a scoring or evaluation model
- Maintains or reads adaptive state
- Is consumed by more than one script (or is designed to be)
- Contains logic that would create tight coupling if duplicated

Utilities — locking, notifications, arg parsing, API calls — belong in common.sh.

---

## ━━━ FILES IN THIS FOLDER ━━━

| File | Role | Status |
|------|------|--------|
| `decision_engine.sh` | Behavior-driven scoring kernel — scoring, decay, deduplication, threshold evaluation | WIP — currently paired with `playback_aware_lidarr_discovery.sh` |

**Planned:**

| File | Role |
|------|------|
| `transcoding_engine.sh` | Transcoding decision logic (quality, codec selection, cost-benefit evaluation) |

---

## ━━━ HOW CONSUMERS USE THE KERNEL ━━━

Source the engine at the top of the consumer script:

```bash
source "$ROOT_DIR/Kernel/decision_engine.sh"
```

Then call engine functions directly, passing consumer-defined weights and thresholds:

```bash
score=$(score_candidate "$user_score" "$popularity" "$recency" "$quality")
score=$(apply_temporal_decay "$score" "$age_days")
decision=$(make_decision "$score" "$MY_THRESHOLD")
```

The engine returns values — consumer scripts decide what to do with them. The
engine has no side effects: no file writes, no API calls, no deletions.