docs(sql): standardize JSONB parameter descriptions

Update all JSONB parameter descriptions to use consistent format:
- Change from 'JSONB Raw encrypted value' or 'JSONB Encrypted data payload'
- Change to 'jsonb containing encrypted EQL payload'

Changes:
- Use lowercase 'jsonb' (correct PostgreSQL type convention)
- Use consistent phrase 'containing encrypted EQL payload'
- Updated 19 parameters across 8 files (Phase 2 + Phase 3)

Files modified:
- src/encrypted/functions.sql
- src/blake3/functions.sql
- src/hmac_256/functions.sql
- src/bloom_filter/functions.sql
- src/ore_block_u64_8_256/functions.sql
- src/ore_cllw_u64_8/functions.sql
- src/ore_cllw_var_8/functions.sql
- src/ste_vec/functions.sql

Author: tobyhede

src/blake3/functions.sql

@@ -5,7 +5,7 @@
 --! Extracts the Blake3 hash value from the 'b3' field of an encrypted
 --! data payload. Used internally for exact-match comparisons.
 --!
---! @param val JSONB Encrypted data payload containing index terms
+--! @param val jsonb containing encrypted EQL payload
 --! @return eql_v2.blake3 Blake3 hash value, or NULL if not present
 --! @throws Exception if 'b3' field is missing when blake3 index is expected
 --!
@@ -57,7 +57,7 @@ $$ LANGUAGE plpgsql;
 --! Tests whether the encrypted data payload includes a 'b3' field,
 --! indicating a Blake3 hash is available for exact-match queries.
 --!
---! @param val JSONB Encrypted data payload
+--! @param val jsonb containing encrypted EQL payload
 --! @return Boolean True if 'b3' field is present and non-null
 --!
 --! @see eql_v2.blake3

src/bloom_filter/functions.sql

@@ -6,7 +6,7 @@
 --! Extracts the Bloom filter array from the 'bf' field of an encrypted
 --! data payload. Used internally for pattern-match queries (LIKE operator).
 --!
---! @param val JSONB Encrypted data payload containing index terms
+--! @param val jsonb containing encrypted EQL payload
 --! @return eql_v2.bloom_filter Bloom filter as smallint array
 --! @throws Exception if 'bf' field is missing when bloom_filter index is expected
 --!
@@ -54,7 +54,7 @@ $$ LANGUAGE plpgsql;
 --! Tests whether the encrypted data payload includes a 'bf' field,
 --! indicating a Bloom filter is available for pattern-match queries.
 --!
---! @param val JSONB Encrypted data payload
+--! @param val jsonb containing encrypted EQL payload
 --! @return Boolean True if 'bf' field is present and non-null
 --!
 --! @see eql_v2.bloom_filter

src/encrypted/functions.sql

@@ -8,7 +8,7 @@
 --! 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
+--! @param val jsonb containing encrypted EQL payload
 --! @return Text Base64-encoded ciphertext string
 --! @throws Exception if 'c' field is not present in JSONB
 --!
@@ -155,7 +155,7 @@ $$ LANGUAGE plpgsql;
 --! 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
+--! @param val jsonb containing encrypted EQL payload
 --! @return JSONB Metadata object with 'i' (index terms) and 'v' (version) fields
 --!
 --! @example

src/hmac_256/functions.sql

@@ -6,7 +6,7 @@
 --! Extracts the HMAC-SHA256 hash value from the 'hm' field of an encrypted
 --! data payload. Used internally for exact-match comparisons.
 --!
---! @param val JSONB Encrypted data payload containing index terms
+--! @param val jsonb containing encrypted EQL payload
 --! @return eql_v2.hmac_256 HMAC-SHA256 hash value
 --! @throws Exception if 'hm' field is missing when hmac_256 index is expected
 --!
@@ -34,7 +34,7 @@ $$ LANGUAGE plpgsql;
 --! Tests whether the encrypted data payload includes an 'hm' field,
 --! indicating an HMAC-SHA256 hash is available for exact-match queries.
 --!
---! @param val JSONB Encrypted data payload
+--! @param val jsonb containing encrypted EQL payload
 --! @return Boolean True if 'hm' field is present and non-null
 --!
 --! @see eql_v2.hmac_256

src/ore_block_u64_8_256/functions.sql

