writeonce/database/src/table.h

/* table.h — class-shaped row storage (iteration 9, Task 1).
 *
 * The engine and the VM heap are two memory worlds crossed only by copy
 * (the 9b design's section 6): a row stores NO VM pointer. Every field
 * lands in one 8-byte slot, kind-driven:
 *
 *   SCALAR  the 8 bytes themselves (WO_NIL_SCALAR spells a ?scalar's nil)
 *   TEXT    engine-owned db_text*  (0 = nil)
 *   OWNED   engine-owned db_rec*   — the object flattened by value,
 *           recursively, through these same rules (0 = nil)
 *   MULTI   engine-owned db_multi* — elements encoded element-wise
 *   MAP     engine-owned db_map*   — keys and values encoded pair-wise
 *   GCREF   never stored: the compiler rejects it (the GC bulkhead);
 *           the engine refuses it defensively as an encode error
 *
 * `ref T` is a SCALAR at this layer — the target row's id, an ordinary
 * number the compiler produced; the engine learns nothing about it until
 * the FK checks (9b plan, Task 3).
 *
 * Row layout: a 16-byte header (id, class, flags) then field_cnt 8-byte
 * slots — deliberately the VM object layout's shape, so encode/decode walk
 * the same class-table kinds the VM walks. Rows live in per-class SLABS
 * (fixed-count, malloc'd, never moved: a row's address is stable for its
 * lifetime, which is what lets 9b hand out loop-scoped row views). A
 * per-table bitmap tracks occupancy; removed slots go on a free list and
 * are reused before any slab grows. The id->row map is an open-addressing
 * hash owned by the table.
 *
 * Id discipline (the c-runtime plan's shipped behavior): per table, per
 * shard, ids interleave — shard S of N allocates S+1, S+1+N, S+1+2N, … —
 * so creation is coordination-free and a row's owner shard is (id-1) % N.
 * Milestone runs at N=1 (iteration 8 not yet landed); everything here is
 * N-parametric and degenerates cleanly.
 *
 * CHOKE POINT DOCTRINE: wo_row_insert / wo_row_remove are the only paths
 * that touch storage. Task 4's secondary indexes hook exactly these two
 * functions; anything else mutating a slab is a defect by definition.
 */
#ifndef WO_TABLE_H
#define WO_TABLE_H

#include "obj.h" /* wo_rt, wo_classdesc, kinds, wo_str, containers */

/* ---- engine-owned value shapes (all malloc'd, all reachable only from
 * row slots, all freed through db_val_free) ---- */

typedef struct db_text {
    uint32_t len;
    char bytes[]; /* len bytes, no NUL */
} db_text;

typedef struct db_rec { /* an owned object flattened by value */
    uint32_t class_id;  /* index into the SAME class table the VM uses */
    uint32_t _pad;
    uint64_t slots[]; /* field_cnt slots, encoded by these rules */
} db_rec;

typedef struct db_multi {
    uint8_t elem_kind;
    uint32_t len;
    uint64_t items[];
} db_multi;

typedef struct db_map {
    uint8_t key_kind, val_kind;
    uint32_t len;
    uint64_t kv[]; /* len pairs: k0 v0 k1 v1 … */
} db_map;

/* ---- rows and tables ---- */

typedef struct db_row {
    uint64_t id;
    uint32_t class_id;
    uint32_t flags; /* reserved (0) */
    uint64_t slots[];
} db_row;

#define DB_SLAB_ROWS 256u

/* Secondary index (iteration 9, Task 4): built from the class table's v3
 * metadata at first touch, maintained ONLY inside the row choke points.
 * Hash multimap: bucket per column-value hash, ids within; equality is
 * re-checked against the actual rows on the unique path (a hash is a hint,
 * never an answer). */
typedef struct db_ibucket {
    uint64_t hash;
    uint64_t *ids;
    uint32_t len, cap;
} db_ibucket;

typedef struct db_index {
    uint32_t flags; /* bit0 = unique */
    uint32_t col_cnt;
    const uint32_t *cols; /* into the loader's idx pool */
    db_ibucket *buckets;  /* open addressing by hash; hash==0 stored as 1 */
    size_t bcap, blen;
} db_index;

/* wo_row_insert failure classes — *msg carries the sentence, this carries
 * the machine-readable kind so db.c maps to the right trap. */
enum { DB_ERR_NONE = 0, DB_ERR_OOM = 1, DB_ERR_BADKIND = 2, DB_ERR_UNIQUE = 3, DB_ERR_MISC = 4 };

