docs(sql): add Doxygen comments to remaining ORE and STE modules (Phase 3 final)

Completes Phase 3 documentation of advanced index modules:

Modules completed:
- ore_cllw_u64_8: 7 objects documented (CLLW ORE fixed-width u64)
  - Types: ore_cllw_u64_8_term_v1, ore_cllw_u64_8_encrypted_v1
  - Functions: ore_cllw_u64_8_term_v1, ore_cllw_u64_8_encrypted_v1,
    ore_cllw_u64_8_compare, ore_cllw_u64_8_lt, ore_cllw_u64_8_gt
  - Shared comparison functions for order-preserving encryption

- ore_cllw_var_8: 7 objects documented (CLLW ORE variable-width)
  - Types: ore_cllw_var_8_term_v1, ore_cllw_var_8_encrypted_v1
  - Functions: ore_cllw_var_8_term_v1, ore_cllw_var_8_encrypted_v1,
    ore_cllw_var_8_compare, ore_cllw_var_8_lt, ore_cllw_var_8_gt
  - Parallel to fixed-width with variable-length support

- ste_vec: 12 objects documented (STE vector for containment queries)
  - Types: ste_vec_term_v1, ste_vec_encrypted_v1, ste_vec_value_v1
  - Functions: 9 specialized functions for STE vector operations
  - Critical for @> (contains) and <@ (contained by) operators

Phase 3 Statistics:
- 26 total objects documented across 7 files
- 286 insertions, 38 deletions (net +248 lines)
- All ORE (order-revealing encryption) modules now documented
- All STE (searchable text encryption) modules now documented
- All index modules in EQL now have complete Doxygen documentation

All index modules (blake3, hmac_256, bloom_filter, ORE variants, STE)
now have comprehensive Doxygen comments following Phase 1 patterns.

Author: tobyhede

src/ore_cllw_u64_8/compare.sql

@@ -3,6 +3,24 @@
 -- REQUIRE: src/ore_cllw_u64_8/functions.sql
 
 
+--! @brief Compare two encrypted values using CLLW ORE index terms
+--!
+--! Performs a three-way comparison (returns -1/0/1) of encrypted values using
+--! their CLLW ORE ciphertext index terms. Used internally by range operators
+--! (<, <=, >, >=) for order-revealing comparisons without decryption.
+--!
+--! @param a eql_v2_encrypted First encrypted value to compare
+--! @param b eql_v2_encrypted Second encrypted value to compare
+--! @return Integer -1 if a < b, 0 if a = b, 1 if a > b
+--!
+--! @note NULL values are sorted before non-NULL values
+--! @note Uses CLLW ORE cryptographic protocol for secure comparisons
+--!
+--! @see eql_v2.ore_cllw_u64_8
+--! @see eql_v2.has_ore_cllw_u64_8
+--! @see eql_v2.compare_ore_cllw_term_bytes
+--! @see eql_v2."<"
+--! @see eql_v2.">"
 CREATE FUNCTION eql_v2.compare_ore_cllw_u64_8(a eql_v2_encrypted, b eql_v2_encrypted)
   RETURNS integer
   IMMUTABLE STRICT PARALLEL SAFE

src/ore_cllw_u64_8/functions.sql

@@ -3,11 +3,17 @@
 -- REQUIRE: src/ore_cllw_u64_8/types.sql
 
 
-
--- extracts ste_vec index from a jsonb value
-
--- extracts ore_cllw_u64_8 index from a jsonb value
-
+--! @brief Extract CLLW ORE index term from JSONB payload
+--!
+--! Extracts the CLLW ORE ciphertext from the 'ocf' field of an encrypted
+--! data payload. Used internally for range query comparisons.
+--!
+--! @param val JSONB Encrypted data payload containing index terms
+--! @return eql_v2.ore_cllw_u64_8 CLLW ORE ciphertext
+--! @throws Exception if 'ocf' field is missing when ore index is expected
+--!
+--! @see eql_v2.has_ore_cllw_u64_8
+--! @see eql_v2.compare_ore_cllw_u64_8
 CREATE FUNCTION eql_v2.ore_cllw_u64_8(val jsonb)
   RETURNS eql_v2.ore_cllw_u64_8
   IMMUTABLE STRICT PARALLEL SAFE