@@ -38,7 +38,7 @@ $$ LANGUAGE plpgsql;
 --! Extracts the ORE block array from the 'ob' field of an encrypted
 --! data payload. Used internally for range query comparisons.
 --!
---! @param val JSONB Encrypted data payload containing index terms
+--! @param val jsonb containing encrypted EQL payload
 --! @return eql_v2.ore_block_u64_8_256 ORE block index term
 --! @throws Exception if 'ob' field is missing when ore index is expected
 --!
@@ -85,7 +85,7 @@ $$ LANGUAGE plpgsql;
 --! Tests whether the encrypted data payload includes an 'ob' field,
 --! indicating an ORE block is available for range queries.
 --!
---! @param val JSONB Encrypted data payload
+--! @param val jsonb containing encrypted EQL payload
 --! @return Boolean True if 'ob' field is present and non-null
 --!
 --! @see eql_v2.ore_block_u64_8_256

src/ore_cllw_u64_8/functions.sql

@@ -8,7 +8,7 @@
 --! 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
+--! @param val jsonb containing encrypted EQL payload
 --! @return eql_v2.ore_cllw_u64_8 CLLW ORE ciphertext
 --! @throws Exception if 'ocf' field is missing when ore index is expected
 --!
@@ -56,7 +56,7 @@ $$ LANGUAGE plpgsql;
 --! 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
+--! @param val jsonb containing encrypted EQL payload
 --! @return Boolean True if 'ocf' field is present and non-null
 --!
 --! @see eql_v2.ore_cllw_u64_8

src/ore_cllw_var_8/functions.sql

@@ -9,7 +9,7 @@
 --! 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
+--! @param val jsonb containing encrypted EQL payload
 --! @return eql_v2.ore_cllw_var_8 Variable-width CLLW ORE ciphertext
 --! @throws Exception if 'ocv' field is missing when ore index is expected
 --!
@@ -58,7 +58,7 @@ $$ LANGUAGE plpgsql;
 --! 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
+--! @param val jsonb containing encrypted EQL payload
 --! @return Boolean True if 'ocv' field is present and non-null
 --!
 --! @see eql_v2.ore_cllw_var_8

src/ste_vec/functions.sql

@@ -11,7 +11,7 @@
 --! containment queries (@>, <@). If no 'sv' field exists, wraps the entire payload
 --! as a single-element array.
 --!
---! @param val JSONB Encrypted data payload containing index terms
+--! @param val jsonb containing encrypted EQL payload
 --! @return eql_v2_encrypted[] Array of encrypted STE vector elements
 --!
 --! @see eql_v2.ste_vec(eql_v2_encrypted)
@@ -63,7 +63,7 @@ $$ LANGUAGE plpgsql;
 --! Tests whether the encrypted data payload contains an 'sv' field with exactly
 --! one element. Single-element STE vectors can be treated as regular encrypted values.
 --!
---! @param val JSONB Encrypted data payload
+--! @param val jsonb containing encrypted EQL payload
 --! @return Boolean True if 'sv' field exists with exactly one element
 --!
 --! @see eql_v2.to_ste_vec_value
@@ -104,7 +104,7 @@ $$ LANGUAGE plpgsql;
 --! as a regular encrypted value, preserving metadata. If the input is not a
 --! single-element STE vector, returns it unchanged.
 --!
---! @param val JSONB Encrypted data payload
+--! @param val jsonb containing encrypted EQL payload
 --! @return eql_v2_encrypted Regular encrypted value (unwrapped if single-element STE vector)
 --!
 --! @see eql_v2.is_ste_vec_value
@@ -156,7 +156,7 @@ $$ LANGUAGE plpgsql;
 --! Extracts the selector ('s') field from an encrypted data payload.
 --! Selectors are used to match STE vector elements during containment queries.
 --!
---! @param val JSONB Encrypted data payload
+--! @param val jsonb containing encrypted EQL payload
 --! @return Text The selector value
 --! @throws Exception if 's' field is missing
 --!
@@ -203,7 +203,7 @@ $$ LANGUAGE plpgsql;
 --! Tests whether the encrypted data payload has the 'a' (array) flag set to true,
 --! indicating it represents an array for STE vector operations.
 --!
---! @param val JSONB Encrypted data payload
+--! @param val jsonb containing encrypted EQL payload
 --! @return Boolean True if 'a' field is present and true
 --!
 --! @see eql_v2.ste_vec