typedef struct db_table {
    uint32_t class_id;
    size_t row_size; /* 16 + field_cnt * 8 */
    /* slabs of DB_SLAB_ROWS rows each; addresses stable forever */
    uint8_t **slabs;
    uint32_t slab_cnt, slab_cap;
    uint64_t *bitmap; /* one bit per slot, slab-major */
    /* removed slots, reused LIFO before any slab grows */
    uint32_t *free_slots;
    uint32_t free_cnt, free_cap;
    uint64_t next_id; /* next id THIS shard hands out for this table */
    uint64_t count;   /* live rows */
    /* id -> (global slot + 1); 0 = empty. Open addressing, pow2. */
    uint64_t *hkeys;
    uint64_t *hvals;
    size_t hcap, hlen;
    /* secondary indexes, from the class table's v3 metadata */
    db_index *indexes;
    uint32_t index_cnt;
    /* databasev2 2: one reusable materialisation buffer per table, for
     * wo_row_borrow. Per-TABLE and not per-call because the unique shadow
     * check borrows once per candidate inside a bucket loop, and per-call
     * allocation would turn an O(1) probe into an allocation storm. Safe
     * because the store is single-writer (the owner shard) and a borrow is
     * never nested — `busy` exists to catch it if that ever stops being
     * true, rather than aliasing silently. */
    uint8_t *scratch;
    size_t scratch_cap;
    int scratch_busy;
    /* databasev2 11: how many DELTA records the last borrow's fold crossed.
     * The fold reports it for free, and the update path uses it to decide when
     * a chain is long enough to be worth terminating with a full-row record.
     * Meaningful only while scratch_busy is set. */
    uint32_t scratch_hops;
} db_table;

typedef struct wo_db {
    /* databasev2 2 (5c): the runtime this store belongs to, so a borrow can
     * reach the WAL. wo_rt already carries `db` and `wal` as opaque handles,
     * so this closes the loop without threading a wal pointer through
     * wo_row_borrow's eleven call sites — which is the whole reason 5c is one
     * accessor rather than eleven rewrites. NULL in test binaries and with
     * durability off; a `resident: keys` table cannot exist in either case,
     * because it has no log to read rows back from. */
    wo_rt *rt;
    const wo_classdesc *classes;
    uint32_t class_cnt;
    uint32_t shard, nshards; /* S of N; ids interleave S+1, S+1+N, … */
    db_table *tables;        /* class_cnt entries, created lazily on first insert */
} wo_db;

/* 0 ok, -1 alloc failure. nshards >= 1, shard < nshards. */
int wo_db_init(wo_db *db, const wo_classdesc *classes, uint32_t class_cnt,
               uint32_t shard, uint32_t nshards);
void wo_db_destroy(wo_db *db);

/* Insert: encode field_cnt VM values (register words, kinds from the class
 * table) into a fresh row. Returns the new id, or 0 with *msg set (OOM, or
 * a GCREF field — which the compiler should have refused upstream). */
uint64_t wo_row_insert(wo_db *db, uint32_t class_id, const uint64_t *vals,
                       const char **msg, int *err_kind);

/* Read: decode the row's fields into VM values freshly allocated from
 * [rt] — always copies, never a pointer into the slab (the out-gate).
 * 0 ok, -1 no such row, -2 OOM (*msg set). */
int wo_row_read(wo_db *db, wo_rt *rt, uint32_t class_id, uint64_t id,
                uint64_t *out_vals, const char **msg);

/* Remove: free the row's engine-owned field values, clear the slot, recycle
 * it. 0 ok, -1 no such row. */
int wo_row_remove(wo_db *db, uint32_t class_id, uint64_t id);

/* databasev2 2 (5c): drop a row's PAYLOAD while keeping it live.
 *
 * The operation the plan recorded as missing. For a `resident: keys` table the
 * row's bytes live in the log, not in a slab: this frees the slot and its
 * engine-owned values, then re-points the id map at [wal_off] (stored as
 * off + 1, reusing the same 0-is-empty trick the slot encoding uses — a table
 * is wholly `all` or wholly `keys`, so the interpretation is per-table and
 * never ambiguous).
 *
 * What it deliberately does NOT do, and why:
 *   - it does not touch the secondary indexes. They store row IDS, not slots
 *     (see db_ibucket), so they are already indirect through the id map and
 *     stay correct across this.
 *   - it does not decrement `count`. The row is still LIVE; only its backing
 *     moved.
 *   - it does not remove the id. The id is how the row is found afterwards.
 *
 * [wal_off] must be the offset of a record whose commit succeeded. Since
 * databasev2 4 made a failed commit fatal, no execution can reach here with an
 * offset that never became durable — which is what wo_wal_next_offset's
 * contract asks for, now guaranteed by process death rather than by an inline
 * check the deferred barrier no longer allows.
 *
 * 0 ok, -1 unknown class/row. */
