docs(sql): document encrypted functions and comparison operators (Phase 2 checkpoint 2)

Add Doxygen documentation for encrypted column operations and operators:

Encrypted functions:
- ciphertext: Extract ciphertext from encrypted values (2 overloads)
- meta_data: Extract index terms/metadata (2 overloads)
- grouped_value: Aggregate for first non-null value in groups
- _first_grouped_value: Internal state function for aggregate
- add_encrypted_constraint: Add validation constraints
- remove_encrypted_constraint: Remove validation constraints

Comparison operators:
- lt: Less-than helper (internal)
- < operator: Three overloads for ORE-based comparisons

Pattern matching operators:
- like: LIKE helper using bloom filters (internal)
- ilike: Case-insensitive LIKE helper (internal)
- ~~ operator: Three overloads for pattern matching (LIKE)
- ~~* operator: Case-insensitive pattern matching (ILIKE)

Coverage: 16 functions/operators documented across 3 files
All include @brief, @param, @return tags
Customer-facing functions include @example tags
Internal functions marked with @internal

Part of: add-doxygen-sql-comments plan
Phase: 2 (Core modules - checkpoint 2/7)

Author: tobyhede

src/encrypted/functions.sql

@@ -3,8 +3,21 @@
 -- REQUIRE: src/ore_block_u64_8_256/types.sql
 -- REQUIRE: src/hmac_256/types.sql
 
-
-
+--! @brief Extract ciphertext from encrypted JSONB value
+--!
+--! Extracts the ciphertext (c field) from a raw JSONB encrypted value.
+--! The ciphertext is the base64-encoded encrypted data.
+--!
+--! @param val JSONB Raw encrypted value containing 'c' field
+--! @return Text Base64-encoded ciphertext string
+--! @throws Exception if 'c' field is not present in JSONB
+--!
+--! @example
+--! -- Extract ciphertext from JSONB literal
+--! SELECT eql_v2.ciphertext('{"c":"AQIDBA==","i":{"unique":"..."}}'::jsonb);
+--!
+--! @see eql_v2.ciphertext(eql_v2_encrypted)
+--! @see eql_v2.meta_data
 CREATE FUNCTION eql_v2.ciphertext(val jsonb)
   RETURNS text
   IMMUTABLE STRICT PARALLEL SAFE
@@ -17,7 +30,21 @@ AS $$
   END;
 $$ LANGUAGE plpgsql;
 
-
+--! @brief Extract ciphertext from encrypted column value
+--!
+--! Extracts the ciphertext from an encrypted column value. Convenience
+--! overload that unwraps eql_v2_encrypted type and delegates to JSONB version.
+--!
+--! @param val eql_v2_encrypted Encrypted column value
+--! @return Text Base64-encoded ciphertext string
+--! @throws Exception if encrypted value is malformed
+--!
+--! @example
+--! -- Extract ciphertext from encrypted column
+--! SELECT eql_v2.ciphertext(encrypted_email) FROM users;
+--!
+--! @see eql_v2.ciphertext(jsonb)
+--! @see eql_v2.meta_data
 CREATE FUNCTION eql_v2.ciphertext(val eql_v2_encrypted)
   RETURNS text
   IMMUTABLE STRICT PARALLEL SAFE
@@ -27,26 +54,70 @@ AS $$
   END;
 $$ LANGUAGE plpgsql;
 
-
+--! @brief State transition function for grouped_value aggregate
+--! @internal
+--!
+--! Returns the first non-null value encountered. Used as state function
+--! for the grouped_value aggregate to select first value in each group.
+--!
+--! @param $1 JSONB Accumulated state (first non-null value found)
+--! @param $2 JSONB New value from current row
+--! @return JSONB First non-null value (state or new value)
+--!
+--! @see eql_v2.grouped_value
 CREATE FUNCTION eql_v2._first_grouped_value(jsonb, jsonb)
 RETURNS jsonb AS $$
   SELECT COALESCE($1, $2);
 $$ LANGUAGE sql IMMUTABLE;
 
