typedef struct session {
    /* ── Lookup key (must match hash table key size) ─── */
    flow_key_t   key;            /* canonical five-tuple, 40B */

    /* ── Protocol state ─────────────────────────────── */
    uint8_t      proto;          /* IPPROTO_TCP, _UDP, _ICMP */
    uint8_t      tcp_state;      /* TCP_S_SYN_SENT .. TCP_S_CLOSED */
    uint8_t      flags;          /* F_NAT, F_TLS_INSPECT, F_LOG */

    /* ── TCP sequence tracking ───────────────────────── */
    uint32_t     fwd_seq;        /* highest seq seen (forward) */
    uint32_t     rev_seq;        /* highest seq seen (reverse) */
    uint32_t     fwd_ack;        /* last ACK seen (forward) */
    uint32_t     rev_ack;
    uint32_t     fwd_window;     /* advertised receive window */
    uint32_t     rev_window;
    uint8_t      fwd_wscale;     /* window scale factor (TCP option) */
    uint8_t      rev_wscale;

    /* ── Timestamps ──────────────────────────────────── */
    uint64_t     created_ns;     /* session birth (CLOCK_MONOTONIC) */
    uint64_t     last_seen_ns;   /* last packet timestamp */
    uint32_t     timeout_s;      /* per-protocol inactivity timeout */
    uint32_t     expire_tick;    /* timer wheel bucket */

    /* ── Traffic counters ────────────────────────────── */
    uint64_t     fwd_pkts;
    uint64_t     fwd_bytes;
    uint64_t     rev_pkts;
    uint64_t     rev_bytes;

    /* ── NAT rewrite (populated if F_NAT set) ────────── */
    uint32_t     nat_src_ip;     /* translated src IP (SNAT) */
    uint16_t     nat_src_port;   /* translated src port (NAPT) */
    uint32_t     nat_dst_ip;     /* translated dst IP (DNAT) */
    uint16_t     nat_dst_port;   /* translated dst port (DNAT) */

    /* ── Application layer ───────────────────────────── */
    uint16_t     app_id;         /* identified app: HTTP=1, TLS=2, DNS=3... */
    uint8_t      risk_score;     /* 0–100 threat score from DPI */
    void        *dpi_state;      /* DPI engine per-flow state machine */

    /* ── Policy result (cached after first policy eval) ─ */
    uint32_t     policy_id;      /* matched ACL rule index */
    uint8_t      action;         /* ACTION_PERMIT, _DENY, _INSPECT */
    uint8_t      ssl_inspect;    /* 1 = TLS MITM proxy active */

    /* ── Linked list for timer wheel ─────────────────── */
    struct session *tw_next;
    struct session *tw_prev;

} __attribute__((packed)) session_t;
/* Target size: ≤ 256 bytes per session */
/* 1M sessions × 256B = 256MB — fits in L3 cache on server CPUs */
/* Typical enterprise NGFW: 500K–4M concurrent sessions */

/* TCP states from NGFW perspective (observer, not endpoint) */
typedef enum {
    TCP_S_NONE = 0,    /* no session — first packet */
    TCP_S_SYN_SENT,    /* SYN seen from initiator */
    TCP_S_SYN_RCVD,    /* SYN+ACK seen from responder */
    TCP_S_ESTABLISHED, /* ACK completing 3-way handshake */
    TCP_S_FIN_WAIT_1,  /* FIN from initiator */
    TCP_S_FIN_WAIT_2,  /* FIN ACKed by responder */
    TCP_S_CLOSE_WAIT,  /* FIN from responder (responder closing first) */
    TCP_S_LAST_ACK,    /* FIN from initiator after CLOSE_WAIT */
    TCP_S_TIME_WAIT,   /* waiting for stray packets */
    TCP_S_CLOSED,      /* RST received or graceful close complete */
} tcp_state_t;

/* State transition table */
uint8_t tcp_next_state[TCP_S_CLOSED+1][2 /*dir*/][64 /*flags*/];

