//
//  probe_restore_policy.h
//  W0lfSword
//
//  BUG.1 (2026-09-11 device day): the two decisions that decide whether the
//  staged write probe leaves a live inpcb corrupted, split out of
//  kexploit/kexploit_opa334.m so they can be compiled and exercised on the host
//  (tests/krw_zone_write_host_test.c drives THIS file; the engine compiles and
//  links the same object, so the host test and the device run cannot disagree
//  about the rule).
//
//  1. WHAT EVERY EXIT OF THE PROBE DOES (probe_exit_action_for)
//     The probe returns KERN_SUCCESS exactly once, and only after the corruption
//     has been promoted to the krw primitive: there the corrupted socket IS the
//     primitive the caller is about to use, so restoring it would end the run
//     (and the caller restores it itself on run_write_test / the staged
//     stage-2 failure path). Every OTHER return - write-verify exhaustion, the
//     alias write not confirmed, the krw fds not live, the chksum expectation
//     mismatch, the round-trip failure, cancel/budget (-7), the early "not our
//     PCB" returns, and any exit added later - must restore before the caller
//     sees it. That is why the default here is RESTORE and not hand-off: a
//     future exit code is covered by default instead of silently walking away
//     from a corrupted object (the 2026-09-11 SE panic class).
//
//  2. WHICH FDS THE RESTORE MAY WRITE THROUGH (probe_restore_fd_source)
//     The restore puts the saved values back by writing through the two sockets
//     whose inpcb was corrupted. It could only re-open them from the spray
//     tracking array (socketPorts / socketPcbIds), which pe_v1's release funnel
//     empties via sockets_release() BEFORE the caller's own restore runs - so
//     the staged -5 path (kernel-base scan exhausted) logged "probe restore
//     FAILED ... krw socket not live" with the corruption still in the kernel,
//     i.e. BUG.1 one exit later, and nothing was ever written back.
//     The fds the promotion opened ARE the same socket pair and nothing closes
//     them, so they are the fallback - but only for the corruption they were
//     opened for: the engine passes promotionPairLive == false unless the fds'
//     save generation and socket index still match the corruption being
//     restored, never "some earlier socket's fds are still non-zero".
//     When neither source is available the verdict is UNREACHABLE, which the
//     engine turns into a loud "[STAGED] probe restore FAILED" line instead of a
//     silent success.
//
#ifndef probe_restore_policy_h
#define probe_restore_policy_h

#include <stdbool.h>

// The probe's promotion return value (KERN_SUCCESS). Named here so the policy
// does not have to drag in mach/Foundation headers to say "this is the one
// deliberate hand-off".
#define PROBE_EXIT_PROMOTED 0

typedef enum {
    PROBE_ACTION_HAND_OFF = 0,   // the caller owns the (deliberate) live corruption
    PROBE_ACTION_RESTORE,        // put the saved fields back before returning
} probe_exit_action;

// Every exit of the write probe. Default RESTORE - see note 1 above.
probe_exit_action probe_exit_action_for(int probeRc);

typedef enum {
    PROBE_FD_SOURCE_FILEPORTS = 0,   // the spray tracking array still holds the pair
    PROBE_FD_SOURCE_PROMOTION_FDS,   // the pair the promotion opened (same socket pair)
    PROBE_FD_SOURCE_UNREACHABLE,     // neither: the restore cannot write - report it
} probe_fd_source;

// trackingArrayHoldsPair: socketPorts still holds g_probe_control_idx / +1.
// promotionPairLive:     controlSocket / rwSocket are the pair opened for the
//                        corruption being restored (generation + index match).
probe_fd_source probe_restore_fd_source(bool trackingArrayHoldsPair,
                                        bool promotionPairLive);

#endif /* probe_restore_policy_h */
