dzql 0.4.2 → 0.4.4

package/README.md

@@ -7,7 +7,7 @@ PostgreSQL-powered framework with automatic CRUD operations, live query subscrip
 - **[Documentation Hub](docs/)** - Complete documentation index
 - **[Getting Started Tutorial](docs/getting-started/tutorial.md)** - Complete tutorial with working todo app
 - **[API Reference](docs/reference/api.md)** - Complete API documentation
-- **[Live Query Subscriptions](docs/getting-started/subscriptions-quick-start.md)** - Real-time denormalized documents (NEW in v0.2.0)
+- **[Live Query Subscriptions](docs/getting-started/subscriptions-quick-start.md)** - Real-time denormalized documents
 - **[Compiler Documentation](docs/compiler/)** - Entity compilation guide and coding standards
 - **[Claude Guide](docs/for-ai/claude-guide.md)** - Development guide for AI assistants
 - **[Venues Example](../venues/)** - Full working application
@@ -32,7 +32,7 @@ await ws.connect();
 const user = await ws.api.save.users({ name: 'Alice' });
 const results = await ws.api.search.users({ filters: { name: 'alice' } });
 
-// NEW in v0.2.0: Live query subscriptions
+// Live query subscriptions
 const { data, unsubscribe } = await ws.api.subscribe_venue_detail(
   { venue_id: 123 },
   (updated) => console.log('Venue changed!', updated)
@@ -59,17 +59,20 @@ See **[Compiler Documentation](docs/compiler/)** for complete usage guide, codin
 ## Testing
 
 ```bash
-# Start test database
-cd tests/test-utils && docker compose up -d
+# From repository root - start test database
+docker compose up -d
+
+# Initialize test database
+bun run test:init
 
 # Run tests
 bun test
 
 # Stop database
-cd tests/test-utils && docker compose down
+docker compose down
 ```
 
-All tests use `bun:test` framework with automatic database setup/teardown. See **[tests/test-utils/README.md](tests/test-utils/README.md)** for details.
+All tests use `bun:test` framework. See **[tests/README.md](../../tests/README.md)** for details.
 
 ## License
 

package/docs/README.md

@@ -7,6 +7,7 @@ Complete documentation for the DZQL PostgreSQL-powered framework.
 New to DZQL? Start here:
 
 - **[Tutorial](getting-started/tutorial.md)** - Complete step-by-step guide with a working todo app
+- **[Interpreter vs Compiler](guides/interpreter-vs-compiler.md)** - Understand the two execution modes
 - **[Subscriptions Quick Start](getting-started/subscriptions-quick-start.md)** - Get real-time subscriptions working in 5 minutes
 
 ## 📖 Guides
@@ -14,6 +15,9 @@ New to DZQL? Start here:
 Feature-specific guides and how-tos:
 
 - **[Live Query Subscriptions](guides/subscriptions.md)** - Real-time denormalized documents
+- **[Many-to-Many Relationships](guides/many-to-many.md)** - Junction table management
+- **[Field Defaults](guides/field-defaults.md)** - Auto-populate fields on create
+- **[Custom Functions](guides/custom-functions.md)** - Extend with PostgreSQL or Bun functions
 - **[Client Stores](guides/client-stores.md)** - Pinia store patterns for Vue.js
 
 ## 📘 Reference
@@ -29,7 +33,7 @@ Complete API documentation:
 - [Quickstart](compiler/QUICKSTART.md) - Get started with the DZQL compiler
 - [Advanced Filters](compiler/ADVANCED_FILTERS.md) - Complex search operators
 - [Coding Standards](compiler/CODING_STANDARDS.md) - Best practices for DZQL code
-- [Comparison](compiler/COMPARISON.md) - DZQL vs other approaches
+- [Comparison](compiler/COMPARISON.md) - Runtime vs compiled side-by-side
 
 ## 🤖 For AI Assistants
 
@@ -40,28 +44,6 @@ Complete API documentation:
 - [npm Package](https://www.npmjs.com/package/dzql)
 - [GitHub Repository](https://github.com/blueshed/dzql)
 - [Issue Tracker](https://github.com/blueshed/dzql/issues)
-- [Changelog](../../../CHANGELOG.md)
-- [Contributing](../../../CONTRIBUTING.md)
-
-## 🏗️ Architecture
-
-Looking for architecture and design docs? See the [repository docs](../../../docs/):
-
-- [Permissions System](../../../docs/architecture/PERMISSIONS.md)
-- [Project Roadmap](../../../docs/architecture/ROADMAP.md)
-- [Subscription Architecture](../../../docs/architecture/SUBSCRIPTIONS_STRATEGY.md)
-
-## 🧪 Development
-
-Contributing to DZQL? See development documentation:
-
-- [TDD Workflow](../../../docs/development/TDD_WORKFLOW.md)
-- [WebSocket Testing](../../../docs/development/WEBSOCKET_TESTING.md)
-- [Claude Web Setup](../../../docs/development/CLAUDE-WEB.md)
-
-## 📦 Package Contents
-
-This documentation is published with the npm package. For repository-wide documentation (contributors, development workflow, architecture), see [`/docs/`](../../../docs/) in the repository root.
 
 ## Need Help?
 

package/docs/for-ai/claude-guide.md

@@ -2,6 +2,38 @@
 
 This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
 
+## Quick Reference Card
+
+```
+DZQL QUICK REFERENCE
+====================
+
+5 Operations:     get, save, delete, lookup, search
+2 Modes:          Interpreter (runtime) | Compiler (static SQL)
+Client API:       ws.api.{operation}.{entity}(params)
+Server API:       db.api.{operation}.{entity}(params, userId)
+
+Entity Registration:
+  dzql.register_entity(
+    table_name,           -- 'todos'
+    label_field,          -- 'title' (for lookups)
+    searchable_fields,    -- ARRAY['title', 'description']
+    fk_includes,          -- '{"org": "organisations"}'
+    soft_delete,          -- false
+    temporal_fields,      -- '{}'
+    notification_paths,   -- '{"ownership": ["@org_id->acts_for..."]}'
+    permission_paths,     -- '{"view": [], "create": [...]}'
+    graph_rules,          -- '{"on_create": {...}, "many_to_many": {...}}'
+    field_defaults        -- '{"owner_id": "@user_id"}'
+  )
+
+M2M id_field naming:  tag_ids (singular + _ids), NOT tags_ids
+Permission [] = public, omitted = denied
+Path syntax: @field->table[filter]{temporal}.target_field
+
+Compile: dzql compile entities.sql -o compiled/
+```
+
 ## Project Overview
 
 DZQL is a PostgreSQL-powered framework that eliminates CRUD boilerplate by providing automatic database operations, real-time WebSocket synchronization, and graph-based relationship management. The core concept: register an entity in PostgreSQL and instantly get 5 standard operations (get, save, delete, lookup, search) plus real-time notifications with zero code.

package/docs/guides/interpreter-vs-compiler.md

@@ -0,0 +1,237 @@
+# Interpreter vs Compiler Mode
+
+DZQL offers two execution modes for your entities. Understanding when to use each is fundamental to getting the best out of the framework.
+
+## Quick Summary
+
+| Aspect | Interpreter | Compiler |
+|--------|-------------|----------|
+| **Setup** | Register entity, use immediately | Register entity, compile, deploy SQL |
+| **Performance** | ~8-12ms per operation | ~2-4ms per operation |
+| **Debugging** | Opaque (dynamic SQL) | Transparent (static SQL) |
+| **Best For** | Development, prototyping | Production, performance-critical |
+
+## How It Works
+
+### Interpreter Mode (Runtime)
+
+Entity configuration is stored as JSON in `dzql.entities` table and parsed at runtime:
+
+```
+Client Request → generic_exec() → Parse JSON config → Build SQL → Execute
+```
+
+**Characteristics:**
+- Zero build step - changes take effect immediately
+- JSON config parsed on every request
+- Dynamic SQL generated at runtime
+- Generic query plans (harder to optimize)
+
+**Usage:**
+```sql
+-- Register entity
+SELECT dzql.register_entity('todos', 'title', ARRAY['title'], ...);
+
+-- Use immediately via generic executor
+SELECT dzql.generic_exec('save', 'todos', '{"title": "Buy milk"}'::jsonb, 1);
+```
+
+### Compiler Mode (Static)
+
+Entity configuration is compiled into dedicated PostgreSQL functions:
+
+```
+Entity Definition → dzql compile → Static SQL Functions → Deploy → Execute
+```
+
+**Characteristics:**
+- Build step required
+- No JSON parsing at runtime
+- Static SQL with specific query plans
+- PostgreSQL can optimize and cache plans
+
+**Usage:**
+```bash
+# Compile entities to SQL
+dzql compile entities.sql -o compiled/
+
+# Deploy to database
+psql < compiled/entities.sql
+```
+
+```sql
+-- Use compiled functions directly
+SELECT save_todos('{"title": "Buy milk"}'::jsonb, 1);
+```
+
+## The Server Automatically Chooses
+
+The DZQL server (`db.js`) automatically tries compiled functions first:
+
+```javascript
+// In callDZQLOperation()
+try {
+  // Try compiled function: save_todos()
+  const result = await sql.unsafe(`SELECT save_todos($1, $2)`, [data, userId]);
+  return result[0].result;
+} catch (error) {
+  // If compiled function doesn't exist, fall back to interpreter
+  if (error.message.includes('save_todos') && error.code === '42883') {
+    return await sql`SELECT dzql.generic_exec('save', 'todos', ${data}, ${userId})`;
+  }
+  throw error;
+}
+```
+
+This means you can:
+1. Start with interpreter mode during development
+2. Compile and deploy when ready for production
+3. Mix and match - some entities compiled, others interpreted
+
+## Performance Comparison
+
+### Interpreter (Runtime Parsing)
+
+```sql
+SELECT dzql.generic_exec('save', 'venues', '{"name": "MSG"}'::jsonb, 42);
+```
+
+**Execution steps:**
+1. Fetch entity config from `dzql.entities` (table lookup)
+2. Parse `permission_paths` JSONB
+3. Build permission query dynamically
+4. Parse `graph_rules` JSONB
+5. Execute rules via dynamic SQL
+6. Parse `notification_paths` JSONB
+7. Resolve paths dynamically
+8. Execute the actual save
+
+**Cost:** ~8-12ms, 3-5 JSONB parses, unpredictable query plans
+
+### Compiler (Pre-built Functions)
+
+```sql
+SELECT save_venues('{"name": "MSG"}'::jsonb, 42);
+```
+
+**Execution steps:**
+1. Call `can_update_venues()` - pre-compiled permission check
+2. Execute INSERT/UPDATE - direct SQL
+3. Call `graph_venues_on_create()` - pre-compiled graph rules
+4. Call `resolve_notification_paths_venues()` - pre-compiled
+5. Done
+
+**Cost:** ~2-4ms, 0 JSONB parses, optimized query plans
+
+## When to Use Each
+
+### Use Interpreter When:
+- Rapid prototyping and development
+- Schema changes frequently
+- Learning DZQL concepts
+- Small applications with low traffic
+- Need maximum flexibility
+
+### Use Compiler When:
+- Production deployments
+- Performance is critical
+- Need predictable query performance
+- Want reviewable/auditable SQL
+- Large teams (generated SQL is easy to review)
+- Complex permission or graph rules
+
+### Recommended Workflow:
+1. **Development:** Use interpreter for fast iteration
+2. **Staging:** Compile and test performance
+3. **Production:** Deploy compiled functions
+
+## Compiling Entities
+
+### Via CLI
+
+```bash
+# Single file
+dzql compile database/entities.sql -o compiled/
+
+# Multiple files
+dzql compile database/*.sql -o compiled/
+```
+
+### Programmatically
+
+```javascript
+import { DZQLCompiler } from 'dzql/compiler';
+
+const compiler = new DZQLCompiler();
+const result = compiler.compileFromSQL(sqlContent);
+
+console.log(result.sql);  // Generated PostgreSQL functions
+```
+
+### What Gets Generated
+
+For each entity, the compiler generates:
+
+| Function | Purpose |
+|----------|---------|
+| `get_{entity}(id, user_id)` | Retrieve single record |
+| `save_{entity}(data, user_id)` | Create or update |
+| `delete_{entity}(id, user_id)` | Delete record |
+| `lookup_{entity}(term, user_id)` | Autocomplete search |
+| `search_{entity}(filters, user_id)` | Paginated search |
+| `can_view_{entity}(user_id, record)` | Permission check |
+| `can_create_{entity}(user_id, record)` | Permission check |
+| `can_update_{entity}(user_id, record)` | Permission check |
+| `can_delete_{entity}(user_id, record)` | Permission check |
+
+## Debugging
+
+### Interpreter Mode
+
+Debugging is harder because SQL is generated dynamically:
+
+```sql
+-- You see this
+EXPLAIN ANALYZE SELECT dzql.generic_exec('save', 'venues', '...');
+
+-- But the actual query is hidden inside
+```
+
+### Compiler Mode
+
+Standard PostgreSQL tools work:
+
+```sql
+-- See the actual function
+\sf save_venues
+
+-- Analyze performance
+EXPLAIN ANALYZE SELECT save_venues('{"name": "MSG"}'::jsonb, 42);
+
+-- Check slow queries
+SELECT * FROM pg_stat_statements WHERE query LIKE '%save_venues%';
+```
+
+## Feature Parity
+
+Both modes support the same features:
+
+| Feature | Interpreter | Compiler |
+|---------|-------------|----------|
+| CRUD operations | ✅ | ✅ |
+| Permission paths | ✅ | ✅ |
+| Graph rules | ✅ | ✅ |
+| Notification paths | ✅ | ✅ |
+| FK includes | ✅ | ✅ |
+| Many-to-many | ✅ | ✅ |
+| Field defaults | ✅ | ✅ |
+| Soft delete | ✅ | ✅ |
+| Temporal fields | ✅ | ✅ |
+
+The difference is purely in execution speed and debuggability, not functionality.
+
+## See Also
+
+- [Compiler Quickstart](../compiler/QUICKSTART.md) - Get started with compilation
+- [Compiler Comparison](../compiler/COMPARISON.md) - Detailed side-by-side analysis
+- [API Reference](../reference/api.md) - The 5 operations

package/docs/guides/many-to-many.md

@@ -161,6 +161,23 @@ SELECT dzql.register_entity(
 | `id_field` | Yes | Field name for ID array in API | `"tag_ids"` |
 | `expand` | No | Include full objects (default: false) | `false` or `true` |
 
+### Naming Convention for `id_field`
+
+**Important:** The `id_field` should use the **singular** form of the target entity, not plural:
+
+| Target Entity | Correct `id_field` | Wrong |
+|---------------|-------------------|-------|
+| `tags` | `tag_ids` | `tags_ids` |
+| `roles` | `role_ids` | `roles_ids` |
+| `categories` | `category_ids` | `categories_ids` |
+| `users` | `user_ids` | `users_ids` |
+
+This convention matches common ORM patterns and is more readable:
+- `tag_ids: [1, 2, 3]` reads as "tag IDs"
+- `tags_ids: [1, 2, 3]` reads awkwardly as "tags IDs"
+
+Using the wrong naming will cause the M2M sync to fail because the generated code looks for a field name that doesn't match what clients send.
+
 ### The `expand` Flag
 
 Controls whether full related objects are included in responses:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dzql",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "PostgreSQL-powered framework with zero boilerplate CRUD operations and real-time WebSocket synchronization",
   "type": "module",
   "main": "src/server/index.js",
@@ -24,7 +24,7 @@
   ],
   "scripts": {
     "test": "bun test ../../tests/core/*.test.js",
-    "prepublishOnly": "echo '✅ Publishing DZQL v0.3.5...'"
+    "prepublishOnly": "echo '✅ Publishing DZQL...'  "
   },
   "dependencies": {
     "jose": "^6.1.0",

package/src/compiler/codegen/graph-rules-codegen.js

@@ -39,24 +39,43 @@ export class GraphRulesCodegen {
     const operation = trigger.replace('on_', '');  // on_create -> create
     const functionName = `_graph_${this.tableName}_${trigger}`;
 
-    const actionBlocks = [];
+    const ruleBlocks = [];
 
     // Process each rule
     for (const [ruleName, ruleConfig] of Object.entries(rules)) {
       const description = ruleConfig.description || ruleName;
+      const condition = ruleConfig.condition;
       const actions = Array.isArray(ruleConfig.actions)
         ? ruleConfig.actions
         : (ruleConfig.actions ? [ruleConfig.actions] : []);
 
+      const actionBlocks = [];
       for (const action of actions) {
         const actionSQL = this._generateAction(action, ruleName, description);
         if (actionSQL) {
           actionBlocks.push(actionSQL);
         }
       }
+
+      if (actionBlocks.length === 0) {
+        continue;  // Skip rules with no actions
+      }
+
+      // Wrap actions in condition IF block if condition is present
+      if (condition) {
+        const conditionSQL = this._generateCondition(condition, operation);
+        const ruleBlock = `  -- Rule: ${ruleName}
+  IF ${conditionSQL} THEN
+${actionBlocks.join('\n\n')}
+  END IF;`;
+        ruleBlocks.push(ruleBlock);
+      } else {
+        // No condition - add actions directly
+        ruleBlocks.push(...actionBlocks);
+      }
     }
 
-    if (actionBlocks.length === 0) {
+    if (ruleBlocks.length === 0) {
       return null;  // No actions, no function
     }
 
@@ -72,7 +91,7 @@ CREATE OR REPLACE FUNCTION ${functionName}(
   ${params}
 ) RETURNS VOID AS $$
 BEGIN
-${actionBlocks.join('\n\n')}
+${ruleBlocks.join('\n\n')}
 END;
 $$ LANGUAGE plpgsql SECURITY DEFINER;`;
   }
@@ -100,6 +119,9 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
       case 'execute':
         return this._generateExecuteAction(action, comment);
 
+      case 'notify':
+        return this._generateNotifyAction(action, comment);
+
       default:
         console.warn('Unknown action type:', action.type);
         return null;
@@ -211,6 +233,140 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
   PERFORM ${functionName}(${paramSQL});`;
   }
 
+  /**
+   * Generate NOTIFY action
+   * Creates an event that will be broadcast to specified users
+   * @private
+   */
+  _generateNotifyAction(action, comment) {
+    const users = action.users || [];
+    const message = action.message || '';
+    const data = action.data || {};
+
+    // Build user ID array resolution
+    let userIdSQL = 'ARRAY[]::INT[]';
+
+    if (users.length > 0) {
+      // Users can be paths like "@post_id->posts.author_id" or direct field refs like "@author_id"
+      const userPaths = [];
+
+      for (const userPath of users) {
+        if (userPath.startsWith('@') && !userPath.includes('->')) {
+          // Simple field reference: @author_id
+          const fieldName = userPath.substring(1);
+          userPaths.push(`(p_record->>'${fieldName}')::int`);
+        } else if (userPath.startsWith('@') && userPath.includes('->')) {
+          // Complex path: @post_id->posts.author_id - use runtime resolver
+          userPaths.push(`dzql.resolve_notification_path('${this.tableName}', p_record, '${userPath}')`);
+        } else {
+          // Literal user ID
+          userPaths.push(`${userPath}`);
+        }
+      }
+
+      if (userPaths.length === 1 && !userPaths[0].includes('resolve_notification_path')) {
+        // Single simple field - wrap in array
+        userIdSQL = `ARRAY[${userPaths[0]}]`;
+      } else if (userPaths.length === 1) {
+        // Single path resolution (already returns array)
+        userIdSQL = userPaths[0];
+      } else {
+        // Multiple paths - need to combine arrays
+        userIdSQL = `(${userPaths.map(p =>
+          p.includes('resolve_notification_path')
+            ? p
+            : `ARRAY[${p}]`
+        ).join(' || ')})`;
+      }
+    }
+
+    // Build notification data object
+    const dataFields = [];
+    dataFields.push(`'type', 'graph_rule_notification'`);
+    dataFields.push(`'table', '${this.tableName}'`);
+
+    if (message) {
+      dataFields.push(`'message', ${this._resolveValue(message)}`);
+    }
+
+    // Add custom data fields
+    for (const [key, value] of Object.entries(data)) {
+      dataFields.push(`'${key}', ${this._resolveValue(value)}`);
+    }
+
+    const dataSQL = dataFields.length > 0
+      ? `jsonb_build_object(${dataFields.join(', ')})`
+      : "'{}'::jsonb";
+
+    return `${comment}
+  -- Create notification event
+  INSERT INTO dzql.events (
+    table_name,
+    op,
+    pk,
+    data,
+    user_id,
+    notify_users
+  ) VALUES (
+    '${this.tableName}',
+    'notify',
+    jsonb_build_object('id', (p_record->>'id')::int),
+    ${dataSQL},
+    p_user_id,
+    ${userIdSQL}
+  );`;
+  }
+
+  /**
+   * Generate condition SQL from condition string
+   * Supports @before.field, @after.field, @user_id, @id
+   * @private
+   */
+  _generateCondition(condition, operation) {
+    let conditionSQL = condition;
+
+    // Replace @before.field references (for update/delete)
+    conditionSQL = conditionSQL.replace(/@before\.(\w+)/g, (match, field) => {
+      return `(p_old_record->>'${field}')`;
+    });
+
+    // Replace @after.field references (for update)
+    conditionSQL = conditionSQL.replace(/@after\.(\w+)/g, (match, field) => {
+      if (operation === 'update') {
+        return `(p_new_record->>'${field}')`;
+      } else {
+        return `(p_record->>'${field}')`;
+      }
+    });
+
+    // Replace @field references (current record)
+    conditionSQL = conditionSQL.replace(/@(\w+)(?!\w)/g, (match, field) => {
+      if (field === 'user_id') {
+        return 'p_user_id';
+      } else if (field === 'id') {
+        // Use appropriate record based on operation
+        if (operation === 'update') {
+          return `(p_new_record->>'id')`;
+        } else if (operation === 'delete') {
+          return `(p_old_record->>'id')`;
+        } else {
+          return `(p_record->>'id')`;
+        }
+      } else {
+        // Field from current record
+        if (operation === 'update') {
+          return `(p_new_record->>'${field}')`;
+        } else if (operation === 'delete') {
+          return `(p_old_record->>'${field}')`;
+        } else {
+          return `(p_record->>'${field}')`;
+        }
+      }
+    });
+
+    return conditionSQL;
+  }
+
   /**
    * Resolve a value (variable reference or literal)
    * @private

package/src/compiler/codegen/operation-codegen.js

@@ -729,10 +729,11 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
   }
 
   /**
-   * Resolve a variable default (@user_id, @now, @today) to SQL expression
+   * Resolve a variable default (@user_id, @now, @today, @field_name) to SQL expression
    * @private
    */
   _resolveDefaultVariable(variable, fieldName) {
+    // Handle built-in variables
     switch (variable) {
       case '@user_id':
         return 'p_user_id';
@@ -740,9 +741,16 @@ $$ LANGUAGE plpgsql SECURITY DEFINER;`;
         return `to_char(NOW(), 'YYYY-MM-DD"T"HH24:MI:SS.MS"Z"')`;
       case '@today':
         return `to_char(CURRENT_DATE, 'YYYY-MM-DD')`;
-      default:
-        throw new Error(`Unknown field default variable: ${variable} for field ${fieldName}`);
     }
+
+    // Handle field references: @other_field
+    if (variable.startsWith('@')) {
+      const referencedField = variable.substring(1);
+      // Reference to another field in the data being inserted
+      return `(p_data->>'${referencedField}')`;
+    }
+
+    throw new Error(`Unknown field default variable: ${variable} for field ${fieldName}`);
   }
 
   /**

package/src/compiler/codegen/permission-codegen.js

@@ -228,7 +228,11 @@ $$ LANGUAGE plpgsql STABLE SECURITY DEFINER;`;
 
     // Add temporal condition
     if (temporal) {
-      conditions.push(`${targetTable}.valid_to IS NULL`);
+      // Add temporal filtering for {active} marker
+      // Assumes standard field names: valid_from and valid_to
+      // This matches the interpreter's behavior in resolve_path_segment (002_functions.sql:316)
+      conditions.push(`${targetTable}.valid_from <= NOW()`);
+      conditions.push(`(${targetTable}.valid_to > NOW() OR ${targetTable}.valid_to IS NULL)`);
     }
 
     // Add user_id check (final target)

package/src/server/db.js

@@ -224,8 +224,13 @@ export async function callDZQLOperation(operation, entity, args, userId) {
       throw new Error(`Unknown operation: ${operation}`);
     }
   } catch (error) {
-    // If compiled function doesn't exist, fall back to generic_exec
-    if (error.message?.includes('does not exist') || error.code === '42883') {
+    // Only fall back if the COMPILED function itself doesn't exist
+    // Don't fall back for other "does not exist" errors (e.g., missing tables, downstream functions)
+    const isMissingCompiledFunction =
+      (error.message?.includes('does not exist') || error.code === '42883') &&
+      error.message?.includes(compiledFunctionName);
+
+    if (isMissingCompiledFunction) {
       dbLogger.trace(`Compiled function ${compiledFunctionName} not found, trying generic_exec`);
       const result = await sql`
         SELECT dzql.generic_exec(${operation}, ${entity}, ${args}, ${userId}) as result

package/src/server/index.js

@@ -31,12 +31,12 @@ async function processSubscriptionUpdates(event, broadcast) {
   for (const [subscribableName, subs] of subscriptionsByName.entries()) {
     try {
       // Ask PostgreSQL which subscription instances are affected
-      const result = await db.query(
+      const result = await sql.unsafe(
         `SELECT ${subscribableName}_affected_documents($1, $2, $3, $4) as affected`,
         [table, op, before, after]
       );
 
-      const affectedParamSets = result.rows[0]?.affected;
+      const affectedParamSets = result[0]?.affected;
 
       if (!affectedParamSets || affectedParamSets.length === 0) {
         continue; // This subscribable not affected
@@ -51,12 +51,12 @@ async function processSubscriptionUpdates(event, broadcast) {
           if (paramsMatch(sub.params, affectedParams)) {
             try {
               // Re-execute query to get updated data
-              const updated = await db.query(
+              const updated = await sql.unsafe(
                 `SELECT get_${subscribableName}($1, $2) as data`,
                 [sub.params, sub.user_id]
               );
 
-              const data = updated.rows[0]?.data;
+              const data = updated[0]?.data;
 
               // Send update to specific connection
               const message = JSON.stringify({

package/src/server/ws.js

@@ -4,6 +4,7 @@ import {
   callUserFunction,
   getUserProfile,
   db,
+  sql,
 } from "./db.js";
 import { wsLogger, authLogger } from "./logger.js";
 import {
@@ -317,12 +318,12 @@ export function createRPCHandler(customHandlers = {}) {
 
         try {
           // Execute initial query (this also checks permissions)
-          const queryResult = await db.query(
+          const queryResult = await sql.unsafe(
             `SELECT get_${subscribableName}($1, $2) as data`,
             [params, ws.data.user_id]
           );
 
-          const data = queryResult.rows[0]?.data;
+          const data = queryResult[0]?.data;
 
           // Register subscription in memory
           const subscriptionId = registerSubscription(

package/src/client/stores/README.md

@@ -1,95 +0,0 @@
-# DZQL Canonical Pinia Stores
-
-**The official, AI-friendly Pinia stores for DZQL Vue.js applications.**
-
-## Why These Stores Exist
-
-When building DZQL apps, developers (and AI assistants) often struggle with:
-
-1. **Three-phase lifecycle** - connecting → login → ready
-2. **WebSocket connection management** - reconnection, error handling
-3. **Authentication flow** - token storage, profile management  
-4. **Router integration** - navigation, state synchronization
-5. **Inconsistent patterns** - every project does it differently
-
-These canonical stores solve all of these problems with a **simple, consistent pattern** that AI can easily understand and replicate.
-
-## The Stores
-
-### `useWsStore` - WebSocket & Auth
-
-Manages:
-- WebSocket connection (with auto-reconnect)
-- User authentication (login/register/logout)
-- Connection state tracking
-- Three-phase app lifecycle
-
-### `useAppStore` - Application State
-
-Manages:
-- App initialization
-- Router integration
-- Entity metadata caching
-- Navigation helpers
-- UI state (sidebars, panels)
-
-## Quick Example
-
-```vue
-<script setup>
-import { computed } from 'vue'
-import { useWsStore, useAppStore } from 'dzql/client/stores'
-
-const wsStore = useWsStore()
-const appStore = useAppStore()
-
-const state = computed(() => wsStore.appState)
-const ws = wsStore.getWs()
-
-// Use DZQL API
-const venues = await ws.api.search.venues({ limit: 50 })
-</script>
-
-<template>
-  <!-- Three-phase lifecycle -->
-  <div v-if="state === 'connecting'">Connecting...</div>
-  <LoginView v-else-if="state === 'login'" />
-  <MainApp v-else-if="state === 'ready'" />
-</template>
-```
-
-## Documentation
-
-- **[Quick Start](../../../docs/reference/client.md)** - Get running in 5 minutes
-- **[Complete Guide](../../../docs/guides/client-stores.md)** - Full API reference and patterns
-
-## Files
-
-- `useWsStore.js` - WebSocket connection and authentication
-- `useAppStore.js` - Application state and navigation
-- `index.js` - Exports both stores
-
-## For AI Assistants
-
-When helping users with DZQL apps:
-
-1. **Always use these stores** - Don't create custom connection logic
-2. **Follow the three-phase lifecycle** - connecting → login → ready
-3. **Use computed for reactive state** - `const profile = computed(() => wsStore.profile)`
-4. **Get WS instance for API calls** - `const ws = wsStore.getWs()`
-
-**Example prompt for AI:**
-
-> "I'm using the canonical DZQL stores from `dzql/client/stores`. The pattern is:
-> 1. useWsStore for WebSocket connection (three phases: connecting, login, ready)
-> 2. useAppStore for app state and navigation
-> 3. Access DZQL API via `wsStore.getWs().api.get.venues({ id: 1 })`
-> Please follow this pattern."
-
-## Version
-
-These stores are available in DZQL v0.1.6+
-
-## License
-
-MIT