@jmruthers/pace-core 0.5.185 → 0.5.187

package/docs/api-reference/components.md

@@ -1829,37 +1829,51 @@ A comprehensive file upload component with drag-and-drop support, validation, an
 ```typescript
 interface FileUploadProps {
   supabase: SupabaseClient;
-  appName: string;
-  orgId: string;
-  onUploadComplete?: (fileRef: FileReference) => void;
-  onUploadStart?: (file: File) => void;
+  table_name: string;
+  record_id: string;
+  organisation_id: string;
+  app_id?: string; // Optional - will be resolved from app name if not provided
+  category: FileCategory; // File category for metadata (stored in file_metadata JSONB field)
+  folder: string; // Folder name in storage bucket (e.g., 'profile_photos', 'documents')
+  pageContext: string; // The page context where the file upload occurs (e.g., 'configuration', 'forms', 'applications')
   accept?: string;
   maxSize?: number;
   multiple?: boolean;
   disabled?: boolean;
+  isPublic?: boolean; // Whether files should be uploaded to public-files bucket
   className?: string;
+  showPreview?: boolean; // Show image preview for accepted files
+  showProgress?: boolean; // Show upload progress bar
+  onUploadSuccess?: (result: FileUploadResult) => void;
+  onUploadError?: (error: string, file?: File) => void;
+  onProgress?: (progress: UploadProgress) => void;
   children?: React.ReactNode;
 }
 ```
 
+**Note:** The `category` prop is used for metadata purposes (stored in the `file_metadata` JSONB field), while the `folder` prop determines the actual storage path: `{orgId}/{folder}/{timestamp-uuid-filename}`. You can use the same value for both (e.g., `category={FileCategory.PROFILE_PHOTOS}` and `folder="profile_photos"`), or use different values if needed.
+
 #### Usage
 
 ```tsx
-import { FileUpload, FileCategory, logger } from '@jmruthers/pace-core';
+import { FileUpload, FileCategory } from '@jmruthers/pace-core';
 
 function MyFileUpload() {
-  const handleUpload = (fileRef: FileReference) => {
-    logger.debug('FileUpload', 'File uploaded:', { fileId: fileRef.id, fileName: fileRef.name });
-  };
-
   return (
     <FileUpload
       supabase={supabase}
-      appName="my-app"
-      orgId={organisationId}
-      onUploadComplete={handleUpload}
+      table_name="pace_person"
+      record_id={personId}
+      organisation_id={organisationId}
+      category={FileCategory.PROFILE_PHOTOS}
+      folder="profile_photos"
+      pageContext="configuration"
       accept="image/*"
       maxSize={2 * 1024 * 1024} // 2MB
+      onUploadSuccess={(result) => {
+        console.log('Uploaded:', result.file_reference);
+        console.log('URL:', result.file_url);
+      }}
     >
       <div className="border-2 border-dashed border-main-300 rounded-lg p-8 text-center">
         <p>Drag and drop files here or click to browse</p>

package/docs/best-practices/performance.md

@@ -490,6 +490,17 @@ function VirtualizedEventList() {
 
 ## Network Optimization
 
+### RBAC Performance Optimizations
+
+The RBAC system includes built-in performance optimizations that significantly reduce network requests:
+
+- **Request Deduplication**: Multiple components checking the same permission share network requests
+- **Enhanced Caching**: Two-tier caching (60s short-term + 5min session cache)
+- **Batched Audit Logging**: Audit events are batched to reduce network requests
+- **Memoization**: Components are memoized to prevent unnecessary re-renders
+
+See the [RBAC Performance Guide](../rbac/performance.md) for detailed information.
+
 ### 1. Request Deduplication
 
 ```typescript

package/docs/implementation-guides/file-reference-system.md

