snapshot.h

/*
** Snapshot system core data structures for the extensible SQL parser.
**
** A ParserSnapshot captures the complete state of a parser's tables at a
** point in time. Snapshots use atomic reference counting so they can be
** safely shared across threads: readers acquire a reference before use and
** release it when done. When the last reference is released the snapshot
** and all of its owned memory are freed.
*/
#ifndef SNAPSHOT_H
#define SNAPSHOT_H
 
#include <stdint.h>
#include <stdbool.h>
#include <stdatomic.h>
 
/* Forward declarations for Lemon grammar structures.
** The actual definitions live in lemon.c; snapshot consumers only
** need pointers to these types. */
struct symbol;
struct rule;
struct state;
 
/* ------------------------------------------------------------------ */
/*  Semantic versioning                                                */
/* ------------------------------------------------------------------ */
 
typedef struct SemVer {
    uint32_t major;             
    uint32_t minor;             
    uint32_t patch;             
    char *prerelease;           
} SemVer;
 
typedef enum VersionOp {
    VERSION_OP_EQ = 0,            /* == exact match                    */
    VERSION_OP_GTE,               /* >= greater-than-or-equal          */
    VERSION_OP_LTE,               /* <= less-than-or-equal             */
    VERSION_OP_GT,                /* >  strictly greater               */
    VERSION_OP_LT,                /* <  strictly less                  */
    VERSION_OP_CARET,             /* ^  compatible (same major)        */
    VERSION_OP_TILDE,             /* ~  approximately (same major.minor) */
} VersionOp;
 
typedef struct VersionConstraint {
    VersionOp op;               
    SemVer version;             
} VersionConstraint;
 
/* ------------------------------------------------------------------ */
/*  Module dependency metadata                                         */
/* ------------------------------------------------------------------ */
 
typedef struct ParserDependency {
    char *module_name;              
    uint8_t merkle_root[32];        
    VersionConstraint *constraints; 
    uint32_t nconstraints;          
    bool optional;                  
} ParserDependency;
 
typedef struct ParserModule {
    char *name;                     
    SemVer version;                 
    ParserDependency *dependencies; 
    uint32_t ndependencies;         
    char **exports;                 
    uint32_t nexports;              
    char **imports;                 
    uint32_t nimports;              
} ParserModule;
 
/* ------------------------------------------------------------------ */
/*  Snapshot                                                           */
/* ------------------------------------------------------------------ */
 
/*
** A ParserSnapshot holds a frozen copy of every table the generated parser
** needs at runtime. Fields fall into three groups:
**
**   1. Bookkeeping   - version, refcount, timestamps
**   2. Grammar data  - symbols, rules, states (deep copies)
**   3. Action tables  - the compact arrays that drive the parse engine
**   4. Module data   - optional module identity and content hash
*/
typedef struct ParserSnapshot {
    uint64_t version;
 
    atomic_uint_fast32_t refcount;
 
    /* --- Grammar data (deep-copied, owned by this snapshot) ----------- */
 
    struct symbol **symbols;       
    uint32_t nsymbol;              
    uint32_t nterminal;            
    struct rule *rules;            
    uint32_t nrule;                
    struct state **states;         
    uint32_t nstate;               
    /* --- Compact action tables (heap-allocated, owned) ---------------- */
 
    uint16_t *yy_action;           
    uint16_t *yy_lookahead;        
    int16_t  *yy_shift_ofst;       
    int16_t  *yy_reduce_ofst;      
    uint16_t *yy_default;          
    uint32_t action_count;         
    uint32_t lookahead_count;      
    /* --- Module identity (optional, NULL when not part of a module) --- */
 
    uint8_t merkle_root[32];       
    ParserModule *module;          
    uint64_t create_time_ns;
 
    void *jit_ctx;
} ParserSnapshot;
 
/*
** Acquire a reference to an existing snapshot.  The caller must eventually
** call snapshot_release() to avoid leaking the snapshot.
**
** Returns the same pointer that was passed in, for convenience:
**     ParserSnapshot *my_ref = snapshot_acquire(shared_snap);
**
** Passing NULL is safe and returns NULL.
*/
ParserSnapshot *snapshot_acquire(ParserSnapshot *snap);
 
/*
** Release a reference previously obtained via snapshot_acquire() or
** create_base_snapshot().  When the last reference is released the
** snapshot and all memory it owns are freed.
**
** Passing NULL is safe and does nothing.
*/
void snapshot_release(ParserSnapshot *snap);
 
/*
** Create a base snapshot by parsing *grammar_file* through the Lemon
** parser generator.  On success a new snapshot with refcount == 1 is
** returned and *error is set to NULL.  On failure NULL is returned and
** *error points to a malloc'd error message that the caller must free.
**
** NOTE: This is currently a stub.  Full implementation comes when Lemon
** is modified to emit dynamic tables (Task #3).
*/
ParserSnapshot *create_base_snapshot(const char *grammar_file, char **error);
 
/* ------------------------------------------------------------------ */
/*  SemVer utilities                                                   */
/* ------------------------------------------------------------------ */
 
/*
** Parse a semantic version string ("1.2.3" or "1.2.3-beta.1") into a
** SemVer struct.  Returns true on success.  On failure *out is zeroed
** and the function returns false.
*/
bool semver_parse(const char *str, SemVer *out);
 
/*
** Compare two semantic versions.  Returns <0, 0, or >0 following the
** same convention as strcmp.  Prerelease versions sort before their
** release counterpart (e.g. 1.0.0-alpha < 1.0.0).
*/
int semver_compare(const SemVer *a, const SemVer *b);
 
/*
** Check whether *ver* satisfies *constraint*.
*/
bool semver_satisfies(const SemVer *ver, const VersionConstraint *constraint);
 
/*
** Free resources owned by a SemVer (just the prerelease string).
** Does not free the SemVer struct itself.
*/
void semver_destroy(SemVer *v);
 
/* ------------------------------------------------------------------ */
/*  Module lifecycle helpers                                           */
/* ------------------------------------------------------------------ */
 
/*
** Deep-free a ParserModule and all memory it owns (name, version,
** dependencies, exports, imports).  Does not free the pointer itself
** unless *mod* was heap-allocated by the caller.
*/
void parser_module_destroy_contents(ParserModule *mod);
 
/*
** Deep-free a ParserDependency's owned memory.
*/
void parser_dependency_destroy_contents(ParserDependency *dep);
 
#endif /* SNAPSHOT_H */