/* Build the table at init (simplified) */
void tcp_init_transitions(void) {
    /* SYN from initiator → create session, SYN_SENT */
    /* Handled at session creation, not in table */

    /* SYN+ACK from responder → SYN_RCVD */
    tcp_next_state[TCP_S_SYN_SENT][0/*rev*/][TH_SYN|TH_ACK] = TCP_S_SYN_RCVD;

    /* ACK from initiator → ESTABLISHED */
    tcp_next_state[TCP_S_SYN_RCVD][1/*fwd*/][TH_ACK] = TCP_S_ESTABLISHED;

    /* FIN from initiator → FIN_WAIT_1 */
    tcp_next_state[TCP_S_ESTABLISHED][1/*fwd*/][TH_FIN]     = TCP_S_FIN_WAIT_1;
    tcp_next_state[TCP_S_ESTABLISHED][1/*fwd*/][TH_FIN|TH_ACK] = TCP_S_FIN_WAIT_1;

    /* ACK of FIN → FIN_WAIT_2 */
    tcp_next_state[TCP_S_FIN_WAIT_1][0/*rev*/][TH_ACK]      = TCP_S_FIN_WAIT_2;

    /* RST → CLOSED from any state */
    for (int st = 0; st <= TCP_S_CLOSED; st++) {
        tcp_next_state[st][0][TH_RST] = TCP_S_CLOSED;
        tcp_next_state[st][1][TH_RST] = TCP_S_CLOSED;
    }
    /* ... more transitions ... */
}

/* Fast-path state lookup */
uint8_t new_state = tcp_next_state[s->tcp_state][is_initiator][tcp_flags & 0x3f];
if (new_state != s->tcp_state) {
    s->tcp_state = new_state;
    if (new_state == TCP_S_CLOSED)
        session_schedule_destroy(s, 5);   /* brief grace period */
}

/* Port pool — bitmap allocator, O(1) amortised */
typedef struct {
    uint32_t public_ip;
    uint16_t port_start;   /* 1024 */
    uint16_t port_end;     /* 65535 */
    uint8_t  bitmap[8192]; /* 64512 ports / 8 = 8064 bytes */
    uint16_t next_hint;    /* round-robin start hint */
    uint32_t in_use;       /* current count */
} nat_port_pool_t;

uint16_t nat_alloc_port(nat_port_pool_t *pool) {
    uint16_t start = pool->next_hint;
    for (int i = 0; i < 64512; i++) {
        uint16_t p   = pool->port_start + ((start + i) % 64512);
        uint32_t off = (p - pool->port_start);
        uint32_t by  = off / 8, bi = off % 8;
        if (!(pool->bitmap[by] & (1u << bi))) {
            pool->bitmap[by] |= (1u << bi);
            pool->next_hint = (start + i + 1) % 64512;
            pool->in_use++;
            return p;
        }
    }
    return 0;  /* port exhaustion */
}

void nat_free_port(nat_port_pool_t *pool, uint16_t port) {
    uint32_t off = port - pool->port_start;
    pool->bitmap[off / 8] &= ~(1u << (off % 8));
    pool->in_use--;
}

/* Packet rewrite — what changes in each direction */
/*
  Outbound SNAT:
    IP  header: src_addr = nat_src_ip     (was private IP)
    TCP header: src_port = nat_src_port   (was ephemeral port)
    Checksums:  both IP and TCP/UDP must be updated

  Inbound reverse:
    IP  header: dst_addr = orig_src_ip    (restore private IP)
    TCP header: dst_port = orig_src_port  (restore original port)
    Checksums:  updated

  DNAT outbound:
    IP  header: dst_addr = real_server_ip
    TCP header: dst_port = real_server_port

  DNAT inbound (reply):
    IP  header: src_addr = public_vip_ip
    TCP header: src_port = published_port
*/

/* Incremental checksum update (RFC 1624) */
/* Much faster than full recalculation — only 1-2 words changed */
static inline uint16_t csum_update_u32(uint16_t old_csum,
                                        uint32_t old_val, uint32_t new_val) {
    uint32_t s = (uint16_t)~old_csum;
    s += (uint16_t)~(old_val & 0xFFFF) + (uint16_t)~(old_val >> 16);
    s += (uint16_t)(new_val & 0xFFFF)  + (uint16_t)(new_val >> 16);
    while (s >> 16) s = (s & 0xFFFF) + (s >> 16);
    return (uint16_t)~s;
}

void nat_rewrite_outbound(struct iphdr *iph, struct tcphdr *th,
                           uint32_t new_sip, uint16_t new_sport) {
    uint32_t old_sip   = iph->saddr;
    uint16_t old_sport = th->source;

    iph->saddr  = htonl(new_sip);
    th->source  = htons(new_sport);

    /* Update IP checksum (covers IP header — 32-bit addr field) */
    iph->check = csum_update_u32(iph->check, old_sip, new_sip);

    /* Update TCP/UDP checksum (pseudo-header includes src IP + port) */
    th->check = csum_update_u32(th->check, old_sip, new_sip);
    th->check = csum_update_u32(th->check,
                                (uint32_t)ntohs(old_sport),
                                (uint32_t)new_sport);
}
/* Hardware offload (DPDK RTE_MBUF_F_TX_IP_CKSUM) avoids software calc */