-
+--! @brief Return first non-null encrypted value in a group
+--!
+--! Aggregate function that returns the first non-null encrypted value
+--! encountered within a GROUP BY clause. Useful for deduplication or
+--! selecting representative values from grouped encrypted data.
+--!
+--! @param input JSONB Encrypted values to aggregate
+--! @return JSONB First non-null encrypted value in group
+--!
+--! @example
+--! -- Get first email per user group
+--! SELECT user_id, eql_v2.grouped_value(encrypted_email)
+--! FROM user_emails
+--! GROUP BY user_id;
+--!
+--! -- Deduplicate encrypted values
+--! SELECT DISTINCT ON (user_id)
+--!   user_id,
+--!   eql_v2.grouped_value(encrypted_ssn) as primary_ssn
+--! FROM user_records
+--! GROUP BY user_id;
+--!
+--! @see eql_v2._first_grouped_value
 CREATE AGGREGATE eql_v2.grouped_value(jsonb) (
   SFUNC = eql_v2._first_grouped_value,
   STYPE = jsonb
 );
 
-
---
--- Adds eql_v2.check_encrypted constraint to the column_name in table_name
---
--- Executes the ALTER TABLE statement
---   `ALTER TABLE {table_name} ADD CONSTRAINT eql_v2_encrypted_check_{column_name} CHECK (eql_v2.check_encrypted({column_name}))`
---
---
+--! @brief Add validation constraint to encrypted column
+--!
+--! Adds a CHECK constraint to ensure column values conform to encrypted data
+--! structure. Constraint uses eql_v2.check_encrypted to validate format.
+--! Called automatically by eql_v2.add_column.
+--!
+--! @param table_name TEXT Name of table containing the column
+--! @param column_name TEXT Name of column to constrain
+--! @return Void
+--!
+--! @example
+--! -- Manually add constraint (normally done by add_column)
+--! SELECT eql_v2.add_encrypted_constraint('users', 'encrypted_email');
+--!
+--! -- Resulting constraint:
+--! -- ALTER TABLE users ADD CONSTRAINT eql_v2_encrypted_check_encrypted_email
+--! --   CHECK (eql_v2.check_encrypted(encrypted_email));
+--!
+--! @see eql_v2.add_column
+--! @see eql_v2.remove_encrypted_constraint
 CREATE FUNCTION eql_v2.add_encrypted_constraint(table_name TEXT, column_name TEXT)
   RETURNS void
 AS $$
@@ -55,13 +126,22 @@ AS $$
 	END;
 $$ LANGUAGE plpgsql;
 
-
---
--- Removes the eql_v2.check_encrypted constraint from the column_name in table_name
---
--- Executes the ALTER TABLE statement
---   `ALTER TABLE {table_name} DROP CONSTRAINT eql_v2_encrypted_check_{column_name}`
---
+--! @brief Remove validation constraint from encrypted column
+--!
+--! Removes the CHECK constraint that validates encrypted data structure.
+--! Called automatically by eql_v2.remove_column. Uses IF EXISTS to avoid
+--! errors if constraint doesn't exist.
+--!
+--! @param table_name TEXT Name of table containing the column
+--! @param column_name TEXT Name of column to unconstrain
+--! @return Void
+--!
+--! @example
+--! -- Manually remove constraint (normally done by remove_column)
+--! SELECT eql_v2.remove_encrypted_constraint('users', 'encrypted_email');
+--!
+--! @see eql_v2.remove_column
+--! @see eql_v2.add_encrypted_constraint
 CREATE FUNCTION eql_v2.remove_encrypted_constraint(table_name TEXT, column_name TEXT)
   RETURNS void
 AS $$
@@ -70,7 +150,21 @@ AS $$
 	END;
 $$ LANGUAGE plpgsql;
 
-
+--! @brief Extract metadata from encrypted JSONB value
+--!
+--! Extracts index terms (i) and version (v) from a raw JSONB encrypted value.
+--! Returns metadata object containing searchable index terms without ciphertext.
+--!
+--! @param val JSONB Raw encrypted value
+--! @return JSONB Metadata object with 'i' (index terms) and 'v' (version) fields
+--!
+--! @example
+--! -- Extract metadata to inspect index terms
+--! SELECT eql_v2.meta_data('{"c":"...","i":{"unique":"abc123"},"v":1}'::jsonb);
+--! -- Returns: {"i":{"unique":"abc123"},"v":1}
+--!
+--! @see eql_v2.meta_data(eql_v2_encrypted)
+--! @see eql_v2.ciphertext
 CREATE FUNCTION eql_v2.meta_data(val jsonb)
   RETURNS jsonb
   IMMUTABLE STRICT PARALLEL SAFE
@@ -83,7 +177,22 @@ AS $$
   END;
 $$ LANGUAGE plpgsql;
 