int wo_row_drop_payload(wo_db *db, uint32_t class_id, uint64_t id, uint64_t wal_off);
int wo_row_set_offset(wo_db *db, uint32_t class_id, uint64_t id, uint64_t wal_off);

/* databasev2 11: how many DELTA records a keys-resident row's chain may carry
 * before an update terminates it with a full-row image instead of lengthening
 * it. A BOUND, not a tuning knob — PostgreSQL ships `fillfactor` and
 * autovacuum's base threshold as documented constants that are rarely touched,
 * and this is the same kind of number. Anything in the low tens caps the
 * pathology; being wrong by a factor of two costs one row-sized write per K
 * updates, which is not a correctness failure in either direction.
 *
 * It deliberately does NOT scale with table size. PostgreSQL scales autovacuum
 * by reltuples because it thresholds a table-level aggregate whose harm is
 * proportional; a chain is a per-ROW property with additive cost — reading one
 * row costs 1 + depth reads whether the table holds a hundred rows or ten
 * million, and replay is the sum over every row's chain. Scaling this up with
 * table size would make the largest databases boot worst. */
#define WO_DELTA_MAX_HOPS 16u
uint64_t wo_row_offset1(const wo_db *db, uint32_t class_id, uint64_t id);

/* databasev2 2 (5d): iterate the live row IDS of a table, whichever backing it
 * has. [*cursor] starts at 0 and is opaque; returns 1 with *id_out set, or 0
 * when exhausted.
 *
 * A keys-resident table has an EMPTY bitmap by construction — its payloads live
 * in the log — so every bitmap walk in the engine would silently see no rows.
 * This is the one primitive those walks move onto.
 *
 * Resident tables keep walking the bitmap, deliberately: the id map holds the
 * same set, but in hash order, and switching would reorder the results of every
 * unordered query in the repo. Two backings, one interface, no behaviour change
 * where nothing needed to change. */
int wo_row_next_id(const wo_db *db, uint32_t class_id, size_t *cursor, uint64_t *id_out);

/* databasev2 2 (5c): is this table's row data in the log rather than in slabs? */
int wo_table_is_keys_resident(const wo_db *db, uint32_t class_id);

/* iteration 9b FK restrict: 1 if some row in some class holds a non-nullable
 * `ref` to [class_id] equal to [id] — i.e. deleting this row would dangle a
 * reference. The compiler records a ref field's target class in the class
 * table's field_class metadata; this scans those columns. Correctness-first
 * (a full scan of referencing tables); the backlink index is the later
 * optimization the spec records. */
int wo_row_has_referrers(wo_db *db, uint32_t class_id, uint64_t id);

/* Update one field in place (iteration 9 Task 5): encode the VM value,
 * swap it into the slot, keep every index containing that column honest —
 * remove-old/add-new with the unique re-check running BEFORE anything
 * mutates, so a violating update leaves the row untouched. 0 ok, -1 no
 * such row / bad field, DB_ERR_* codes via *err_kind like insert. */
int wo_row_update_field(wo_db *db, uint32_t class_id, uint64_t id, uint32_t field,
                        uint64_t vm_val, const char **msg, int *err_kind);

/* Borrowed row pointer for engine-internal callers (the WAL writes a row's
 * encoded bytes; indexes read key slots). NULL = no such row. NEVER handed
 * to the VM. */
db_row *wo_row_ptr(wo_db *db, uint32_t class_id, uint64_t id);

/* ---- databasev2 2: the shared row accessor -------------------------------
 *
 * Every reader that today does `wo_row_ptr` and then touches `r->slots[...]`
 * uses this pair instead, so ONE code path serves both residencies:
 *
 *   resident: all   borrow returns the slab pointer; release is a no-op
 *   resident: keys  borrow materialises the record from its log offset into
 *                   the table's scratch; release frees what it built
 *
 * Landed as a PURE REFACTOR: until the offset storage exists, borrow is
 * wo_row_ptr plus a branch and every release is a no-op. Deliberate — the
 * refactor is provable on its own, before the storage change it enables.
 *
 * A borrowed row is READ-ONLY when it is materialised: it is a copy, so
 * writing to it changes nothing durable. Mutation still goes through the row
 * choke points. Pair EVERY non-NULL borrow with a release, and never nest two
 * borrows on the same table — they would share one scratch. */