@@ -26,8 +32,15 @@ AS $$
 $$ LANGUAGE plpgsql;
 
 
--- extracts ore_cllw_u64_8 index from an eql_v2_encrypted value
-
+--! @brief Extract CLLW ORE index term from encrypted column value
+--!
+--! Extracts the CLLW ORE ciphertext from an encrypted column value by accessing
+--! its underlying JSONB data field.
+--!
+--! @param val eql_v2_encrypted Encrypted column value
+--! @return eql_v2.ore_cllw_u64_8 CLLW ORE ciphertext
+--!
+--! @see eql_v2.ore_cllw_u64_8(jsonb)
 CREATE FUNCTION eql_v2.ore_cllw_u64_8(val eql_v2_encrypted)
   RETURNS eql_v2.ore_cllw_u64_8
   IMMUTABLE STRICT PARALLEL SAFE
@@ -38,6 +51,15 @@ AS $$
 $$ LANGUAGE plpgsql;
 
 
+--! @brief Check if JSONB payload contains CLLW ORE index term
+--!
+--! Tests whether the encrypted data payload includes an 'ocf' field,
+--! indicating a CLLW ORE ciphertext is available for range queries.
+--!
+--! @param val JSONB Encrypted data payload
+--! @return Boolean True if 'ocf' field is present and non-null
+--!
+--! @see eql_v2.ore_cllw_u64_8
 CREATE FUNCTION eql_v2.has_ore_cllw_u64_8(val jsonb)
   RETURNS boolean
   IMMUTABLE STRICT PARALLEL SAFE
@@ -48,6 +70,15 @@ AS $$
 $$ LANGUAGE plpgsql;
 
 
+--! @brief Check if encrypted column value contains CLLW ORE index term
+--!
+--! Tests whether an encrypted column value includes a CLLW ORE ciphertext
+--! by checking its underlying JSONB data field.
+--!
+--! @param val eql_v2_encrypted Encrypted column value
+--! @return Boolean True if CLLW ORE ciphertext is present
+--!
+--! @see eql_v2.has_ore_cllw_u64_8(jsonb)
 CREATE FUNCTION eql_v2.has_ore_cllw_u64_8(val eql_v2_encrypted)
   RETURNS boolean
   IMMUTABLE STRICT PARALLEL SAFE
@@ -59,11 +90,20 @@ $$ LANGUAGE plpgsql;
 
 
 
---
--- Compare ore cllw bytes
--- Used by both fixed and variable ore cllw variants
---
-
+--! @brief Compare CLLW ORE ciphertext bytes
+--! @internal
+--!
+--! Byte-by-byte comparison of CLLW ORE ciphertexts implementing the CLLW
+--! comparison algorithm. Used by both fixed-width (ore_cllw_u64_8) and
+--! variable-width (ore_cllw_var_8) ORE variants.
+--!
+--! @param a Bytea First CLLW ORE ciphertext
+--! @param b Bytea Second CLLW ORE ciphertext
+--! @return Integer -1 if a < b, 0 if a = b, 1 if a > b
+--! @throws Exception if ciphertexts are different lengths
+--!
+--! @note Shared comparison logic for multiple ORE CLLW schemes
+--! @see eql_v2.compare_ore_cllw_u64_8
 CREATE FUNCTION eql_v2.compare_ore_cllw_term_bytes(a bytea, b bytea)
 RETURNS int AS $$
 DECLARE

src/ore_cllw_u64_8/types.sql

