ABI — epoch 2

The frozen contract (PLATFORM.md §6). This page embeds the header verbatim; the docs build fails if the file moves.

#pragma once
/* Caliper ABI — epoch 2. FROZEN: any change here is an epoch bump (§14).
 * C types only; no STL, exceptions, or third-party types (§6c). */
#include <stdint.h>
#include <stdbool.h>

#define CALIPER_ABI_EPOCH 2
#define CALIPER_DESCRIPTOR_SYMBOL "caliper_applet_descriptor"

#if defined(_WIN32)
  #define CALIPER_EXPORT __declspec(dllexport)
#else
  #define CALIPER_EXPORT __attribute__((visibility("default")))
#endif

#ifdef __cplusplus
extern "C" {
#endif

/* The host is a service registry, not a struct of fields (§6b). */
typedef struct CaliperHost {
    uint32_t    struct_size;      /* sizeof(CaliperHost) as the host built it */
    uint32_t    abi_epoch;        /* epoch this host speaks */
    uint32_t    host_version;     /* (major<<16)|(minor<<8)|patch */
    const char* applet_data_dir;  /* per-applet sandbox dir, UTF-8, host-owned */
    /* Returns a service table or NULL; pointer valid for the applet's
     * lifetime. Unknown ids return NULL — never UB. */
    const void* (*get_service)(const struct CaliperHost* host,
                               const char* service_id);
} CaliperHost;

/* Pixel-space contract (§6a): fb_* are PHYSICAL framebuffer pixels; ImGui
 * coordinates are logical units; physical = logical * dpi_scale. */
typedef struct CaliperFrameInfo {
    uint32_t struct_size;
    int32_t  fb_width;
    int32_t  fb_height;
    float    dpi_scale;
    double   time_sec;
    double   delta_sec;
} CaliperFrameInfo;

typedef struct CaliperAppletAPI {
    uint32_t struct_size;
    void* (*create)(void);
    void  (*destroy)(void* self);
    bool  (*initialize)(void* self, const CaliperHost* host);
    void  (*frame)(void* self, const CaliperFrameInfo* info);
    void  (*cleanup)(void* self);
    /* future entry points are APPENDED here, guarded by struct_size */
} CaliperAppletAPI;

typedef struct CaliperAppletDescriptor {
    uint32_t struct_size;
    uint32_t abi_epoch;                   /* must equal a host-supported epoch */
    const char* id;                       /* reverse-DNS, matches manifest */
    const char* version;                  /* applet semver, matches manifest */
    const char* name;
    const char* summary;
    const char* tag;
    const char* const* required_services; /* NULL-terminated; may be NULL */
    CaliperAppletAPI api;
} CaliperAppletDescriptor;

/* Every epoch-2 applet exports exactly one symbol:
 *   const CaliperAppletDescriptor* caliper_applet_descriptor(void);
 * (generated by CALIPER_APPLET in caliper.hpp, or hand-written in C). */

#ifdef __cplusplus
}
#endif