Varaverk/Kernel/README-Kernel.md

━━━━━ 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:

source "$ROOT_DIR/Kernel/decision_engine.sh"

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

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.