#ifndef VMSIG_CTX_H
#define VMSIG_CTX_H
#include "vmsig_event.h"

/* vmsig_ctx.h — the "transfer context": the SISC-critical seam owning PRIORITY,
 * SEQUENCING and PROTOCOL timing of delivery. Behavioral timing does NOT belong
 * here — commands arrive already decided from control; the context merely
 * orders and paces them on the "wire". */

typedef struct vmsig_ctx vmsig_ctx;   /* opaque: queues, seq, timing */

/* Protocol (RS232-like) transmission timings — transport ONLY, not behavior.
 * All zeros = pass-through (no pacing). */
typedef struct {
    uint32_t min_gap_ns;     /* min. gap between channel events (rate-cap)    */
    uint32_t coalesce_ns;    /* collapse bursts of one kind within a window   */
    uint32_t max_inflight;   /* backpressure depth on a channel before drop   */
    uint8_t  drop_policy;    /* VMSIG_DROP_*                                  */
} vmsig_timing;

#define VMSIG_DROP_OLDEST 0
#define VMSIG_DROP_NEWEST 1
#define VMSIG_DROP_BLOCK  2

vmsig_ctx* vmsig_ctx_new(void);
void       vmsig_ctx_free(vmsig_ctx* c);

/* Policy per (source,dir): default priority + protocol timing. They live
 * here, NOT in adapters and NOT in control. */
int  vmsig_ctx_set_policy(vmsig_ctx* c, vmsig_source src, vmsig_dir dir,
                          vmsig_prio default_prio, const vmsig_timing* t);

/* Enqueue an event into the `dir`-direction context (assigns seq, applies
 * priority/timing/coalescing/backpressure). 0 — enqueued, 1 —
 * coalesced/dropped by policy, -1 — error. On success takes ownership of
 * ev->payload. Thread-safe (the UP side is called from worker threads). */
int  vmsig_ctx_submit(vmsig_ctx* c, vmsig_dir dir, vmsig_event* ev);

/* Fetch the next event of direction `dir` ready for delivery, honoring
 * priority + protocol timing. 1 — event written to out, 0 — nothing yet
 * (caller arms timing_fd), -1 — error. */
int  vmsig_ctx_next(vmsig_ctx* c, vmsig_dir dir, vmsig_event* out);

/* timerfd by which the context wakes the loop when a paced/coalesced event
 * has matured. Registered in the core like any source. -1 if not needed. */
int  vmsig_ctx_timing_fd(vmsig_ctx* c, vmsig_dir dir);

#endif /* VMSIG_CTX_H */