@jmruthers/pace-core 0.5.181 → 0.5.183

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

@@ -1,1106 +0,0 @@
-# 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 TEXT,  -- ⚠️ Use TEXT for strings, NOT CHARACTER VARYING
-    p_param2 INTEGER DEFAULT NULL,  -- Use INTEGER, DOUBLE PRECISION, SMALLINT for numbers
-    p_param3 BOOLEAN DEFAULT NULL,  -- Use BOOLEAN for boolean values
-    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
-    -- ⚠️ CRITICAL: Permission format must match what rbac_permissions_get returns
-    -- Format: 'operation:page.{pageName}' (e.g., 'read:page.dishes', 'create:page.meals')
-    -- The permission string is passed to rbac_permissions_get and must match exactly
-    IF NOT rbac_check_permission_simplified(
-        COALESCE(p_user_id, auth.uid()),
-        'read:page.dishes',  -- Format: operation:page.{pageName} - MUST match rbac_permissions_get output
-        p_organisation_id,
-        p_event_id,  -- p_event_id if event-scoped, NULL if org-scoped
-        (SELECT id FROM rbac_apps WHERE name = 'CAKE' LIMIT 1),  -- p_app_id
-        'dishes'  -- 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 and Types**:
-   - 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
-   - **⚠️ CRITICAL: Parameter Type Requirements**:
-     - **String parameters MUST use `TEXT`**, NOT `CHARACTER VARYING` or `VARCHAR`
-     - **Numeric parameters**: Use `DOUBLE PRECISION` for decimal numbers, `INTEGER` for whole numbers, `SMALLINT` for small integers
-     - **Boolean parameters**: Use `BOOLEAN`
-     - **Date/Time parameters**: Use `DATE`, `TIMESTAMP`, or `TIMESTAMPTZ` as appropriate
-     - **UUID parameters**: Use `UUID`
-     - **Why TEXT instead of CHARACTER VARYING?**
-       - Application code calls functions with TEXT parameters
-       - PostgreSQL cannot automatically choose between TEXT and CHARACTER VARYING versions
-       - Having both creates ambiguity errors: "Could not choose the best candidate function"
-       - TEXT is the standard PostgreSQL type for string parameters in RPC functions
-       - Even though database columns may use CHARACTER VARYING, function parameters should use TEXT
-
-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
-    -- ⚠️ CRITICAL: Permission format must be 'operation:page.{pageName}'
-    -- This matches the format returned by rbac_permissions_get()
-    IF NOT rbac_check_permission_simplified(
-        p_user_id,
-        'read:page.meals',  -- Format: operation:page.{pageName}
-        p_organisation_id,
-        p_event_id,
-        (SELECT id FROM rbac_apps WHERE name = 'CAKE' LIMIT 1),
-        'meals'  -- Page name (resolved to page ID internally)
-    ) 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:page.meals',  -- Format: operation:page.{pageName}
-        organisation_id,
-        meal_event_id,
-        (SELECT id FROM rbac_apps WHERE name = 'CAKE' LIMIT 1),
-        'meals'  -- Page name
-      )
-    )
-  );
-```
-
-**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:page.meals',  -- Format: operation:page.{pageName}
-            p_organisation_id,
-            p_event_id,
-            (SELECT id FROM rbac_apps WHERE name = 'CAKE' LIMIT 1),
-            'meals'  -- Page name
-        )
-    ) 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
-```
-
-## Permission Format
-
-### ⚠️ CRITICAL: Correct Permission Format
-
-**The permission string format is critical and must match exactly what `rbac_permissions_get()` returns.**
-
-#### Correct Format
-
-```sql
--- ✅ CORRECT: Format is 'operation:page.{pageName}'
-rbac_check_permission_simplified(
-    p_user_id,
-    'create:page.dishes',      -- Format: operation:page.{pageName}
-    p_organisation_id,
-    p_event_id,
-    v_app_id,
-    'dishes'                   -- Page name (resolved to page ID internally)
-)
-```
-
-#### Common Mistakes
-
-```sql
--- ❌ WRONG: Missing 'page.' prefix
-'create:dishes'
-
--- ❌ WRONG: Wrong separator
-'create:page/dishes'
-
--- ❌ WRONG: Wrong format entirely
-'dishes:create'
-```
-
-#### How to Determine the Correct Format
-
-1. **Check existing migrations** - Look at recent migrations that work
-2. **Check RLS policies** - Use the same format as RLS policies for the same resource
-3. **Verify with rbac_permissions_get** - The permission string must match what this function returns in the `permission_type` column
-
-#### Examples by Operation Type
-
-```sql
--- Page-based permissions (most common)
-'read:page.dishes'      -- Read dishes page
-'create:page.dishes'    -- Create dishes
-'update:page.dishes'     -- Update dishes
-'delete:page.dishes'     -- Delete dishes
-
-'read:page.meals'        -- Read meals page
-'read:page.distribution' -- Read distribution page
-'read:page.deliveries'   -- Read deliveries page
-
--- File-based permissions (special case)
-'read:files'             -- Read files
-'create:files'           -- Create files
-'delete:files'           -- Delete files
-```
-
-#### Parameter Guidelines
-
-```sql
-rbac_check_permission_simplified(
-    p_user_id,                    -- User ID (required)
-    'create:page.dishes',         -- Permission string (format: operation:page.{pageName})
-    p_organisation_id,            -- Organisation ID (required for non-super-admin)
-    p_event_id,                   -- Event ID (optional, for event-scoped permissions)
-    v_app_id,                     -- App ID (required, usually CAKE app)
-    'dishes'                      -- Page name (required, matches the page name in rbac_app_pages)
-)
-```
-
-## Migration Guidelines
-
-### Creating New Functions
-
-1. **Create migration file with correct timestamp**:
-   ```bash
-   # Generate timestamp: YYYYMMDDHHMMSS
-   date +%Y%m%d%H%M%S
-   # Example output: 20251104113510
-   
-   # Create file: supabase/migrations/20251104113510_descriptive_name.sql
-   ```
-   ⚠️ **CRITICAL**: Always generate a NEW timestamp for each migration. Never reuse timestamps from previous migrations, even if they haven't been pushed yet.
-
-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. **Regenerate types**: Run `npm run generate-types` to automatically generate TypeScript types from the database schema
-7. **Verify types**: Check that `Database['public']['Functions']['function_name']` exists in `packages/core/src/types/database.generated.ts`
-
-### ⚠️ Common Migration Mistakes
-
-1. **Reusing old migration timestamps**: 
-   - ❌ **WRONG**: Reusing `20251104113047` if it's already been pushed
-   - ✅ **CORRECT**: Generate new timestamp: `date +%Y%m%d%H%M%S` → `20251104113510`
-   - Always create a NEW file with a NEW timestamp for each migration
-
-2. **Wrong permission format**: 
-   - ❌ **WRONG**: `'create:dishes'` or `'read:meals'`
-   - ✅ **CORRECT**: `'create:page.dishes'` or `'read:page.meals'`
-   - Always use `'operation:page.{pageName}'` format, not `'operation:resource'`
-   - The format must match exactly what `rbac_permissions_get()` returns
-
-3. **Missing page_id parameter**: Always provide the page name as the last parameter (e.g., `'dishes'`, `'meals'`, `'distribution'`)
-
-4. **Using CHARACTER VARYING instead of TEXT for string parameters**:
-   - ❌ **WRONG**: `p_unit_id CHARACTER VARYING` or `p_dish_name VARCHAR`
-   - ✅ **CORRECT**: `p_unit_id TEXT` or `p_dish_name TEXT`
-   - **CRITICAL**: All string parameters MUST use `TEXT`, NOT `CHARACTER VARYING` or `VARCHAR`
-   - Having both TEXT and CHARACTER VARYING versions causes "Could not choose the best candidate function" errors
-   - Application code calls functions with TEXT parameters, so functions must accept TEXT
-   - Even though database columns may use CHARACTER VARYING, function parameters should use TEXT
-
-5. **Creating duplicate function versions**:
-   - ❌ **WRONG**: Creating both `app_cake_unit_update(TEXT, ...)` and `app_cake_unit_update(CHARACTER VARYING, ...)`
-   - ✅ **CORRECT**: Only create `app_cake_unit_update(TEXT, ...)`
-   - Before creating a new function, check if a version already exists
-   - If updating a function, use `CREATE OR REPLACE FUNCTION` to update the existing version
-   - If you need to change parameter types, drop the old version first: `DROP FUNCTION IF EXISTS ... CASCADE;`
-
-6. **Ambiguous column references**: 
-   - ❌ **WRONG**: `SELECT mealtype_name FROM cake_mealtype`
-   - ✅ **CORRECT**: `SELECT cake_mealtype.mealtype_name FROM cake_mealtype`
-   - Always fully qualify table names when there might be ambiguity
-   - **MANDATORY**: When using JOINs, always use table aliases and prefix ALL column references
-   - Common ambiguous columns: `organisation_id`, `created_by`, `updated_by`, `created_at`, `updated_at`
-   - See "Avoiding Ambiguous Column References" section below for detailed guidance
-
-7. **Not checking existing migrations**: Before creating a new migration, check if a similar one already exists to avoid duplicates
-
-### 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
-5. **Regenerate types**: Run `npm run generate-types` after function changes to update TypeScript types
-
-### 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
-
-## Avoiding Ambiguous Column References
-
-### Overview
-
-Ambiguous column reference errors occur when PostgreSQL cannot determine which table a column belongs to in a query with JOINs. This is a common source of silent failures in RPC functions.
-
-### Mandatory Rules
-
-1. **Always use table aliases in JOINs**: Never write JOINs without table aliases
-2. **Fully qualify ALL column references**: Every column in SELECT, WHERE, ORDER BY, GROUP BY, and HAVING clauses must be prefixed with its table alias
-3. **Common ambiguous columns**: The following columns exist in multiple tables and MUST always be prefixed:
-   - `organisation_id`
-   - `created_by`, `updated_by`
-   - `created_at`, `updated_at`
-   - `event_id` and its variations (e.g., `dish_event_id`, `meal_event_id`)
-
-### Correct Patterns
-
-```sql
--- ✅ CORRECT: All columns properly prefixed with table aliases
-SELECT 
-  d.dish_id,
-  d.dish_name,
-  d.organisation_id,
-  d.created_at,
-  mt.mealtype_name,
-  e.event_name,
-  e.organisation_id AS event_organisation_id
-FROM cake_dish d
-LEFT JOIN cake_mealtype mt ON d.dish_mealtype_id = mt.mealtype_id
-LEFT JOIN event e ON d.dish_event_id = e.event_id
-WHERE d.dish_event_id = p_event_id
-  AND d.organisation_id = p_organisation_id
-ORDER BY d.dish_code, mt.mealtype_name;
-
--- ✅ CORRECT: CTEs with proper aliases
-WITH distribution_items AS (
-  SELECT
-    d.item_id,
-    d.collection_date,
-    SUM(d.required_quantity) as total_quantity
-  FROM data_cake_distribution_list(p_event_id, p_user_id, p_organisation_id) d
-  GROUP BY d.item_id, d.collection_date
-)
-SELECT 
-  di.item_id,
-  di.collection_date,
-  di.total_quantity
-FROM distribution_items di
-WHERE di.item_id = p_item_id;
-```
-
-### Incorrect Patterns
-
-```sql
--- ❌ WRONG: Missing table prefixes in SELECT
-SELECT 
-  dish_id,
-  dish_name,
-  organisation_id,  -- AMBIGUOUS: Could be from cake_dish or event
-  mealtype_name
-FROM cake_dish d
-LEFT JOIN cake_mealtype mt ON d.dish_mealtype_id = mt.mealtype_id
-LEFT JOIN event e ON d.dish_event_id = e.event_id;
-
--- ❌ WRONG: Missing table prefix in WHERE clause
-SELECT d.dish_id, d.dish_name
-FROM cake_dish d
-LEFT JOIN event e ON d.dish_event_id = e.event_id
-WHERE organisation_id = p_organisation_id;  -- AMBIGUOUS: Which table?
-
--- ❌ WRONG: Missing table prefix in ORDER BY
-SELECT d.dish_id, d.dish_name, e.event_name
-FROM cake_dish d
-LEFT JOIN event e ON d.dish_event_id = e.event_id
-ORDER BY created_at;  -- AMBIGUOUS: Which table's created_at?
-
--- ❌ WRONG: SELECT INTO with multiple columns but wrong variable count
-SELECT d.dish_code, d.dish_name, mt.mealtype_name
-INTO v_mealtype_name  -- WRONG: Only one variable for three columns
-FROM cake_dish d
-LEFT JOIN cake_mealtype mt ON d.dish_mealtype_id = mt.mealtype_id;
-```
-
-### SELECT INTO Statements
-
-When using `SELECT ... INTO`, ensure:
-1. The number of columns matches the number of variables
-2. All columns are properly prefixed with table aliases
-3. Use separate variables for each column
-
-```sql
--- ✅ CORRECT: Proper SELECT INTO with multiple variables
-DECLARE
-  v_dish_code TEXT;
-  v_dish_name TEXT;
-  v_mealtype_name TEXT;
-  v_updated_at TIMESTAMPTZ;
-BEGIN
-  SELECT 
-    d.dish_code,
-    d.dish_name,
-    mt.mealtype_name,
-    d.updated_at
-  INTO 
-    v_dish_code,
-    v_dish_name,
-    v_mealtype_name,
-    v_updated_at
-  FROM cake_dish d
-  LEFT JOIN cake_mealtype mt ON d.dish_mealtype_id = mt.mealtype_id
-  WHERE d.dish_id = p_dish_id;
-END;
-```
-
-### CTEs and Subqueries
-
-When using CTEs (Common Table Expressions) or subqueries:
-1. Use descriptive aliases for CTEs
-2. Fully qualify all column references within CTEs
-3. When referencing CTEs in the main query, use the CTE alias
-
-```sql
--- ✅ CORRECT: CTE with proper aliases
-WITH unit_diners AS (
-  SELECT 
-    d.diner_unit_id,
-    d.diner_diettype_id,
-    SUM(COALESCE(d.diner_adult, 0)) as adults,
-    SUM(COALESCE(d.diner_youth, 0)) as youth
-  FROM cake_diner d
-  INNER JOIN event_units eu ON d.diner_unit_id = eu.unit_id
-  WHERE (d.diner_adult > 0 OR d.diner_youth > 0)
-  GROUP BY d.diner_unit_id, d.diner_diettype_id
-)
-SELECT 
-  ud.diner_unit_id,
-  ud.adults,
-  ud.youth
-FROM unit_diners ud
-WHERE ud.diner_unit_id = p_unit_id;
-```
-
-### Table Alias Naming Conventions
-
-Use short, descriptive aliases:
-- `d` for `cake_dish`
-- `r` for `cake_recipe`
-- `m` for `cake_meal`
-- `mt` for `cake_mealtype`
-- `i` for `cake_item`
-- `dt` for `cake_diettype`
-- `e` for `event`
-- `u` for `cake_unit`
-- `mp` for `cake_mealplan`
-
-### UPDATE Statements
-
-For UPDATE statements, the WHERE clause should reference the table being updated:
-
-```sql
--- ✅ CORRECT: WHERE clause uses table name or alias
-UPDATE cake_dish
-SET dish_name = p_dish_name,
-    updated_by = p_user_id,
-    updated_at = now()
-WHERE dish_id = p_dish_id;  -- dish_id is unambiguous (primary key)
-
--- ✅ CORRECT: When updating with JOIN, qualify all columns
-UPDATE cake_dish d
-SET d.dish_name = p_dish_name
-FROM cake_mealtype mt
-WHERE d.dish_mealtype_id = mt.mealtype_id
-  AND d.dish_id = p_dish_id;
-```
-
-### Testing for Ambiguous References
-
-Before deploying, test your function:
-1. Call the function with valid parameters
-2. Check PostgreSQL logs for "ambiguous column reference" errors
-3. Verify all column references are prefixed in JOINs
-4. Test with multiple tables that share column names
-
-## 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:
-
-### Function Structure
-- ✅ 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 with `EXCEPTION WHEN OTHERS`
-- ✅ 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
-
-### ⚠️ Critical Parameter Type Requirements
-- ✅ **String parameters use TEXT**: All string parameters MUST use `TEXT`, NOT `CHARACTER VARYING` or `VARCHAR`
-- ✅ **No duplicate function versions**: Only one version of each function exists (TEXT version, not CHARACTER VARYING)
-- ✅ **Numeric parameters use correct types**: `DOUBLE PRECISION` for decimals, `INTEGER` for whole numbers, `SMALLINT` for small integers
-- ✅ **Why TEXT?**: Application code calls with TEXT parameters; having both TEXT and CHARACTER VARYING versions causes ambiguity errors
-
-### ⚠️ Critical Permission Format
-- ✅ **Permission format is correct**: `'operation:page.{pageName}'` (e.g., `'create:page.dishes'`, `'read:page.meals'`)
-- ✅ **NOT using wrong format**: `'operation:resource'` (e.g., `'create:dishes'`, `'read:meals'`)
-- ✅ **Page name parameter provided**: Last parameter is the page name (e.g., `'dishes'`, `'meals'`)
-- ✅ **Permission format matches rbac_permissions_get output**: Verify by checking existing working migrations
-
-### ⚠️ Migration File Requirements
-- ✅ **New timestamp generated**: Run `date +%Y%m%d%H%M%S` to get current timestamp
-- ✅ **New file created**: Never reuse timestamps from previous migrations
-- ✅ **File naming**: `YYYYMMDDHHMMSS_descriptive_name.sql`
-- ✅ **No ambiguous column references**: Fully qualify table names (e.g., `cake_mealtype.mealtype_name`)
-
-### ⚠️ Column Reference Requirements
-- ✅ **All column references in JOINs are fully qualified with table aliases**: Every column in SELECT, WHERE, ORDER BY, GROUP BY, HAVING must have table prefix
-- ✅ **No ambiguous column references in WHERE, ORDER BY, GROUP BY, HAVING clauses**: All columns must be prefixed with table alias
-- ✅ **Table aliases used consistently and meaningfully**: Use short, descriptive aliases (e.g., `d` for dish, `r` for recipe)
-- ✅ **SELECT INTO statements match variable count**: Number of columns must match number of variables
-
-## References
-
-- [RBAC System Documentation](../core-concepts/rbac-system.md)
-- [Database Schema Requirements](./database-schema-requirements.md)
-- [Security Architecture](./rbac-security-architecture.md)
-