exhaustive doc comment for the RuntimeTable class

Author: querolita

src/lib/provable/gadgets/runtime-table.ts

@@ -11,8 +11,80 @@ export {
 };
 
 /**
- * The `RuntimeTable` class represents a provable table whose entries can be defined
- * at runtime. It allows inserting key-value pairs and checking for their existence.
+ * # RuntimeTable
+ *
+ * A **provable lookup table** whose entries are defined at runtime (during circuit construction).
+ * It constrains that certain `(index, value)` pairs *exist* in a table identified by `id`, using
+ * efficient **lookup gates** under the hood. Each inner lookup gate can batch up to **3 pairs**.
+ *
+ * ## When to use
+ * - **small/medium, runtime-chosen set** of `(index, value)` pairs and want to prove
+ *   **membership** of queried pairs in that set.
+ * - **ergonomic batching**: repeated `lookup()` calls automatically group into 3-tuples
+ *   so it creates pay fewer gates when possible (instead of writing repetitive `Gates.lookup(...)`
+ *   calls and manually handling batching of lookup entries).
+ * - **expressiveness**: all runtime tables will be condensed into one long table under the hood, 
+ *   so it is highly recommended to use distinct `id`s for unrelated tables to achieve better
+ *   separation of concerns and avoid accidental collisions, at no extra cost. 
+ *
+ * ## When *not* to use
+ * - **static and global tables**: Prefer built-ins for fixed-tables that already exist in the system.
+ *   (a.k.a. standard 4-bit XOR or 12-bit length range-check tables).
+ * - **hiding properties**: lookup tables **constrain membership**, but don’t provide secrecy 
+ *   of the values by themselves. If data privacy is needed, consider using the **witness** to hold 
+ *   the values and protect from exposure to the verifier.
+ * - **huge tables**: runtime lookups are efficient for a limited amount of entries, but their
+ *   size is limited by the underlying circuit size (i.e. 2^16). Applications needing more storage
+ *   should consider an optimized custom solution.
+ * - **mutable data**: runtime tables are write-once only, so once inserted entries in table are
+ *   remain fixed. To represent changing data, consider using DynamicArrays.
+ *
+ * ## Invariants & constraints
+ * - `id !== 0 && id !== 1`. (Reserved for XOR and range-check tables.)
+ * - `indices` are **unique**. Duplicates are rejected.
+ * - `lookup()` **batches** each 3 calls (for the same table) into **one** gate automatically.
+ * - `check()` call is required for soundness to flush 1–2 pending pairs before the end of the circuit.
+ *
+ * ## Complexity
+ * - Gate cost for membership checks is ~`ceil(#pairs / 3)` lookup gates per table id,
+ *   plus one lookup gate per `insert()` triplet.
+ *
+ * ## Example
+ * ```ts
+ * // Define a runtime table with id=5 and allowed indices {10n, 20n, 30n}
+ * const rt = new RuntimeTable(5, [10n, 20n, 30n]);
+ *
+ * // Populate some pairs (you can insert in chunks of up to 3)
+ * rt.insert([
+ *   [10n, Field.from(123)],
+ *   [20n, Field.from(456)],
+ *   [30n, Field.from(789)],
+ * ]);
+ *
+ * // Constrain that these pairs exist in the table
+ * rt.lookup(10n, Field.from(123));
+ * rt.lookup(20n, Field.from(456));
+ * // These two calls will be grouped; add a third, or call check() to flush
+ * rt.check(); // flush pending lookups (important!)
+ * ```
+ *
+ * ## Gotchas
+ * - **Don’t forget `check()`**: If you finish a proof block with 1–2 pending `lookup()` calls,
+ *   call `check()` to emit the final lookup gate. Otherwise those constraints won’t land.
+ * - **Index validation**: `insert()` and `lookup()` throw if the index isn’t whitelisted in `indices`.
+ * - **ID collisions**: Pick distinct `id`s for unrelated runtime tables.
+ * - **flag settings**: zkApps with runtime tables must be compiled with the `withRuntimeTables` flag.
+ *
+ * @remarks
+ * Construction registers the table configuration via `Gates.addRuntimeTableConfig(id, indices)`.
+ * Subsequent `insert()`/`lookup()` use that configuration to emit lookup gates. Please refrain from
+ * using that function directly, as it will be deprecated in the future.
+ *
+ * @see Gates.lookup
+ * @see Gates.addRuntimeTableConfig
+ * @see Gadgets.inTable
+ * @see DynamicArray for a mutable alternative to store runtime data.
+ * @public
  */
 class RuntimeTable {
     /**