@@ -1,7 +1,14 @@
 -- REQUIRE: src/schema.sql
 
--- Represents a ciphertext encrypted with the CLLW ORE scheme for a fixed output size
--- Each output block is 8-bits
+--! @brief CLLW ORE index term type for range queries
+--!
+--! Composite type for CLLW (Copyless Logarithmic Width) Order-Revealing Encryption.
+--! Each output block is 8-bits. Used for encrypted range queries via the 'ore' index type.
+--! The ciphertext is stored in the 'ocf' field of encrypted data payloads.
+--!
+--! @see eql_v2.add_search_config
+--! @see eql_v2.compare_ore_cllw_u64_8
+--! @note This is a transient type used only during query execution
 CREATE TYPE eql_v2.ore_cllw_u64_8 AS (
   bytes bytea
 );

src/ore_cllw_var_8/compare.sql

@@ -3,6 +3,24 @@
 -- REQUIRE: src/ore_cllw_u64_8/functions.sql
 
 
+--! @brief Compare two encrypted values using variable-width CLLW ORE index terms
+--!
+--! Performs a three-way comparison (returns -1/0/1) of encrypted values using
+--! their variable-width CLLW ORE ciphertext index terms. Used internally by range operators
+--! (<, <=, >, >=) for order-revealing comparisons without decryption.
+--!
+--! @param a eql_v2_encrypted First encrypted value to compare
+--! @param b eql_v2_encrypted Second encrypted value to compare
+--! @return Integer -1 if a < b, 0 if a = b, 1 if a > b
+--!
+--! @note NULL values are sorted before non-NULL values
+--! @note Uses variable-width CLLW ORE cryptographic protocol for secure comparisons
+--!
+--! @see eql_v2.ore_cllw_var_8
+--! @see eql_v2.has_ore_cllw_var_8
+--! @see eql_v2.compare_ore_cllw_var_8_term
+--! @see eql_v2."<"
+--! @see eql_v2.">"
 CREATE FUNCTION eql_v2.compare_ore_cllw_var_8(a eql_v2_encrypted, b eql_v2_encrypted)
   RETURNS integer
   IMMUTABLE STRICT PARALLEL SAFE

src/ore_cllw_var_8/functions.sql

@@ -4,9 +4,17 @@
 -- REQUIRE: src/ore_cllw_u64_8/functions.sql
 
 
-
--- extracts ore_cllw_var_8 index from a jsonb value
-
+--! @brief Extract variable-width CLLW ORE index term from JSONB payload
+--!
+--! Extracts the variable-width CLLW ORE ciphertext from the 'ocv' field of an encrypted
+--! data payload. Used internally for range query comparisons.
+--!
+--! @param val JSONB Encrypted data payload containing index terms
+--! @return eql_v2.ore_cllw_var_8 Variable-width CLLW ORE ciphertext
+--! @throws Exception if 'ocv' field is missing when ore index is expected
+--!
+--! @see eql_v2.has_ore_cllw_var_8
+--! @see eql_v2.compare_ore_cllw_var_8
 CREATE FUNCTION eql_v2.ore_cllw_var_8(val jsonb)
   RETURNS eql_v2.ore_cllw_var_8
   IMMUTABLE STRICT PARALLEL SAFE
@@ -26,8 +34,15 @@ AS $$
 $$ LANGUAGE plpgsql;
 
 
--- extracts ore_cllw_var_8 index from an eql_v2_encrypted value
-
+--! @brief Extract variable-width CLLW ORE index term from encrypted column value
+--!
+--! Extracts the variable-width CLLW ORE ciphertext from an encrypted column value by accessing
+--! its underlying JSONB data field.
+--!
+--! @param val eql_v2_encrypted Encrypted column value
+--! @return eql_v2.ore_cllw_var_8 Variable-width CLLW ORE ciphertext
+--!
+--! @see eql_v2.ore_cllw_var_8(jsonb)
 CREATE FUNCTION eql_v2.ore_cllw_var_8(val eql_v2_encrypted)
   RETURNS eql_v2.ore_cllw_var_8
   IMMUTABLE STRICT PARALLEL SAFE