@@ -45,14 +45,16 @@ CREATE TABLE file_references (
 
 **Organisation-First Structure:**
 ```
-{bucket}/{orgId}/{category}/{filename}
+{bucket}/{orgId}/{folder}/{timestamp-uuid-filename}
 
 Examples:
 - files/org-123/profile_photos/timestamp-uuid-photo.jpg (private)
-- files/org-123/id_documents/timestamp-uuid-passport.pdf (private)
+- files/org-123/documents/timestamp-uuid-passport.pdf (private)
 - public-files/org-123/event_logos/timestamp-uuid-logo.png (public)
 ```
 
+**Note:** The `folder` prop determines the storage path, while `category` is stored in the `file_metadata` JSONB field for filtering and metadata purposes. You can use the same value for both (e.g., `category={FileCategory.PROFILE_PHOTOS}` and `folder="profile_photos"`), or use different values if needed.
+
 ### Bucket Selection
 
 The system uses two Supabase storage buckets:
@@ -77,7 +79,10 @@ await service.createFileReference({
   table_name: 'pace_person',
   record_id: personId,
   organisation_id: orgId,
+  app_id: 'your-app-id',
   category: FileCategory.PROFILE_PHOTOS,
+  folder: 'profile_photos',
+  pageContext: 'configuration',
   is_public: false // Uses 'files' bucket
 }, file);
 
@@ -86,7 +91,10 @@ await service.createFileReference({
   table_name: 'event',
   record_id: eventId,
   organisation_id: orgId,
+  app_id: 'your-app-id',
   category: FileCategory.EVENT_LOGOS,
+  folder: 'event_logos',
+  pageContext: 'configuration',
   is_public: true // Uses 'public-files' bucket
 }, file);
 ```
@@ -136,6 +144,8 @@ import { FileUpload, FileCategory } from '@jmruthers/pace-core';
   organisation_id={orgId}
   app_id="your-app-id" // Optional - auto-resolved from app name if not provided
   category={FileCategory.PROFILE_PHOTOS}
+  folder="profile_photos"
+  pageContext="configuration"
   accept="image/*"
   maxSize={5 * 1024 * 1024}
   onUploadSuccess={(result) => {
@@ -157,6 +167,8 @@ import { FileUpload, FileCategory } from '@jmruthers/pace-core';
   organisation_id={orgId}
   // app_id omitted - will be auto-resolved from app name
   category={FileCategory.PROFILE_PHOTOS}
+  folder="profile_photos"
+  pageContext="configuration"
   accept="image/*"
   maxSize={5 * 1024 * 1024}
   showProgress={true}
@@ -191,6 +203,8 @@ import { FileUpload, FileCategory } from '@jmruthers/pace-core';
   organisation_id={orgId}
   app_id="your-app-id"
   category={FileCategory.EVENT_LOGOS}
+  folder="event_logos"
+  pageContext="configuration"
   accept="image/*"
   isPublic={true} // Uploads to public-files bucket
   showPreview={true}
@@ -210,6 +224,8 @@ import { FileUpload, FileCategory } from '@jmruthers/pace-core';
   organisation_id={orgId}
   app_id="your-app-id"
   category={FileCategory.PROFILE_PHOTOS}
+  folder="profile_photos"
+  pageContext="configuration"
 >
   <div className="custom-upload-ui">
     <p>Click to upload profile photo</p>
@@ -237,6 +253,8 @@ import { FileDisplay, FileCategory } from '@jmruthers/pace-core';
     organisation_id={orgId}
     app_id="your-app-id"
     category={FileCategory.PROFILE_PHOTOS}
+    folder="profile_photos"
+    pageContext="configuration"
   />
 </FileDisplay>
 ```
@@ -331,6 +349,8 @@ const result = await uploadFile({
   organisation_id: orgId,
   app_id: 'your-app-id',
   category: FileCategory.PROFILE_PHOTOS,
+  folder: 'profile_photos',
+  pageContext: 'configuration',
   is_public: false // Uses 'files' bucket
 }, file);
 
@@ -341,6 +361,8 @@ const publicResult = await uploadFile({
   organisation_id: orgId,
   app_id: 'your-app-id',
   category: FileCategory.EVENT_LOGOS,
+  folder: 'event_logos',
+  pageContext: 'configuration',
   is_public: true // Uses 'public-files' bucket
 }, logoFile);
 

package/docs/implementation-guides/file-upload-storage.md

@@ -48,6 +48,7 @@ function MyFileUpload() {
       organisation_id="org-123"
       // app_id auto-resolved from app name
       category={FileCategory.GENERAL_DOCUMENTS}
+      folder="documents"
       pageContext="configuration"
       accept=".pdf,.doc,.docx"
       maxSize={5 * 1024 * 1024} // 5MB
@@ -103,6 +104,8 @@ function UserProfile({ userId }: { userId: string }) {
           record_id={userId}
           organisation_id="org-123"
           category={FileCategory.GENERAL_DOCUMENTS}
+          folder="documents"
+          pageContext="configuration"
           accept=".pdf,.doc,.docx"
           maxSize={10 * 1024 * 1024}
         />
@@ -127,7 +130,8 @@ interface FileUploadProps {
   record_id: string;
   organisation_id: string;
   app_id?: string; // Optional - will be resolved from app name if not provided
-  category: FileCategory;
+  category: FileCategory; // File category for metadata (stored in file_metadata JSONB field)
+  folder: string; // Folder name in storage bucket (e.g., 'profile_photos', 'documents')
   pageContext: string; // The page context where the file upload occurs (e.g., 'configuration', 'forms', 'applications')
   accept?: string;
   maxSize?: number;
@@ -144,6 +148,8 @@ interface FileUploadProps {
 }
 ```
 
+**Note:** The `category` prop is used for metadata purposes (stored in the `file_metadata` JSONB field), while the `folder` prop determines the actual storage path: `{orgId}/{folder}/{timestamp-uuid-filename}`. You can use the same value for both (e.g., `category={FileCategory.PROFILE_PHOTOS}` and `folder="profile_photos"`), or use different values if needed.
+
 #### Usage Examples
 
 **Basic Upload:**
@@ -154,6 +160,7 @@ interface FileUploadProps {
   record_id="person-123"
   organisation_id={organisationId}
   category={FileCategory.PROFILE_PHOTOS}
+  folder="profile_photos"
   pageContext="configuration"
   accept="image/*"
   maxSize={2 * 1024 * 1024} // 2MB
@@ -171,6 +178,7 @@ interface FileUploadProps {
   record_id="person-123"
   organisation_id={organisationId}
   category={FileCategory.GENERAL_DOCUMENTS}
+  folder="documents"
   pageContext="forms"
   multiple={true}
   accept=".pdf,.doc,.docx"
@@ -273,6 +281,8 @@ interface FileDisplayProps {
     record_id={personId}
     organisation_id={organisationId}
     category={FileCategory.IMAGES}
+    folder="images"
+    pageContext="configuration"
     accept="image/*"
     showPreview={true}
   />
@@ -294,6 +304,29 @@ interface FileDisplayProps {
 // without wrapper divs, borders, or metadata. Prefers image files over other types.
 ```
 
+**Document Display (Clickable Links):**
+```tsx
+// Display a PDF or other document as a clickable link
+<FileDisplay
+  supabase={supabase}
+  table_name="medi_action_plan"
+  record_id={planId}
+  organisation_id={organisationId}
+  category={FileCategory.MEDICAL_DOCUMENTS}
+  displayOnly={true}
+  showFallback={true}
+  fallbackText="View Action Plan"
+/>
+// When displayOnly is true and the file is NOT an image (e.g., PDF, Word doc, Excel),
+// renders as a clickable link that opens in a new tab. The link includes:
+// - Document icon (FileText) on the left
+// - Filename in the center
+// - External link icon on the right
+// - Proper security attributes (rel="noopener noreferrer")
+// - Full accessibility support (ARIA labels, keyboard navigation, focus states)
+// If the file URL is unavailable, falls back to the fallback UI.
+```
+
 ## Hooks
 
 ### useFileReference
@@ -451,6 +484,8 @@ await uploadFile({
   organisation_id: 'org-123',
   app_id: 'app-123',
   category: FileCategory.GENERAL_DOCUMENTS,
+  folder: 'documents',
+  pageContext: 'configuration',
   is_public: false
 }, pdfFile);
 
@@ -461,6 +496,8 @@ await uploadFile({
   organisation_id: 'org-123',
   app_id: 'app-123',
   category: FileCategory.PROFILE_PHOTOS,
+  folder: 'profile_photos',
+  pageContext: 'configuration',
   is_public: false
 }, imageFile);
 ```

package/docs/rbac/README.md

@@ -96,7 +96,7 @@ The RBAC system uses a **database-first architecture** where all permission logi
 ## 🎯 Key Features
 
 - **🔐 Secure by Default** - Organisation context enforced, RLS integrated, database-first API
-- **⚡ High Performance** - Intelligent caching with 60s TTL, optimized RPC calls
+- **⚡ High Performance** - Intelligent two-tier caching (60s + 5min), request deduplication, batched audit logging, optimized RPC calls
 - **🎨 React Integration** - Hooks and components for easy UI integration
 - **🔄 Real-time Updates** - Automatic cache invalidation on permission changes
 - **📊 Audit Logging** - Complete audit trail for all permission checks
@@ -422,6 +422,7 @@ When database connection is lost:
 - **[API Reference](./api-reference.md)** - Explore all available APIs
 - **[Examples](./examples.md)** - See real-world usage patterns
 - **[Advanced Patterns](./advanced-patterns.md)** - Learn optimization techniques
+- **[Performance Guide](./performance.md)** - Performance optimizations and configuration
 
 ## 🆘 Need Help?
 

package/docs/rbac/api-reference.md

@@ -331,6 +331,17 @@ function UsersPage() {
 
 4. **Error Handling**: If permission check fails, the component shows the `fallback`. Check browser console for `[PagePermissionGuard]` logs to debug issues.
 
+#### Performance Optimizations
+
+`PagePermissionGuard` includes built-in performance optimizations:
+
+- **Request Deduplication**: Multiple instances checking the same permission share network requests
+- **Enhanced Caching**: Two-tier caching (60s short-term + 5min session cache for page-level checks)
+- **Batched Audit Logging**: Audit events are automatically batched to reduce network requests
+- **Memoization**: Component is memoized with deep equality checks to prevent unnecessary re-renders
+
+These optimizations reduce network requests from 1,200+ to <50 per page load. See [RBAC Performance Guide](../rbac/performance.md) for details.
+
 ### NavigationGuard
 
 Conditionally render navigation items based on permissions.

package/docs/rbac/performance.md

@@ -0,0 +1,320 @@
+---
+lastUpdated: 2025-01-26T00:00:00+11:00
+version: 0.5.186
+reviewedBy: documentation-standards-audit
+---
+
+# RBAC Performance Optimizations
+
+> **📚 RBAC Performance Guide** | [← Back to RBAC Documentation](./README.md) | [API Reference](./api-reference.md)
+
+The RBAC system includes comprehensive performance optimizations to minimize network requests and improve page load times. This guide explains how these optimizations work and how to configure them.
+
+## Overview
+
+The RBAC performance optimizations address the common issue of excessive network requests when using `PagePermissionGuard` and other RBAC components. Without optimizations, a single page load could generate 1,200+ network requests. With optimizations enabled, this is reduced to <50 requests per page load.
+
+## Performance Features
+
+### 1. Request Deduplication
+
+**Problem**: Multiple components checking the same permission simultaneously make separate network requests.
+
+**Solution**: Request deduplication shares in-flight permission check requests across all components. When multiple `PagePermissionGuard` instances check the same permission at the same time, they share a single network request.
+
+**How it works**:
+- When a permission check is requested, the system checks if an identical request is already in-flight
+- If found, the existing promise is returned instead of making a new request
+- The deduplication map is automatically cleaned up when requests complete
+
+**Example**:
+```tsx
+// Three components checking the same permission
+<PagePermissionGuard pageName="dashboard" operation="read">
+  <Component1 />
+</PagePermissionGuard>
+<PagePermissionGuard pageName="dashboard" operation="read">
+  <Component2 />
+</PagePermissionGuard>
+<PagePermissionGuard pageName="dashboard" operation="read">
+  <Component3 />
+</PagePermissionGuard>
+// Result: Only 1 network request instead of 3
+```
+
+**Configuration**: Enabled by default. Can be disabled via configuration:
+```typescript
+setupRBAC(supabase, {
+  performance: {
+    enableRequestDeduplication: false, // Disable deduplication
+  },
+});
+```
+
+### 2. Enhanced Caching
+
+**Problem**: Short cache TTL (60 seconds) causes frequent re-checks, especially for stable page-level permissions.
+
+**Solution**: Two-tier caching strategy with session-level cache for page-level permissions.
+
+**Cache Tiers**:
+- **Short-term cache**: 60 seconds for frequently changing permissions
+- **Session cache**: 5 minutes for stable page-level permissions
+
+**How it works**:
+- Permission checks first look in the short-term cache
+- If not found, check the session cache (for page-level checks)
+- Page-level permission checks automatically use session cache
+- Cache is invalidated on user/org/event changes
+
+**Example**:
+```typescript
+// First check: Network request + cache result
+await isPermittedCached({ userId, scope, permission: 'read:page.dashboard' });
+
+// Subsequent checks within 5 minutes: Cache hit (no network request)
+await isPermittedCached({ userId, scope, permission: 'read:page.dashboard' });
+```
+
+**Configuration**:
+```typescript
+setupRBAC(supabase, {
+  cache: {
+    ttl: 60000, // Short-term cache TTL (default: 60s)
+    sessionTtl: 300000, // Session cache TTL (default: 5min)
+  },
+});
+```
+
+### 3. Batched Audit Logging
+
+**Problem**: Every permission check generates a separate audit log request, even for cached checks.
+
+**Solution**: Batched audit logging queues events and sends them in batches, and skips logging for cached checks.
+
+**How it works**:
+- Audit events are queued instead of being sent immediately
+- Events are batched by time window (default: 100ms) or batch size (default: 10 events)
+- Cached permission checks skip audit logging entirely (only cache misses are logged)
+- Batches are automatically flushed when the window expires or batch size is reached
+
+**Example**:
+```typescript
+// 10 permission checks in quick succession
+// Without batching: 10 separate audit log requests
+// With batching: 1 batched request with 10 events
+```
+
+**Configuration**:
+```typescript
+setupRBAC(supabase, {
+  audit: {
+    batched: true, // Enable batched logging (default: true)
+    batchWindow: 100, // Time window in ms (default: 100ms)
+    batchSize: 10, // Maximum batch size (default: 10)
+  },
+  performance: {
+    enableBatchedAuditLogging: true, // Enable/disable (default: true)
+  },
+});
+```
+
+### 4. Improved Memoization
+
+**Problem**: Scope objects are recreated on every render, causing unnecessary permission re-checks.
+
+**Solution**: Deep equality checks for scope objects and React.memo for components.
+
+**How it works**:
+- `PagePermissionGuard` uses `React.memo` to prevent unnecessary re-renders
+- Scope objects are compared using deep equality instead of reference equality
+- Permission strings are memoized to prevent recreation
+- Only re-check permissions when dependencies actually change
+
+**Example**:
+```tsx
+// Component re-renders with same scope object
+// Without memoization: Permission re-checked
+// With memoization: Cached result used, no re-check
+```
+
+**Configuration**: Automatic, no configuration needed.
+
+### 5. Performance Monitoring
+
+**Problem**: No visibility into performance metrics and optimization effectiveness.
+
+**Solution**: Built-in performance monitoring tracks key metrics.
+
+**Metrics Tracked**:
+- Total permission checks
+- Cache hit rate
+- Request deduplication rate
+- Network request count
+- Average response time
+- Batched vs individual audit events
+
+**Usage**:
+```typescript
+import { 
+  enablePerformanceMonitoring,
+  getPerformanceMetrics,
+  getPerformanceSummary 
+} from '@jmruthers/pace-core/rbac';
+
+// Enable monitoring
+enablePerformanceMonitoring();
+
+// Get metrics
+const metrics = getPerformanceMetrics();
+console.log('Cache hit rate:', metrics.cacheHitRate);
+console.log('Network requests:', metrics.networkRequests);
+
+// Get formatted summary
+console.log(getPerformanceSummary());
+```
+
+**Configuration**:
+```typescript
+setupRBAC(supabase, {
+  performance: {
+    enablePerformanceTracking: true, // Enable in development
+  },
+});
+```
+
+## Configuration
+
+All performance optimizations can be configured when setting up RBAC:
+
+```typescript
+import { setupRBAC } from '@jmruthers/pace-core/rbac';
+
+setupRBAC(supabase, {
+  // Cache configuration
+  cache: {
+    ttl: 60000, // Short-term cache TTL (default: 60s)
+    sessionTtl: 300000, // Session cache TTL (default: 5min)
+    enabled: true, // Enable caching (default: true)
+  },
+  
+  // Audit configuration
+  audit: {
+    enabled: true, // Enable audit logging (default: true)
+    batched: true, // Enable batched logging (default: true)
+    batchWindow: 100, // Batch time window in ms (default: 100ms)
+    batchSize: 10, // Maximum batch size (default: 10)
+  },
+  
+  // Performance configuration
+  performance: {
+    enableRequestDeduplication: true, // Enable deduplication (default: true)
+    enableBatchedAuditLogging: true, // Enable batched audit (default: true)
+    enablePerformanceTracking: false, // Enable monitoring (default: false in production)
+  },
+});
+```
+
+## Expected Performance Improvements
+
+With all optimizations enabled:
+
+| Metric | Before | After | Improvement |
+|--------|--------|-------|-------------|
+| Network Requests | 1,200+ | <50 | 96% reduction |
+| Page Load Time | 1+ minute | <5 seconds | 92% reduction |
+| Bandwidth | 13+ MB | <1 MB | 92% reduction |
+| Cache Hit Rate | N/A | >90% | - |
+| Audit Log Requests | 1,200+ | <50 | 96% reduction |
+
+## Best Practices
+
+### 1. Enable All Optimizations
+
+All optimizations are enabled by default. Only disable them if you have a specific reason:
+
+```typescript
+// ✅ Good: Use defaults
+setupRBAC(supabase);
+
+// ❌ Avoid: Disabling optimizations without reason
+setupRBAC(supabase, {
+  performance: {
+    enableRequestDeduplication: false, // Only if you have a specific need
+  },
+});
+```
+
+### 2. Monitor Performance in Development
+
+Enable performance tracking during development to identify bottlenecks:
+
+```typescript
+setupRBAC(supabase, {
+  performance: {
+    enablePerformanceTracking: import.meta.env.MODE === 'development',
+  },
+});
+```
+
+### 3. Adjust Cache TTL Based on Use Case
+
+For applications with frequently changing permissions, reduce cache TTL:
+
+```typescript
+setupRBAC(supabase, {
+  cache: {
+    ttl: 30000, // 30 seconds for frequently changing permissions
+    sessionTtl: 180000, // 3 minutes for page-level checks
+  },
+});
+```
+
+### 4. Tune Batch Settings for High-Volume Apps
+
+For applications with many permission checks, adjust batch settings:
+
+```typescript
+setupRBAC(supabase, {
+  audit: {
+    batchWindow: 50, // Shorter window for faster batching
+    batchSize: 20, // Larger batches for high volume
+  },
+});
+```
+
+## Troubleshooting
+
+### High Network Request Count
+
+If you're still seeing high request counts:
+
+1. **Check cache hit rate**: Use performance monitoring to verify cache is working
+2. **Verify deduplication**: Ensure multiple components aren't bypassing deduplication
+3. **Check audit batching**: Verify batched audit logging is enabled
+4. **Review scope changes**: Ensure scope objects aren't being recreated unnecessarily
+
+### Low Cache Hit Rate
+
+If cache hit rate is low:
+
+1. **Check cache TTL**: Verify cache TTL settings are appropriate
+2. **Review cache invalidation**: Ensure cache isn't being invalidated too frequently
+3. **Verify session cache**: Check that page-level checks are using session cache
+4. **Monitor scope changes**: Frequent scope changes will reduce cache effectiveness
+
+### Performance Monitoring Not Working
+
+If performance monitoring isn't showing data:
+
+1. **Verify it's enabled**: Check `enablePerformanceTracking` is set to `true`
+2. **Check timing**: Metrics accumulate over time, check after multiple permission checks
+3. **Review console**: Check for any errors in the console
+
+## Related Documentation
+
+- [PagePermissionGuard API Reference](./api-reference.md#pagepermissionguard) - Component API
+- [RBAC Configuration](./api-reference.md#configuration) - Configuration options
+- [Performance Best Practices](../best-practices/performance.md) - General performance guide
+- [RBAC Getting Started](./getting-started.md) - Getting started guide
+

package/docs/standards/01-architecture-standard.md

@@ -11,6 +11,11 @@ Define the core architectural principles for pace-core so that components, APIs,
 - Secure by default
 - Performance-conscious
 
+## Performance Requirements
+- **RLS policies must use helper functions** - Never use subqueries in RLS policies as they cause N+1 query patterns
+- **Database migrations must be tested** - Verify migrations don't cause query timeouts or performance degradation
+- **Monitor query performance** - Use EXPLAIN ANALYZE to verify RLS policies don't create expensive execution plans
+
 ## Boundaries
 ### In scope
 - UI primitives

package/docs/standards/05-security-standard.md

@@ -13,6 +13,16 @@
 - Never store secrets in code
 - Use safe error messaging
 
+## RLS Policy Performance Rules
+- **NEVER use subqueries in RLS policies** - They execute for every row check and cause severe performance degradation
+- **ALWAYS use helper functions** - Create STABLE SECURITY DEFINER functions for lookups (e.g., `get_base_app_id()`, `get_form_event_id()`)
+- **Helper functions must be**:
+  - `STABLE` - Results are consistent within a transaction
+  - `SECURITY DEFINER` - Bypass RLS to avoid recursion
+  - `SET search_path TO 'public'` - Prevent search path injection
+- **Test RLS policies** - Verify they don't cause query timeouts or N+1 query patterns
+- **Monitor performance** - Watch for slow queries after RLS policy changes
+
 ## Logging Rules
 Allowed:
 - IDs
@@ -28,3 +38,5 @@ Forbidden:
 - Ensure no sensitive logs
 - Replace raw errors with ApiError
 - Validate input shapes
+- **RLS policies use helper functions, not subqueries**
+- **Helper functions are STABLE and SECURITY DEFINER**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmruthers/pace-core",
-  "version": "0.5.185",
+  "version": "0.5.187",
   "description": "Clean, modern React component library with Tailwind v4 styling and native utilities",
   "private": false,
   "publishConfig": {