db_row *wo_row_borrow(wo_db *db, uint32_t class_id, uint64_t id, const char **msg);
void wo_row_release(wo_db *db, uint32_t class_id, db_row *r);

/* Engine-internal, for WAL replay only: create a row with a FIXED id,
 * slots zeroed — the caller (wal.c) fills them with engine-encoded values
 * it built while decoding. Advances the table's next_id past [id] when the
 * id belongs to this shard, so post-replay inserts never collide. NULL =
 * OOM or duplicate id (corruption beyond a torn tail). */
db_row *wo_row_create_raw(wo_db *db, uint32_t class_id, uint64_t id);

/* Engine-internal: free one engine-encoded slot value of [kind] (wal.c's
 * decode error paths). */
void wo_db_val_free(wo_db *db, uint8_t kind, uint64_t v);

/* Decode one engine slot value to a FRESH VM value in [rt] (the out-gate:
 * always a copy). The query builtins' field reads go through this. */
uint64_t wo_val_decode_vm(wo_db *db, wo_rt *rt, uint8_t kind, uint64_t engine_val,
                          int *ok, const char **msg);

/* Read-path index probe (the O(1) wiring): answer a SINGLE-COLUMN
 * equality from the index's hash buckets instead of walking slabs.
 * Key representation is caller-neutral so wo_str and db_text callers
 * both fit: a Text key passes its bytes+len (bytes == NULL means nil;
 * an empty text is a non-NULL pointer with len 0); any scalar/float
 * key passes the raw word in [key_scalar] (bytes ignored). The bucket
 * hash canonicalizes floats exactly as index maintenance does; the
 * VERIFY step then compares exactly as the slab walk compares (raw
 * words for scalars/floats, byte equality for text) — a hash is a
 * hint, never an answer, so results are identical to the scan.
 * Returns 1 = probed (*out_ids is a malloc'd id list of *out_cnt,
 * possibly NULL/0 — the caller frees), 0 = cannot probe (unknown
 * class/index, untouched table, or a multi-column index — the caller
 * keeps its scan fallback), -1 = OOM. */
int wo_idx_probe(wo_db *db, uint32_t class_id, uint32_t index, uint64_t key_scalar,
                 const void *key_bytes, uint32_t key_len, uint64_t **out_ids,
                 uint32_t *out_cnt);

/* Engine-internal, replay only: after wal.c fills a raw row's slots, this
 * runs the index maintenance the normal insert runs inline — including the
 * unique check, whose violation during replay is corruption, not data
 * (0 ok, -1). */
int wo_row_raw_commit(wo_db *db, uint32_t class_id, db_row *r);

/* ---- arc stage 3: the slot-level surface the transparent DB RPC uses ----
 * VM heaps are never read cross-shard (a worker's GC writes header mark
 * bits concurrently), so the REQUESTER shard encodes its VM values into
 * engine-owned slots on its own thread and ships those; the OWNER shard
 * executes from slots. Everything here is thread-agnostic: it touches only
 * the wo_db it is handed and engine-owned mallocs. */

/* Encode one VM value into an engine slot on the caller's thread (the
 * in-gate, split out of wo_row_insert for the RPC path). */
uint64_t wo_db_val_encode(const wo_classdesc *classes, uint8_t kind, uint64_t vm_val,
                          int *ok, const char **msg);

/* Deep-copy one engine value — a GET_FIELD reply must outlive the row it
 * was read from (a later statement may free the row's slot). */
uint64_t wo_db_val_clone(const wo_classdesc *classes, uint8_t kind, uint64_t v, int *ok);

/* Insert from PRE-ENCODED slots (field_cnt of them). Ownership of the slot
 * VALUES transfers: installed on success, freed on failure. New id, or 0
 * with *msg / *err_kind set exactly as wo_row_insert sets them. */
uint64_t wo_row_insert_slots(wo_db *db, uint32_t class_id, const uint64_t *slots,
                             const char **msg, int *err_kind);

/* Update one field from a PRE-ENCODED slot value (consumed either way:
 * installed on success, freed on failure). Same contract as
 * wo_row_update_field after its encode. */
int wo_row_update_field_slot(wo_db *db, uint32_t class_id, uint64_t id, uint32_t field,
                             uint64_t slot, const char **msg, int *err_kind);

#endif /* WO_TABLE_H */