@jmruthers/pace-core 0.5.79 → 0.5.81

package/docs/architecture/rpc-function-standards.md

@@ -0,0 +1,757 @@
+# RPC Function Standards
+
+## Overview
+
+This document defines the standards for creating, naming, and structuring RPC (Remote Procedure Call) functions in the PACE Core database. These standards ensure consistency, security, and maintainability across all database functions.
+
+## Naming Convention
+
+### Pattern
+
+RPC function names must follow: **`<family>_<domain>_<verb>`**
+
+### Family Prefixes
+
+The family prefix categorizes the function's purpose:
+
+- **`data_`** - Data access functions that retrieve or manipulate application data
+  - Examples: `data_user_events_get`, `data_cake_meals_get`, `data_user_organisations_get`
+  
+- **`rbac_`** - RBAC (Role-Based Access Control) functions for permission checking, role management, and security
+  - Examples: `rbac_check_permission_simplified`, `rbac_permissions_get`, `rbac_role_grant`
+  
+- **`util_`** - Utility functions for common operations, helpers, and shared logic
+  - Examples: `util_app_resolve`, `util_format_date`
+  
+- **`app_`** - Application-specific functions tied to a particular app module
+  - Examples: `app_cake_supply_calculate`, `app_cake_distribution_get`
+
+### Domain
+
+The domain identifies the entity or context the function operates on:
+
+- **User-related**: `user_events`, `user_organisations`, `user_roles`
+- **App-specific**: `cake_meals`, `cake_distribution`, `cake_supply`
+- **System**: `permissions`, `roles`, `session`, `audit`
+
+### Verb
+
+The verb describes the action being performed:
+
+- **`get`** - Retrieve a single record or collection
+- **`list`** - Retrieve a collection (alternative to `get`)
+- **`create`** - Create a new record
+- **`update`** - Update an existing record
+- **`delete`** - Delete a record
+- **`check`** - Validate or check a condition (returns boolean)
+- **`validate`** - Validate data or access (returns boolean or result)
+- **`grant`** - Grant a permission or role
+- **`revoke`** - Revoke a permission or role
+- **`calculate`** - Perform calculations
+- **`resolve`** - Resolve or transform data
+
+### Examples
+
+```sql
+-- ✅ Good examples
+data_user_events_get              -- Get user events
+data_cake_meals_get               -- Get cake meals
+rbac_check_permission_simplified  -- Check permission
+rbac_permissions_get              -- Get permissions
+rbac_role_grant                   -- Grant role
+util_app_resolve                  -- Resolve app
+data_cake_distribution_list       -- List distribution data
+
+-- ❌ Bad examples
+getUserEvents                     -- Wrong: camelCase, missing prefix
+cake_meals_get                    -- Wrong: missing family prefix
+rbac_checkPermission              -- Wrong: camelCase
+get_cake_meals                    -- Wrong: wrong prefix order
+```
+
+## Function Structure
+
+### Standard Template
+
+```sql
+CREATE OR REPLACE FUNCTION public.<family>_<domain>_<verb>(
+    p_param1 TYPE,
+    p_param2 TYPE DEFAULT NULL,
+    p_user_id UUID DEFAULT auth.uid(),
+    p_organisation_id UUID DEFAULT NULL
+)
+RETURNS TABLE(
+    column1 TYPE,
+    column2 TYPE
+)
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path TO 'public'
+AS $$
+DECLARE
+    v_local_variable TYPE;
+    v_is_super_admin BOOLEAN := false;
+BEGIN
+    -- 1. Input validation
+    IF p_param1 IS NULL THEN
+        RETURN;
+    END IF;
+    
+    -- 2. Super admin check (if applicable)
+    SELECT EXISTS(
+        SELECT 1 FROM rbac_global_roles 
+        WHERE user_id = COALESCE(p_user_id, auth.uid())
+        AND role = 'super_admin'
+        AND valid_from <= NOW()
+        AND (valid_to IS NULL OR valid_to >= NOW())
+    ) INTO v_is_super_admin;
+    
+    IF v_is_super_admin THEN
+        -- Super admin logic
+        RETURN QUERY SELECT ...;
+        RETURN;
+    END IF;
+    
+    -- 3. Organisation context validation (if required)
+    IF p_organisation_id IS NULL THEN
+        RAISE EXCEPTION 'Organisation context is required';
+        RETURN;
+    END IF;
+    
+    -- 4. Dynamic RBAC permission check (replaces manual organisation/event checks)
+    -- Use rbac_check_permission_simplified() for consistency with RLS policies
+    IF NOT rbac_check_permission_simplified(
+        COALESCE(p_user_id, auth.uid()),
+        'read:resource',  -- Format: operation:resource (e.g., 'read:meals', 'create:events')
+        p_organisation_id,
+        NULL,  -- p_event_id if event-scoped, NULL if org-scoped
+        (SELECT id FROM rbac_apps WHERE name = 'CAKE' LIMIT 1),  -- p_app_id
+        'resource'  -- p_page_id (page name from rbac_app_pages)
+    ) THEN
+        RETURN; -- No permission
+    END IF;
+    
+    -- 5. Main logic (RLS is bypassed but we've checked permissions above)
+    RETURN QUERY SELECT ...;
+    
+EXCEPTION WHEN OTHERS THEN
+    RAISE WARNING 'Function failed: %', SQLERRM;
+    RETURN;
+END;
+$$;
+```
+
+### Key Requirements
+
+1. **Always use `SECURITY DEFINER`** - Functions must run with elevated privileges to bypass RLS. **However**, you must still implement security checks using `rbac_check_permission_simplified()` internally (see Dynamic RLS Integration section above).
+
+2. **Always set `SET search_path TO 'public'`** - Prevents SQL injection attacks
+
+3. **Parameter Naming**:
+   - Prefix all parameters with `p_` (e.g., `p_event_id`, `p_user_id`)
+   - Use `p_user_id UUID DEFAULT auth.uid()` for user context
+   - Use `p_organisation_id UUID DEFAULT NULL` for organisation context
+   - Use descriptive names
+
+4. **Variable Naming**:
+   - Prefix local variables with `v_` (e.g., `v_is_super_admin`, `v_event_exists`)
+   - Use descriptive names
+
+5. **Return Types**:
+   - Use `RETURNS TABLE(...)` for functions that return multiple rows
+   - Use `RETURNS BOOLEAN` for check/validation functions
+   - Use `RETURNS JSON` or `RETURNS JSONB` for complex data
+   - Use `RETURNS UUID` or `RETURNS TEXT` for single values
+
+6. **Error Handling**:
+   - Always include `EXCEPTION WHEN OTHERS` block
+   - Log errors with `RAISE WARNING` or `RAISE NOTICE`
+   - Return empty results on error (fail-secure)
+
+7. **Security Checks**:
+   - Always check super_admin status first (if applicable)
+   - Always use `rbac_check_permission_simplified()` for permission checks (ensures consistency with dynamic RLS)
+   - Always validate organisation membership (for non-super-admin)
+   - Always validate event access (for event-scoped functions)
+   - Never trust client-provided parameters without validation
+   - **Important**: Even though RLS is bypassed with `SECURITY DEFINER`, you must implement the same security checks that RLS policies would enforce
+
+8. **Comments**:
+   - Add header comment explaining function purpose
+   - Document parameters
+   - Document return value
+   - Document security implications
+
+## Dynamic RLS Integration
+
+### Overview
+
+PACE Core uses **Dynamic RLS (Row Level Security)** with RBAC-aware policies. This means RLS policies use `rbac_check_permission_simplified()` to dynamically check permissions based on the current RBAC configuration, rather than hardcoded role checks.
+
+### RPC Functions vs RLS Policies
+
+There are **two layers** of security in PACE Core:
+
+1. **RLS Policies** - For direct table access (client-side queries)
+   - Use `rbac_check_permission_simplified()` in policy USING clauses
+   - Enforce security at the database level for all direct queries
+   - Example: `CREATE POLICY ... USING (rbac_check_permission_simplified(...))`
+
+2. **RPC Functions** - For complex operations (server-side logic)
+   - Run with `SECURITY DEFINER` which **bypasses RLS**
+   - Must implement their own security checks
+   - Should use `rbac_check_permission_simplified()` internally for consistency
+
+### Why RPC Functions Bypass RLS
+
+RPC functions use `SECURITY DEFINER` which bypasses RLS. This is **intentional and required** for several reasons:
+
+#### Technical Reasons
+
+1. **Performance** - RPC functions need to query multiple tables efficiently without RLS overhead on every operation
+2. **Complex Logic** - Functions perform calculations, aggregations, and joins that RLS policies can't handle elegantly
+3. **Query Optimization** - Functions can optimize queries for specific use cases without RLS interference
+
+#### Security Architecture Reasons
+
+4. **Centralized Security** - Functions implement security checks in one place rather than relying on multiple RLS policies
+5. **Explicit Control** - Security logic is visible in the function code, not hidden in policy definitions
+6. **Defense in Depth** - Even if RLS has bugs or is misconfigured, RPC function security checks still apply
+7. **RLS as Safety Net** - RLS policies provide defense-in-depth for any direct queries, but RPC functions don't rely on them
+
+#### Why This Architecture is Better
+
+**Problem with RLS-Only Approach:**
+- RLS policies can have bugs (we saw this with `cake_diner` policy)
+- RLS policies can be misconfigured or forgotten
+- Multiple policies on multiple tables = multiple places for bugs
+- Direct queries bypass security if RLS is broken
+
+**Solution with RPC Functions:**
+- All security logic in one place (the function)
+- Explicit permission checks that are easy to audit
+- RLS still exists as defense-in-depth (catches bugs)
+- Can't bypass security even if RLS fails
+
+**Important**: You must still implement security checks in the RPC function itself. Bypassing RLS doesn't mean bypassing security - it means implementing security explicitly rather than relying on RLS policies.
+
+### Using `rbac_check_permission_simplified()` in RPC Functions
+
+RPC functions should use `rbac_check_permission_simplified()` for permission checks to ensure consistency with RLS policies:
+
+```sql
+CREATE OR REPLACE FUNCTION data_cake_meals_get(
+    p_event_id TEXT,
+    p_user_id UUID DEFAULT auth.uid(),
+    p_organisation_id UUID DEFAULT NULL
+)
+RETURNS TABLE(...)
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path TO 'public'
+AS $$
+BEGIN
+    -- Super admin check (always first)
+    IF EXISTS(SELECT 1 FROM rbac_global_roles WHERE user_id = p_user_id AND role = 'super_admin') THEN
+        RETURN QUERY SELECT * FROM cake_meal WHERE meal_event_id = p_event_id;
+        RETURN;
+    END IF;
+    
+    -- Use rbac_check_permission_simplified for dynamic RBAC checking
+    IF NOT rbac_check_permission_simplified(
+        p_user_id,
+        'read:meals',
+        p_organisation_id,
+        p_event_id,
+        (SELECT id FROM rbac_apps WHERE name = 'CAKE' LIMIT 1),
+        'meals'
+    ) THEN
+        RETURN; -- No permission
+    END IF;
+    
+    -- Return data (bypasses RLS due to SECURITY DEFINER)
+    RETURN QUERY
+    SELECT * FROM cake_meal
+    WHERE meal_event_id = p_event_id
+    AND organisation_id = p_organisation_id;
+END;
+$$;
+```
+
+### Key Points
+
+1. **Always check permissions** - Even though RLS is bypassed, you must check permissions
+2. **Use the same function** - Use `rbac_check_permission_simplified()` just like RLS policies do
+3. **Consistent behavior** - This ensures RPC functions and direct queries have the same security behavior
+4. **Performance** - `rbac_check_permission_simplified()` is optimized and cached
+
+### RPC-First Architecture (Recommended)
+
+**Security Best Practice**: Use RPC functions as the **primary access method** for all database operations. Treat RLS as defense-in-depth, not a primary security control.
+
+#### Why RPC Functions Should Be Preferred
+
+1. **Centralized Security Logic**
+   - All security checks in one place (the RPC function)
+   - Easier to audit and review
+   - Consistent behavior across all operations
+
+2. **Avoids RLS Bypass Issues**
+   - RLS policies can have bugs, be misconfigured, or be bypassed
+   - RPC functions with explicit permission checks are more reliable
+   - SECURITY DEFINER functions bypass RLS, but implement their own checks
+
+3. **Better Performance Control**
+   - Can optimize queries for specific use cases
+   - Can add caching at the function level
+   - Can pre-compute complex operations
+
+4. **Audit and Logging**
+   - All data access goes through known functions
+   - Easier to log and monitor
+   - Can add audit trails automatically
+
+5. **Business Logic Enforcement**
+   - Complex business rules enforced at database level
+   - Data validation and transformations in one place
+   - Prevents inconsistent logic across applications
+
+#### Current Architecture (Allows Both)
+
+Currently, PACE Core supports both RPC functions and direct queries:
+
+**Use RPC Functions when:**
+- Complex calculations or aggregations needed
+- Multiple tables need to be joined with complex logic
+- Performance is critical (pre-computed results)
+- Business logic is too complex for RLS policies
+- **Security-sensitive operations** (preferred for all operations)
+
+**Use Direct Queries (with RLS) when:**
+- Simple CRUD operations (only if RLS policies are properly configured)
+- Standard filtering and sorting
+- Client-side filtering is sufficient
+- No complex business logic required
+- ⚠️ **Not recommended for production** - Use RPC functions instead
+
+#### Recommended Future Architecture: RPC-Only Access
+
+For maximum security, consider migrating to an **RPC-only architecture**:
+
+1. **All table access through RPC functions**
+   - Create RPC functions for all data operations
+   - Ban direct table queries from application code
+   - Use RLS as pure defense-in-depth (should never be relied upon)
+
+2. **Benefits of RPC-Only:**
+   - **Single point of security enforcement** - All access controlled in functions
+   - **Easier auditing** - All access logged through RPC layer
+   - **Consistent behavior** - Same security checks for all operations
+   - **Easier maintenance** - Security logic in one place
+   - **Prevents bugs** - Can't accidentally bypass security by querying directly
+
+3. **RLS as Defense-in-Depth:**
+   - RLS policies still exist and provide protection
+   - But RPC functions bypass them (SECURITY DEFINER)
+   - RLS catches any bugs or unauthorized direct access attempts
+   - Acts as a safety net, not primary security
+
+4. **Migration Path:**
+   ```
+   Phase 1: Create RPC functions for all operations
+   Phase 2: Update applications to use RPC functions
+   Phase 3: Enable strict mode to log/block direct queries
+   Phase 4: Remove direct query access entirely
+   ```
+
+### Example: Consistent Security Between RLS and RPC
+
+**RLS Policy (for direct queries):**
+```sql
+CREATE POLICY "rbac_cake_meal_select" ON cake_meal
+  FOR SELECT TO authenticated
+  USING (
+    organisation_id IS NOT NULL
+    AND (
+      is_user_super_admin()
+      OR rbac_check_permission_simplified(
+        auth.uid(),
+        'read:meals',
+        organisation_id,
+        meal_event_id,
+        (SELECT id FROM rbac_apps WHERE name = 'CAKE' LIMIT 1),
+        'meals'
+      )
+    )
+  );
+```
+
+**RPC Function (for complex operations):**
+```sql
+CREATE OR REPLACE FUNCTION data_cake_meals_get(...)
+...
+BEGIN
+    -- Same security check logic as RLS policy
+    IF NOT (
+        v_is_super_admin OR
+        rbac_check_permission_simplified(
+            p_user_id,
+            'read:meals',
+            p_organisation_id,
+            p_event_id,
+            (SELECT id FROM rbac_apps WHERE name = 'CAKE' LIMIT 1),
+            'meals'
+        )
+    ) THEN
+        RETURN;
+    END IF;
+    ...
+END;
+```
+
+Both use the **same permission checking function**, ensuring consistent security behavior.
+
+## Security Best Practices
+
+### 1. Input Validation
+
+Always validate inputs:
+
+```sql
+-- Check for NULL required parameters
+IF p_event_id IS NULL THEN
+    RETURN;
+END IF;
+
+-- Check for invalid values
+IF NOT EXISTS(SELECT 1 FROM event WHERE event_id = p_event_id) THEN
+    RETURN;
+END IF;
+```
+
+### 2. Organisation Context
+
+Always require organisation context for non-super-admin operations:
+
+```sql
+-- Get organisation from context if not provided
+IF p_organisation_id IS NULL THEN
+    p_organisation_id := current_setting('app.organisation_id', true)::uuid;
+END IF;
+
+IF p_organisation_id IS NULL THEN
+    RAISE EXCEPTION 'Organisation context is required';
+END IF;
+```
+
+### 3. Super Admin Bypass
+
+Always check for super_admin status first:
+
+```sql
+DECLARE
+    v_is_super_admin BOOLEAN;
+BEGIN
+    SELECT EXISTS(
+        SELECT 1 FROM rbac_global_roles 
+        WHERE user_id = COALESCE(p_user_id, auth.uid())
+        AND role = 'super_admin'
+        AND valid_from <= NOW()
+        AND (valid_to IS NULL OR valid_to >= NOW())
+    ) INTO v_is_super_admin;
+    
+    IF v_is_super_admin THEN
+        -- Super admin can access all data
+        RETURN QUERY SELECT * FROM table_name;
+        RETURN;
+    END IF;
+    
+    -- Regular user logic with RBAC checks
+    ...
+END;
+```
+
+### 4. Organisation Membership Validation
+
+Always validate organisation membership:
+
+```sql
+IF NOT EXISTS(
+    SELECT 1 FROM rbac_organisation_roles
+    WHERE user_id = COALESCE(p_user_id, auth.uid())
+    AND organisation_id = p_organisation_id
+    AND status = 'active'
+    AND revoked_at IS NULL
+    AND valid_from <= NOW()
+    AND (valid_to IS NULL OR valid_to >= NOW())
+) THEN
+    RETURN; -- No access
+END IF;
+```
+
+### 5. Event Access Validation
+
+For event-scoped functions:
+
+```sql
+IF NOT EXISTS(
+    SELECT 1 FROM rbac_event_app_roles
+    WHERE user_id = COALESCE(p_user_id, auth.uid())
+    AND event_id = p_event_id
+    AND app_id = (SELECT id FROM rbac_apps WHERE name = 'CAKE' LIMIT 1)
+    AND status = 'active'
+) THEN
+    RETURN; -- No event access
+END IF;
+```
+
+## Performance Considerations
+
+### 1. Use Indexes
+
+Ensure queries use indexed columns:
+- `organisation_id`
+- `user_id`
+- `event_id`
+- Foreign key columns
+
+### 2. Limit Result Sets
+
+Always use `LIMIT` when appropriate:
+
+```sql
+RETURN QUERY
+SELECT * FROM table_name
+WHERE condition
+ORDER BY column
+LIMIT 1000; -- Prevent large result sets
+```
+
+### 3. Avoid N+1 Queries
+
+Use CTEs (Common Table Expressions) or JOINs instead of subqueries:
+
+```sql
+-- ❌ Bad: N+1 query pattern
+FOR rec IN SELECT id FROM table1 LOOP
+    SELECT * INTO v_data FROM table2 WHERE table1_id = rec.id;
+END LOOP;
+
+-- ✅ Good: Single query with JOIN
+RETURN QUERY
+SELECT t1.*, t2.*
+FROM table1 t1
+JOIN table2 t2 ON t2.table1_id = t1.id;
+```
+
+### 4. Cache Expensive Checks
+
+For functions called frequently, consider caching super_admin checks:
+
+```sql
+-- Cache super_admin status in function
+DECLARE
+    v_is_super_admin BOOLEAN;
+BEGIN
+    -- Check once, use multiple times
+    SELECT EXISTS(...) INTO v_is_super_admin;
+    
+    IF v_is_super_admin THEN
+        -- Fast path
+    ELSE
+        -- Regular path with RBAC
+    END IF;
+END;
+```
+
+## Testing Requirements
+
+### Unit Tests
+
+Functions should be tested with:
+
+1. **Null inputs** - Should handle gracefully
+2. **Invalid inputs** - Should return empty or error
+3. **Super admin access** - Should bypass checks
+4. **Organisation membership** - Should enforce correctly
+5. **Event access** - Should validate for event-scoped functions
+6. **Empty results** - Should return empty set, not error
+7. **Error conditions** - Should fail gracefully
+
+### Example Test
+
+```sql
+-- Test super admin access
+SELECT * FROM data_user_events_get('event-123', 'super-admin-user-id', NULL);
+-- Should return all events
+
+-- Test regular user with access
+SELECT * FROM data_user_events_get('event-123', 'regular-user-id', 'org-123');
+-- Should return events user has access to
+
+-- Test user without access
+SELECT * FROM data_user_events_get('event-123', 'unauthorized-user-id', 'org-123');
+-- Should return empty
+
+-- Test NULL input
+SELECT * FROM data_user_events_get(NULL, 'user-id', 'org-123');
+-- Should return empty gracefully
+```
+
+## Migration Guidelines
+
+### Creating New Functions
+
+1. **Create migration file**: `YYYYMMDDHHMMSS_descriptive_name.sql`
+2. **Add function**: Use standard template above
+3. **Add comments**: Document purpose, parameters, returns
+4. **Add grants**: `GRANT EXECUTE ON FUNCTION ... TO authenticated;`
+5. **Add tests**: Include test queries in migration
+6. **Update types**: Add function name to TypeScript types
+
+### Updating Existing Functions
+
+1. **Use `CREATE OR REPLACE FUNCTION`** - Ensures idempotency
+2. **Preserve backward compatibility** - Add new parameters with defaults
+3. **Version changes** - Update function name if breaking changes (e.g., `_v2`)
+4. **Document changes** - Add comments explaining changes
+
+### Deprecating Functions
+
+1. **Add deprecation notice**:
+   ```sql
+   COMMENT ON FUNCTION old_function IS 'DEPRECATED: Use new_function instead';
+   ```
+
+2. **Keep function** - Don't delete immediately, allow migration period
+
+3. **Update references** - Update all callers before removing
+
+## Common Patterns
+
+### Pattern 1: Simple Data Retrieval
+
+```sql
+CREATE OR REPLACE FUNCTION data_entity_list(
+    p_organisation_id UUID,
+    p_user_id UUID DEFAULT auth.uid()
+)
+RETURNS TABLE(id UUID, name TEXT)
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path TO 'public'
+AS $$
+BEGIN
+    -- Super admin check
+    IF EXISTS(SELECT 1 FROM rbac_global_roles WHERE user_id = p_user_id AND role = 'super_admin') THEN
+        RETURN QUERY SELECT id, name FROM entity;
+        RETURN;
+    END IF;
+    
+    -- Organisation check
+    IF NOT EXISTS(SELECT 1 FROM rbac_organisation_roles WHERE user_id = p_user_id AND organisation_id = p_organisation_id) THEN
+        RETURN;
+    END IF;
+    
+    -- Return data
+    RETURN QUERY 
+    SELECT id, name 
+    FROM entity 
+    WHERE organisation_id = p_organisation_id;
+END;
+$$;
+```
+
+### Pattern 2: Permission Check
+
+```sql
+CREATE OR REPLACE FUNCTION rbac_check_permission(
+    p_user_id UUID,
+    p_permission TEXT,
+    p_organisation_id UUID
+)
+RETURNS BOOLEAN
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path TO 'public'
+AS $$
+DECLARE
+    v_has_permission BOOLEAN := false;
+BEGIN
+    -- Super admin has all permissions
+    IF EXISTS(SELECT 1 FROM rbac_global_roles WHERE user_id = p_user_id AND role = 'super_admin') THEN
+        RETURN true;
+    END IF;
+    
+    -- Check permission
+    SELECT EXISTS(
+        SELECT 1 FROM rbac_page_permissions pp
+        JOIN rbac_organisation_roles ror ON pp.organisation_id = ror.organisation_id
+        WHERE ror.user_id = p_user_id
+        AND ror.organisation_id = p_organisation_id
+        AND pp.operation = split_part(p_permission, ':', 1)
+        AND pp.allowed = true
+    ) INTO v_has_permission;
+    
+    RETURN COALESCE(v_has_permission, false);
+END;
+$$;
+```
+
+### Pattern 3: Complex Calculation
+
+```sql
+CREATE OR REPLACE FUNCTION app_cake_distribution_calculate(
+    p_event_id TEXT,
+    p_user_id UUID DEFAULT auth.uid(),
+    p_organisation_id UUID DEFAULT NULL
+)
+RETURNS TABLE(...)
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path TO 'public'
+AS $$
+DECLARE
+    v_is_super_admin BOOLEAN;
+BEGIN
+    -- Security checks
+    ...
+    
+    -- Use CTEs for complex logic
+    WITH event_units AS (
+        SELECT unit_id FROM cake_unit WHERE unit_event_id = p_event_id
+    ),
+    unit_diners AS (
+        SELECT ... FROM cake_diner WHERE diner_unit_id IN (SELECT unit_id FROM event_units)
+    )
+    SELECT ...;
+END;
+$$;
+```
+
+## Summary Checklist
+
+When creating or reviewing an RPC function, ensure:
+
+- ✅ Follows naming convention: `<family>_<domain>_<verb>`
+- ✅ Uses `SECURITY DEFINER`
+- ✅ Sets `search_path TO 'public'`
+- ✅ Validates all inputs
+- ✅ Checks super_admin status (if applicable)
+- ✅ Validates organisation membership (if applicable)
+- ✅ Validates event access (if event-scoped)
+- ✅ Uses proper error handling
+- ✅ Returns empty on error (fail-secure)
+- ✅ Has documentation comments
+- ✅ Uses descriptive parameter names (`p_` prefix)
+- ✅ Uses descriptive variable names (`v_` prefix)
+- ✅ Has appropriate return type
+- ✅ Includes `GRANT EXECUTE` statement
+- ✅ Tested with various scenarios
+
+## References
+
+- [RBAC System Documentation](../core-concepts/rbac-system.md)
+- [Database Schema Requirements](./database-schema-requirements.md)
+- [Security Architecture](./rbac-security-architecture.md)
+