-
+--! @brief Extract metadata from encrypted column value
+--!
+--! Extracts index terms and version from an encrypted column value.
+--! Convenience overload that unwraps eql_v2_encrypted type and
+--! delegates to JSONB version.
+--!
+--! @param val eql_v2_encrypted Encrypted column value
+--! @return JSONB Metadata object with 'i' (index terms) and 'v' (version) fields
+--!
+--! @example
+--! -- Inspect index terms for encrypted column
+--! SELECT user_id, eql_v2.meta_data(encrypted_email) as email_metadata
+--! FROM users;
+--!
+--! @see eql_v2.meta_data(jsonb)
+--! @see eql_v2.ciphertext
 CREATE FUNCTION eql_v2.meta_data(val eql_v2_encrypted)
   RETURNS jsonb
   IMMUTABLE STRICT PARALLEL SAFE

src/operators/<.sql

@@ -2,12 +2,18 @@
 -- REQUIRE: src/encrypted/types.sql
 -- REQUIRE: src/operators/compare.sql
 
-
--- Operators for < less than comparisons of eql_v2_encrypted types
---
--- Uses `eql_v2.compare` for the actual comparison logic.
---
---
+--! @brief Less-than comparison helper for encrypted values
+--! @internal
+--!
+--! Internal helper that delegates to eql_v2.compare for less-than testing.
+--! Returns true if first value is less than second using ORE comparison.
+--!
+--! @param a eql_v2_encrypted First encrypted value
+--! @param b eql_v2_encrypted Second encrypted value
+--! @return Boolean True if a < b (compare result = -1)
+--!
+--! @see eql_v2.compare
+--! @see eql_v2."<"
 CREATE FUNCTION eql_v2.lt(a eql_v2_encrypted, b eql_v2_encrypted)
 RETURNS boolean
 AS $$
@@ -16,8 +22,26 @@ AS $$
   END;
 $$ LANGUAGE plpgsql;
 
-
-
+--! @brief Less-than operator for encrypted values
+--!
+--! Implements the < operator for comparing two encrypted values using Order-Revealing
+--! Encryption (ORE) index terms. Enables range queries and sorting without decryption.
+--! Requires 'ore' index configuration on the column.
+--!
+--! @param a eql_v2_encrypted Left operand
+--! @param b eql_v2_encrypted Right operand
+--! @return Boolean True if a is less than b
+--!
+--! @example
+--! -- Range query on encrypted timestamps
+--! SELECT * FROM events
+--! WHERE encrypted_timestamp < '2024-01-01'::timestamp::text::eql_v2_encrypted;
+--!
+--! -- Compare encrypted numeric columns
+--! SELECT * FROM products WHERE encrypted_price < encrypted_discount_price;
+--!
+--! @see eql_v2.compare
+--! @see eql_v2.add_search_config
 CREATE FUNCTION eql_v2."<"(a eql_v2_encrypted, b eql_v2_encrypted)
 RETURNS boolean
 AS $$
@@ -36,8 +60,19 @@ CREATE OPERATOR <(
   JOIN = scalarltjoinsel
 );
 
-
-
+--! @brief Less-than operator for encrypted value and JSONB
+--!
+--! Overload of < operator accepting JSONB on the right side. Automatically
+--! casts JSONB to eql_v2_encrypted for ORE comparison.
+--!
+--! @param a eql_v2_encrypted Left operand (encrypted value)
+--! @param b JSONB Right operand (will be cast to eql_v2_encrypted)
+--! @return Boolean True if a < b
+--!
+--! @example
+--! SELECT * FROM events WHERE encrypted_age < '18'::int::text::jsonb;
+--!
+--! @see eql_v2."<"(eql_v2_encrypted, eql_v2_encrypted)
 CREATE FUNCTION eql_v2."<"(a eql_v2_encrypted, b jsonb)
 RETURNS boolean
 AS $$
@@ -56,8 +91,19 @@ CREATE OPERATOR <(
   JOIN = scalarltjoinsel
 );
 
-
-
+--! @brief Less-than operator for JSONB and encrypted value
+--!
+--! Overload of < operator accepting JSONB on the left side. Automatically
+--! casts JSONB to eql_v2_encrypted for ORE comparison.
+--!
+--! @param a JSONB Left operand (will be cast to eql_v2_encrypted)
+--! @param b eql_v2_encrypted Right operand (encrypted value)
+--! @return Boolean True if a < b
+--!
+--! @example
+--! SELECT * FROM events WHERE '2023-01-01'::date::text::jsonb < encrypted_date;
+--!
+--! @see eql_v2."<"(eql_v2_encrypted, eql_v2_encrypted)
 CREATE FUNCTION eql_v2."<"(a jsonb, b eql_v2_encrypted)
 RETURNS boolean
 AS $$