//
//  kwrite_counter.h
//  W0lfSword
//
//  BUG.5 (2026-09-11 device day): "readonly = zero kernel writes" was prose.
//  Nothing counted the writes, so nothing could contradict the sentence - and a
//  reader takes it as "safe to leave running". This module replaces the claim
//  with a measurement: every kernel write this chain issues reaches the kernel
//  through exactly one primitive (`early_kwrite32bytes` - the only call that
//  emits bytes, a 32-byte `setsockopt(ICMP6_FILTER)`), so counting there counts
//  every write, whatever route asked for it.
//
//  The counters are per attempt: `kwrite_count_reset()` is called by
//  `kexploit_opa334()` (and by `kexploit_telemetry_reset()`), and the engine
//  prints a measured summary on the way out, so a readonly run reports a
//  measured 0 instead of asserting one. The host app reads the same numbers
//  through `kexploit_scan_writes()` / `kexploit_scan_write_bytes()`.
//
//  The attribution stack is thread-local on purpose: the scan thread and the
//  pe_init free thread can both write, and one must never be counted as the
//  other. The counters themselves are relaxed atomics - a summary line that is
//  off by a concurrent write-in-flight is still a measurement, a lost increment
//  is not.
//
//  What this module is NOT: it does not decide whether a write is safe (that is
//  krw_zone_write.c's clamp) and it does not make a write happen. It counts what
//  went out and what the kernel refused.
//
#ifndef KWRITE_COUNTER_H
#define KWRITE_COUNTER_H

#include <stdint.h>

// Every write's route into the kernel. The names are the ones the summary line
// prints, so a device log says which primitive issued the writes.
typedef enum {
    KWRITE_SRC_KRW32 = 0,   // early_kwrite32bytes() called directly
    KWRITE_SRC_KRW64,       // early_kwrite64() - a 32-byte RMW around the above
    KWRITE_SRC_ZONE,        // krw_zone_write_block() - the BUG.1 clamped writer
    KWRITE_SRC_COUNT
} kwrite_src_t;

// Per-attempt reset: zeroes the totals and every per-source bucket.
void kwrite_count_reset(void);

// One 32-byte write that the kernel accepted (setsockopt returned 0).
void kwrite_count_emit(kwrite_src_t src, uint32_t len);

// One write the kernel refused. Counted separately and never folded into the
// totals: a refused write did not modify kernel memory, and the claim under
// audit is about writes that landed.
void kwrite_count_failed(kwrite_src_t src, uint32_t len);

uint64_t kwrite_count_total(void);         // accepted writes
uint64_t kwrite_count_bytes(void);         // bytes of accepted writes
uint64_t kwrite_count_failed_total(void);  // refused writes
uint64_t kwrite_count_failed_bytes(void);  // bytes of refused writes
uint64_t kwrite_count_for(kwrite_src_t src);        // accepted, per route
uint64_t kwrite_count_failed_for(kwrite_src_t src); // refused, per route

// Human-readable name of a route ("early_kwrite32bytes", ...). Never NULL, even
// for an out-of-range value - a log line must not be the thing that crashes.
const char *kwrite_src_name(kwrite_src_t src);

// Attribution stack. The outer entry point (early_kwrite64, krw_zone_write_block)
// pushes the route it represents, the emit primitive counts while that route is
// current, and the pop restores whatever the caller had. Nesting works because
// the previous value is returned and handed back.
kwrite_src_t kwrite_src_push(kwrite_src_t src);
void kwrite_src_pop(kwrite_src_t prev);
kwrite_src_t kwrite_src_current(void);

#endif /* KWRITE_COUNTER_H */
