//
//  krw_zone_write.h
//  W0lfSword
//
//  BUG.1 steps 3 / 3b - the 32-byte block writer behind kwrite_zone_element().
//
//  This is split out of krw.m (which pulls in Foundation/UIKit headers) so the
//  block sequencing and the bound check can be compiled and exercised on the
//  host: tests/krw_zone_write_host_test.c drives THIS file against a fake
//  kernel window and fails if a single emitted block leaves the object, which
//  on device is not a bug report but a panic (2026-09-11 SE, zalloc.c:1322).
//
//  Kernel access happens only through the two block primitives declared at the
//  bottom: the engine implements them in krw.m, the host test implements them
//  over a byte array.
//
//  THE CONTRACT (step 3b): nothing is ever written without a declared object.
//  Every block this primitive can emit is 0x20 bytes wide and is written at an
//  address the caller derived from its own bookkeeping, so a block is provably
//  safe only relative to the allocation that contains it - and only the caller
//  knows that allocation. A call with no declaration (or with a declaration
//  that does not contain the target) is therefore REFUSED, not written
//  unproven: that refusal is what the 2026-09-11 SE write was missing.
//
#ifndef krw_zone_write_h
#define krw_zone_write_h

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

// Width of one kernel write the primitive can emit. Must equal
// EARLY_KRW_LENGTH (kexploit_opa334.h); krw.m static_asserts the two agree, so
// the arithmetic here can never describe a different block than the bytes that
// actually go out.
#define KRW_ZONE_BLOCK_LEN 0x20

typedef enum {
    KRW_ZONE_OK = 0,
    KRW_ZONE_REFUSE_LEN,               // len < one block: not supported
    KRW_ZONE_REFUSE_UNDECLARED,        // no enclosing object declared: nothing to prove against
    KRW_ZONE_REFUSE_NO_OBJECT_SHIFT,   // tail block would be shifted, object unknown (same refusal, for the log)
    KRW_ZONE_REFUSE_SHIFT_BEFORE_BASE, // shifted block would start before the object
    KRW_ZONE_REFUSE_PAST_END,          // a block would leave the object
} krw_zone_verdict;

// True when [base, base+size) is a usable declaration for a write at dst.
// size == 0 or base == 0 ("nothing declared"), a window that wraps, and any
// window that does not contain dst, are all treated as no declaration - a
// stale or foreign declaration can never authorise a write.
bool krw_zone_window_contains(uint64_t dst, uint64_t base, uint64_t size);

// The 0x20-aligned block a qword write at `addr` goes into (addr itself when it
// is already aligned). KRW_ZONE_BLOCK_LEN is a power of two on purpose: the
// aligned block never spans two allocation units the way an unaligned 32-byte
// RMW does.
uint64_t krw_zone_block_align_down(uint64_t addr);

// The declaration a caller can derive from its own field table: the window that
// holds every field up to and including one that ENDS at `fieldEnd`, rounded up
// to a whole block (allocation sizes are multiples of the block width, so a
// field ending at 0x158 implies a window of at least 0x160). 0 in = 0 out
// ("nothing to declare"), and an unreasonable fieldEnd yields 0 rather than a
// wrapped window.
uint64_t krw_zone_window_for_field_end(uint64_t fieldEnd);

// Pure decision for one call, no kernel access. haveObj is passed in (rather
// than recomputed) so the branch that compares the shifted block start against
// the object base can be tested directly.
// blockStartOut receives the address of the LAST block - the one the backward
// shift moves. Every block of the range is checked here, before anything is
// written, so a refusal can never leave a half-applied write.
krw_zone_verdict krw_zone_check_bounds(uint64_t dst, uint64_t len,
                                       uint64_t objBase, uint64_t objSize,
                                       bool haveObj,
                                       uint64_t *blockStartOut);

// Decide and emit a byte range. Nothing is written unless the whole range
// passed the check. Refused when no object is declared (see the contract above).
krw_zone_verdict krw_zone_write(uint64_t dst, const void *src, uint64_t len,
                               uint64_t objBase, uint64_t objSize);

// Decide and emit one qword - the write early_kwrite64() performs, with the
// bound check early_kwrite64() does not have. The block read-patched-written is
// the 0x20-aligned block containing dst, so the bytes it touches are the same
// width as every other write here and are provably inside the declared window;
// an unaligned 32-byte RMW at dst would instead straddle two aligned blocks.
krw_zone_verdict krw_zone_write_qword(uint64_t dst, uint64_t value,
                                      uint64_t objBase, uint64_t objSize);

// Primitives: exactly KRW_ZONE_BLOCK_LEN bytes in / out at an absolute kernel
// address. Provided by the engine (krw.m) and by the host test.
void krw_zone_read_block(uint64_t where, uint8_t *buf);
void krw_zone_write_block(uint64_t where, const uint8_t *buf);

#endif /* krw_zone_write_h */
