// ss_release_policy_box.h - SuperSlab Release Policy Box
// Purpose: Determine when to keep/release/decommit superslabs (Memory-Lean mode)
// Box Theory: Single conversion point for superslab lifecycle decisions
//
// Responsibilities:
//   - Decide if a superslab should be kept (persistent) or released
//   - Execute decommit operations (MADV_FREE/MADV_DONTNEED) when lean mode enabled
//   - Respect DSO guard / fail-fast rules (never touch DSO memory)
//
// Design Philosophy:
//   - In FAST mode (default): Keep all superslabs (speed-first, persistent backend)
//   - In LEAN mode (opt-in): Release empty superslabs to reduce RSS
//   - Boundary: All decommit operations flow through Superslab OS Box (ss_os_madvise_guarded)
//   - Safety: DSO guard prevents touching .fini_array (Phase 17 lesson)
//
// Dependencies:
//   - ss_mem_lean_env_box.h (ENV configuration)
//   - madvise_guard_box.h (DSO-safe madvise wrapper)
//   - ss_os_acquire_box.h (stats counters)
//
// License: MIT
// Date: 2025-12-17

#ifndef HAKMEM_SS_RELEASE_POLICY_BOX_H
#define HAKMEM_SS_RELEASE_POLICY_BOX_H

#include <stdint.h>
#include <stddef.h>
#include <stdbool.h>

// Forward declaration
struct SuperSlab;
typedef struct SuperSlab SuperSlab;

// ============================================================================
// Release Policy API
// ============================================================================

// Check if a superslab should be kept in memory (persistent backend)
//
// Returns:
//   - true: Keep superslab (FAST mode, or LEAN mode with budget remaining)
//   - false: Release superslab (LEAN mode, empty and over budget)
//
// Parameters:
//   - ss: SuperSlab to check
//   - class_idx: Size class (0-7 for Tiny)
//
// Thread-safe: Yes (reads ENV config, no shared state)
bool ss_should_keep_superslab(SuperSlab* ss, int class_idx);

// Attempt to decommit a superslab's memory (reduce RSS)
//
// What it does:
//   - If lean mode disabled: no-op (return immediately)
//   - If lean mode enabled: call madvise(MADV_FREE or MADV_DONTNEED)
//   - Respects DSO guard (skips if address overlaps DSO)
//   - Respects madvise guard (disables on ENOMEM)
//   - Updates lean_decommit counter on success
//
// Returns:
//   - 0: Success (or no-op if lean mode disabled)
//   - -1: Failed (DSO overlap, madvise error, etc.)
//
// Parameters:
//   - ptr: Start of memory region
//   - size: Size of memory region in bytes
//
// Thread-safe: Yes (no shared state mutations except atomic counters)
int ss_maybe_decommit_superslab(void* ptr, size_t size);

#endif // HAKMEM_SS_RELEASE_POLICY_BOX_H