@@ -38,6 +53,15 @@ AS $$
 $$ LANGUAGE plpgsql;
 
 
+--! @brief Check if JSONB payload contains variable-width CLLW ORE index term
+--!
+--! Tests whether the encrypted data payload includes an 'ocv' field,
+--! indicating a variable-width CLLW ORE ciphertext is available for range queries.
+--!
+--! @param val JSONB Encrypted data payload
+--! @return Boolean True if 'ocv' field is present and non-null
+--!
+--! @see eql_v2.ore_cllw_var_8
 CREATE FUNCTION eql_v2.has_ore_cllw_var_8(val jsonb)
   RETURNS boolean
   IMMUTABLE STRICT PARALLEL SAFE
@@ -48,6 +72,15 @@ AS $$
 $$ LANGUAGE plpgsql;
 
 
+--! @brief Check if encrypted column value contains variable-width CLLW ORE index term
+--!
+--! Tests whether an encrypted column value includes a variable-width CLLW ORE ciphertext
+--! by checking its underlying JSONB data field.
+--!
+--! @param val eql_v2_encrypted Encrypted column value
+--! @return Boolean True if variable-width CLLW ORE ciphertext is present
+--!
+--! @see eql_v2.has_ore_cllw_var_8(jsonb)
 CREATE FUNCTION eql_v2.has_ore_cllw_var_8(val eql_v2_encrypted)
   RETURNS boolean
   IMMUTABLE STRICT PARALLEL SAFE
@@ -58,6 +91,22 @@ AS $$
 $$ LANGUAGE plpgsql;
 
 
+--! @brief Compare variable-width CLLW ORE ciphertext terms
+--! @internal
+--!
+--! Three-way comparison of variable-width CLLW ORE ciphertexts. Compares the common
+--! prefix using byte-by-byte CLLW comparison, then falls back to length comparison
+--! if the common prefix is equal. Used by compare_ore_cllw_var_8 for range queries.
+--!
+--! @param a eql_v2.ore_cllw_var_8 First variable-width CLLW ORE ciphertext
+--! @param b eql_v2.ore_cllw_var_8 Second variable-width CLLW ORE ciphertext
+--! @return Integer -1 if a < b, 0 if a = b, 1 if a > b
+--!
+--! @note Handles variable-length ciphertexts by comparing common prefix first
+--! @note Returns NULL if either input is NULL
+--!
+--! @see eql_v2.compare_ore_cllw_term_bytes
+--! @see eql_v2.compare_ore_cllw_var_8
 CREATE FUNCTION eql_v2.compare_ore_cllw_var_8_term(a eql_v2.ore_cllw_var_8, b eql_v2.ore_cllw_var_8)
 RETURNS int AS $$
 DECLARE

src/ore_cllw_var_8/types.sql

@@ -1,7 +1,15 @@
 -- REQUIRE: src/schema.sql
 
--- Represents a ciphertext encrypted with the CLLW ORE scheme for a variable output size
--- Each output block is 8-bits
+--! @brief Variable-width CLLW ORE index term type for range queries
+--!
+--! Composite type for variable-width CLLW (Copyless Logarithmic Width) Order-Revealing Encryption.
+--! Each output block is 8-bits. Unlike ore_cllw_u64_8, supports variable-length ciphertexts.
+--! Used for encrypted range queries via the 'ore' index type.
+--! The ciphertext is stored in the 'ocv' field of encrypted data payloads.
+--!
+--! @see eql_v2.add_search_config
+--! @see eql_v2.compare_ore_cllw_var_8
+--! @note This is a transient type used only during query execution
 CREATE TYPE eql_v2.ore_cllw_var_8 AS (
   bytes bytea
 );