dzql 0.5.6 → 0.5.7

package/docs/guides/atomic-updates.md

@@ -0,0 +1,242 @@
+# Atomic Updates for Subscribables
+
+Atomic updates enable efficient real-time synchronization by sending only the changes (insert/update/delete) to subscribed clients, instead of re-querying and sending the entire document on every change.
+
+## Overview
+
+### Problem Solved
+
+Previously, when any data changed that affected a subscription, the server would:
+1. Re-query the entire document using `get_<subscribable>()`
+2. Send the complete document to the client
+3. Client replaces its entire local state
+
+This approach has several problems:
+- **Network inefficiency**: Sends full product catalogue when one task template duration changes
+- **Database load**: Re-executes complex queries on every tiny change
+- **Client state loss**: Replaces entire local state, losing UI state (scroll position, expanded rows, etc.)
+
+### Solution: Atomic Updates
+
+With atomic updates, the server:
+1. Forwards the raw event (table, operation, primary key, data) directly to clients
+2. Client applies the patch to their local copy of the document
+3. Only changed data traverses the network
+
+Benefits:
+- **Efficient**: O(change size) instead of O(document size) per update
+- **Preserved state**: Client UI state remains intact
+- **Reduced database load**: No re-querying on every change
+
+## How It Works
+
+### 1. Subscribe: Initial Data + Schema
+
+When a client subscribes, they receive:
+- The full initial document (unchanged)
+- A **schema** that maps table names to document paths
+
+```javascript
+const { data, schema, unsubscribe } = await ws.api.subscribe_venue_detail(
+  { venue_id: 1 },
+  (updated) => console.log('Updated:', updated)
+);
+
+// schema = {
+//   root: 'venues',
+//   paths: {
+//     'venues': '.',           // Root entity
+//     'organisations': 'org',  // FK expansion
+//     'sites': 'sites',        // Child collection
+//     'packages': 'packages'   // Child collection
+//   }
+// }
+```
+
+### 2. On Changes: Atomic Events
+
+When data changes, instead of re-querying, the server sends a `subscription:event` message:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "subscription:event",
+  "params": {
+    "subscription_id": "550e8400-e29b-41d4-a716-446655440000",
+    "subscribable": "venue_detail",
+    "event": {
+      "table": "sites",
+      "op": "update",
+      "pk": { "id": 5 },
+      "data": { "id": 5, "name": "Updated Site Name", "venue_id": 1 },
+      "before": { "id": 5, "name": "Old Name", "venue_id": 1 }
+    }
+  }
+}
+```
+
+### 3. Client: Apply Patch
+
+The client uses the schema to locate where the change belongs in the document and applies it:
+
+- **insert**: Adds new item to the appropriate array
+- **update**: Finds item by primary key and merges changes
+- **delete**: Finds item by primary key and removes it
+
+The callback receives the updated local document, preserving any UI state.
+
+## Scope Tables
+
+Each subscribable tracks which tables are "in scope" - tables that can affect the document:
+
+```sql
+SELECT scope_tables FROM dzql.subscribables WHERE name = 'venue_detail';
+-- Returns: ['venues', 'organisations', 'sites', 'packages']
+```
+
+This enables an optimization: events from tables not in scope are immediately skipped, avoiding unnecessary `_affected_documents()` calls.
+
+### Automatic Extraction
+
+Scope tables are automatically extracted when registering a subscribable:
+
+```sql
+SELECT dzql.register_subscribable(
+  'venue_detail',
+  '{"subscribe": [...]}'::jsonb,
+  '{"venue_id": "int"}'::jsonb,
+  'venues',                          -- root_entity -> scope includes 'venues'
+  '{
+    "org": "organisations",          -- scope includes 'organisations'
+    "sites": {"entity": "sites", ...} -- scope includes 'sites'
+  }'::jsonb
+);
+
+-- scope_tables automatically set to: ['venues', 'organisations', 'sites']
+```
+
+## Path Mapping
+
+The path mapping tells the client where each table's data lives in the document structure:
+
+| Table | Path | Meaning |
+|-------|------|---------|
+| `venues` | `.` | Root level |
+| `organisations` | `org` | `document.org` |
+| `sites` | `sites` | `document.sites[]` |
+| `allocations` | `packages.allocations` | `document.packages[].allocations[]` |
+
+### Nested Relations
+
+For nested relations, paths are dot-separated:
+
+```javascript
+relations = {
+  packages: {
+    entity: 'packages',
+    filter: 'venue_id=$venue_id',
+    include: {
+      allocations: 'allocations'
+    }
+  }
+}
+
+// Results in paths:
+// 'packages' -> 'packages'
+// 'allocations' -> 'packages.allocations'
+```
+
+## Client-Side Patching
+
+The `WebSocketManager` automatically handles `subscription:event` messages:
+
+```javascript
+// Internally, when subscription:event is received:
+applyAtomicUpdate(sub, event) {
+  const { table, op, pk, data } = event;
+  const path = sub.schema.paths[table];
+  
+  if (path === '.') {
+    // Root entity update
+    Object.assign(sub.localData[sub.schema.root], data);
+  } else {
+    // Relation update
+    const arr = getArrayAtPath(sub.localData, path);
+    if (op === 'insert') arr.push(data);
+    if (op === 'update') {
+      const idx = arr.findIndex(item => pkMatch(item, pk));
+      if (idx !== -1) Object.assign(arr[idx], data);
+    }
+    if (op === 'delete') {
+      const idx = arr.findIndex(item => pkMatch(item, pk));
+      if (idx !== -1) arr.splice(idx, 1);
+    }
+  }
+  
+  // Trigger callback with patched document
+  sub.callback(sub.localData);
+}
+```
+
+## Composite Primary Keys
+
+Atomic updates support composite primary keys:
+
+```json
+{
+  "pk": { "product_id": 1, "part_id": 2 }
+}
+```
+
+The client matches all key fields when finding items to update or delete.
+
+## Migration from Full Re-queries
+
+If you have existing subscribables, atomic updates are enabled automatically when:
+1. The `scope_tables` column is populated (happens on `register_subscribable`)
+2. The client receives the `schema` in the subscribe response
+
+No code changes required - the system is backward compatible.
+
+## Debugging
+
+### Check Scope Tables
+
+```sql
+SELECT name, scope_tables 
+FROM dzql.subscribables 
+WHERE name = 'your_subscribable';
+```
+
+### Verify Path Mapping
+
+Subscribe and log the schema:
+
+```javascript
+const { schema } = await ws.api.subscribe_venue_detail(
+  { venue_id: 1 },
+  () => {}
+);
+console.log('Path mapping:', schema.paths);
+```
+
+### Server Logs
+
+Enable debug logging to see atomic events:
+
+```
+Sent atomic event to subscription abc123... (sites:update)
+```
+
+## Limitations
+
+1. **Deeply nested updates**: For very deep nesting (3+ levels), paths become complex. Consider flattening your subscribable structure.
+
+2. **Cascading deletes**: When a parent is deleted, the client may receive the parent delete before child deletes. The client handles missing parents gracefully.
+
+3. **Permission changes**: If a user loses access mid-subscription, they may receive one final event before the subscription is terminated.
+
+## See Also
+
+- [Subscriptions Guide](./subscriptions.md) - Full subscribable documentation
+- [Getting Started with Subscriptions](../getting-started/subscriptions-quick-start.md)

package/docs/guides/subscriptions.md

@@ -19,7 +19,9 @@ Live Query Subscriptions (Pattern 1 from vision.md) enable clients to subscribe
    - `get_<name>(params, user_id)` - Query function
    - `<name>_affected_documents(table, op, old, new)` - Change detection
 3. **Subscribe**: Client calls `ws.api.subscribe_<name>(params, callback)`
-4. **Update**: Database changes trigger NOTIFY → server asks PostgreSQL which subscriptions are affected → server re-queries and sends updates
+4. **Update**: Database changes trigger NOTIFY → server forwards atomic events → client applies patches locally
+
+> **Note**: DZQL uses [Atomic Updates](./atomic-updates.md) for efficient real-time sync. Instead of re-querying the full document on every change, the server forwards the raw event and the client patches its local copy. This reduces network traffic and preserves client-side UI state.
 
 ## Quick Start
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dzql",
-  "version": "0.5.6",
+  "version": "0.5.7",
   "description": "PostgreSQL-powered framework with zero boilerplate CRUD operations and real-time WebSocket synchronization",
   "type": "module",
   "main": "src/server/index.js",

package/src/client/ws.js

@@ -334,16 +334,28 @@ class WebSocketManager {
         resolve(message.result);
       }
     } else {
-      // Handle subscription updates
+      // Handle subscription updates (legacy full document replacement)
       if (message.method === "subscription:update") {
         const { subscription_id, data } = message.params;
         const sub = this.subscriptions.get(subscription_id);
         if (sub && sub.callback) {
+          // Update local data and call callback
+          sub.localData = data;
           sub.callback(data);
         }
         return;
       }
 
+      // Handle atomic subscription events (new efficient patching)
+      if (message.method === "subscription:event") {
+        const { subscription_id, event } = message.params;
+        const sub = this.subscriptions.get(subscription_id);
+        if (sub) {
+          this.applyAtomicUpdate(sub, event);
+        }
+        return;
+      }
+
       // Handle broadcasts and SID requests
 
       // Check if this is a SID request from server
@@ -361,6 +373,117 @@ class WebSocketManager {
     }
   }
 
+  /**
+   * Apply an atomic update to a subscription's local data
+   * @private
+   * @param {Object} sub - Subscription object with localData, schema, callback
+   * @param {Object} event - Event with table, op, pk, data, before
+   */
+  applyAtomicUpdate(sub, event) {
+    const { table, op, pk, data, before } = event;
+    const { schema, localData, callback } = sub;
+
+    // Fallback: if no schema or localData, we can't apply atomic updates
+    if (!schema || !localData) {
+      console.warn('Cannot apply atomic update: missing schema or localData');
+      // If we have data, just call callback with it as a fallback
+      if (data) {
+        callback(data);
+      }
+      return;
+    }
+
+    const path = schema.paths?.[table];
+    if (!path) {
+      console.warn(`Unknown table ${table} for subscribable, cannot apply patch`);
+      return;
+    }
+
+    // Apply the update based on where the table lives in the document
+    if (path === '.' || table === schema.root) {
+      // Root entity changed
+      this.applyRootUpdate(localData, schema.root, op, data, before);
+    } else {
+      // Relation changed - find and update in nested structure
+      this.applyRelationUpdate(localData, path, op, pk, data);
+    }
+
+    // Trigger callback with updated document
+    callback(localData);
+  }
+
+  /**
+   * Apply update to root entity
+   * @private
+   */
+  applyRootUpdate(localData, rootKey, op, data, before) {
+    if (op === 'update' && data) {
+      // Merge update into root entity
+      if (localData[rootKey]) {
+        Object.assign(localData[rootKey], data);
+      }
+    } else if (op === 'delete') {
+      // Mark root as deleted (or set to null)
+      localData[rootKey] = null;
+    }
+    // insert at root level would be a new document, handled by initial subscribe
+  }
+
+  /**
+   * Apply update to a relation (nested array)
+   * @private
+   */
+  applyRelationUpdate(localData, path, op, pk, data) {
+    const arr = this.getArrayAtPath(localData, path);
+    if (!arr || !Array.isArray(arr)) {
+      console.warn(`Could not find array at path ${path}`);
+      return;
+    }
+
+    if (op === 'insert' && data) {
+      arr.push(data);
+    } else if (op === 'update' && data && pk) {
+      const idx = arr.findIndex(item => this.pkMatch(item, pk));
+      if (idx !== -1) {
+        Object.assign(arr[idx], data);
+      } else {
+        // Item not found, might be a new item that passes the filter - add it
+        arr.push(data);
+      }
+    } else if (op === 'delete' && pk) {
+      const idx = arr.findIndex(item => this.pkMatch(item, pk));
+      if (idx !== -1) {
+        arr.splice(idx, 1);
+      }
+    }
+  }
+
+  /**
+   * Get array at a dot-separated path in an object
+   * @private
+   */
+  getArrayAtPath(obj, path) {
+    const parts = path.split('.');
+    let current = obj;
+    for (const part of parts) {
+      if (!current || typeof current !== 'object') return null;
+      current = current[part];
+    }
+    return current;
+  }
+
+  /**
+   * Check if an item matches a primary key
+   * @private
+   */
+  pkMatch(item, pk) {
+    if (!item || !pk) return false;
+    for (const [key, value] of Object.entries(pk)) {
+      if (item[key] !== value) return false;
+    }
+    return true;
+  }
+
   attemptReconnect() {
     if (this.reconnectAttempts < this.maxReconnectAttempts) {
       this.reconnectAttempts++;
@@ -409,19 +532,23 @@ class WebSocketManager {
   /**
    * Subscribe to a live query
    *
+   * Subscribes to real-time updates for a document. The server returns the initial
+   * data along with a schema that enables efficient atomic updates (patching).
+   *
    * @param {string} method - Method name (subscribe_<subscribable>)
    * @param {object} params - Subscription parameters
    * @param {function} callback - Callback function for updates
-   * @returns {Promise<{data, subscription_id, unsubscribe}>} Initial data and unsubscribe function
+   * @returns {Promise<{data, subscription_id, schema, unsubscribe}>} Initial data, schema, and unsubscribe function
    *
    * @example
-   * const { data, unsubscribe } = await ws.api.subscribe_venue_detail(
+   * const { data, schema, unsubscribe } = await ws.api.subscribe_venue_detail(
    *   { venue_id: 1 },
    *   (updated) => console.log('Updated:', updated)
    * );
    *
    * // Use initial data
    * console.log('Initial:', data);
+   * console.log('Schema:', schema); // { root: 'venues', paths: { venues: '.', sites: 'sites', ... } }
    *
    * // Later: unsubscribe
    * unsubscribe();
@@ -433,7 +560,7 @@ class WebSocketManager {
 
     // Call server to register subscription
     const result = await this.call(method, params);
-    const { subscription_id, data } = result;
+    const { subscription_id, data, schema } = result;
 
     // Create unsubscribe function
     const unsubscribeFn = async () => {
@@ -442,16 +569,19 @@ class WebSocketManager {
       this.subscriptions.delete(subscription_id);
     };
 
-    // Store callback for updates
+    // Store callback, schema, and local data for atomic updates
     this.subscriptions.set(subscription_id, {
       callback,
-      unsubscribe: unsubscribeFn
+      unsubscribe: unsubscribeFn,
+      schema,           // Schema for path mapping (enables atomic updates)
+      localData: data   // Local copy for patching
     });
 
-    // Return initial data and unsubscribe function
+    // Return initial data, schema, and unsubscribe function
     return {
       data,
       subscription_id,
+      schema,
       unsubscribe: unsubscribeFn
     };
   }

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

@@ -433,6 +433,71 @@ $$ LANGUAGE plpgsql IMMUTABLE;`;
         jsonb_build_object('${firstParam}', COALESCE((p_new->>'${relFK}')::int, (p_old->>'${relFK}')::int))
       ];`;
   }
+
+  /**
+   * Extract all tables in scope for this subscribable
+   * Used for efficient event filtering - only events from these tables need consideration
+   * @returns {string[]} Array of table names
+   */
+  extractScopeTables() {
+    const tables = new Set([this.rootEntity]);
+
+    const extractFromRelations = (relations) => {
+      for (const [relName, relConfig] of Object.entries(relations || {})) {
+        const entity = typeof relConfig === 'string' ? relConfig : relConfig.entity;
+        if (entity) tables.add(entity);
+
+        // Handle nested relations (include or relations)
+        if (typeof relConfig === 'object') {
+          if (relConfig.include) {
+            extractFromRelations(relConfig.include);
+          }
+          if (relConfig.relations) {
+            extractFromRelations(relConfig.relations);
+          }
+        }
+      }
+    };
+
+    extractFromRelations(this.relations);
+    return Array.from(tables);
+  }
+
+  /**
+   * Build path mapping for client-side patching
+   * Maps table names to their path in the document structure
+   * @returns {Object} Map of table name -> document path
+   */
+  buildPathMapping() {
+    const paths = {};
+
+    // Root entity maps to top level
+    paths[this.rootEntity] = '.';
+
+    const buildPaths = (relations, parentPath = '') => {
+      for (const [relName, relConfig] of Object.entries(relations || {})) {
+        const entity = typeof relConfig === 'string' ? relConfig : relConfig.entity;
+        const currentPath = parentPath ? `${parentPath}.${relName}` : relName;
+
+        if (entity) {
+          paths[entity] = currentPath;
+        }
+
+        // Handle nested relations
+        if (typeof relConfig === 'object') {
+          if (relConfig.include) {
+            buildPaths(relConfig.include, currentPath);
+          }
+          if (relConfig.relations) {
+            buildPaths(relConfig.relations, currentPath);
+          }
+        }
+      }
+    };
+
+    buildPaths(this.relations);
+    return paths;
+  }
 }
 
 /**
@@ -444,3 +509,23 @@ export function generateSubscribable(subscribable) {
   const codegen = new SubscribableCodegen(subscribable);
   return codegen.generate();
 }
+
+/**
+ * Extract scope tables from subscribable config
+ * @param {Object} subscribable - Subscribable configuration
+ * @returns {string[]} Array of table names in scope
+ */
+export function extractScopeTables(subscribable) {
+  const codegen = new SubscribableCodegen(subscribable);
+  return codegen.extractScopeTables();
+}
+
+/**
+ * Build path mapping from subscribable config
+ * @param {Object} subscribable - Subscribable configuration
+ * @returns {Object} Map of table name -> document path
+ */
+export function buildPathMapping(subscribable) {
+  const codegen = new SubscribableCodegen(subscribable);
+  return codegen.buildPathMapping();
+}

package/src/database/migrations/009_subscriptions.sql

@@ -13,6 +13,7 @@ CREATE TABLE IF NOT EXISTS dzql.subscribables (
   param_schema JSONB NOT NULL DEFAULT '{}'::jsonb,
   root_entity TEXT NOT NULL,
   relations JSONB NOT NULL DEFAULT '{}'::jsonb,
+  scope_tables TEXT[] NOT NULL DEFAULT '{}',
   created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
   updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
 );
@@ -35,6 +36,9 @@ COMMENT ON COLUMN dzql.subscribables.root_entity IS
 COMMENT ON COLUMN dzql.subscribables.relations IS
   'Related entities to include (e.g., {"org": "organisations", "sites": {"entity": "sites", "filter": "venue_id=$venue_id"}})';
 
+COMMENT ON COLUMN dzql.subscribables.scope_tables IS
+  'Array of table names that are in scope for this subscribable (root + all relations). Used for efficient event filtering.';
+
 -- Index for quick lookups
 CREATE INDEX IF NOT EXISTS idx_subscribables_root_entity
   ON dzql.subscribables(root_entity);
@@ -110,6 +114,7 @@ RETURNS TABLE (
   param_schema JSONB,
   root_entity TEXT,
   relations JSONB,
+  scope_tables TEXT[],
   created_at TIMESTAMPTZ,
   updated_at TIMESTAMPTZ
 ) AS $$
@@ -121,6 +126,7 @@ BEGIN
     s.param_schema,
     s.root_entity,
     s.relations,
+    s.scope_tables,
     s.created_at,
     s.updated_at
   FROM dzql.subscribables s
@@ -139,6 +145,7 @@ RETURNS TABLE (
   param_schema JSONB,
   root_entity TEXT,
   relations JSONB,
+  scope_tables TEXT[],
   created_at TIMESTAMPTZ,
   updated_at TIMESTAMPTZ
 ) AS $$
@@ -150,6 +157,7 @@ BEGIN
     s.param_schema,
     s.root_entity,
     s.relations,
+    s.scope_tables,
     s.created_at,
     s.updated_at
   FROM dzql.subscribables s
@@ -168,6 +176,7 @@ RETURNS TABLE (
   param_schema JSONB,
   root_entity TEXT,
   relations JSONB,
+  scope_tables TEXT[],
   created_at TIMESTAMPTZ,
   updated_at TIMESTAMPTZ
 ) AS $$
@@ -179,6 +188,7 @@ BEGIN
     s.param_schema,
     s.root_entity,
     s.relations,
+    s.scope_tables,
     s.created_at,
     s.updated_at
   FROM dzql.subscribables s

package/src/database/migrations/010_atomic_updates.sql

@@ -0,0 +1,150 @@
+-- Migration 010: Atomic Updates for Subscribables
+-- Adds extract_scope_tables function and updates register_subscribable to auto-populate scope_tables
+
+-- ============================================================================
+-- Helper function to extract scope tables from relations
+-- ============================================================================
+
+CREATE OR REPLACE FUNCTION dzql.extract_scope_tables(
+  p_root_entity TEXT,
+  p_relations JSONB
+) RETURNS TEXT[] AS $$
+DECLARE
+  v_tables TEXT[];
+  v_key TEXT;
+  v_value JSONB;
+  v_entity TEXT;
+  v_nested JSONB;
+BEGIN
+  -- Start with root entity
+  v_tables := ARRAY[p_root_entity];
+
+  -- Return early if no relations
+  IF p_relations IS NULL OR p_relations = '{}'::jsonb THEN
+    RETURN v_tables;
+  END IF;
+
+  -- Iterate through relations
+  FOR v_key, v_value IN SELECT * FROM jsonb_each(p_relations)
+  LOOP
+    -- Handle string relation (simple FK expansion): "org": "organisations"
+    IF jsonb_typeof(v_value) = 'string' THEN
+      v_entity := v_value #>> '{}';
+      IF v_entity IS NOT NULL AND v_entity != '' THEN
+        v_tables := array_append(v_tables, v_entity);
+      END IF;
+    -- Handle object relation: {"entity": "sites", "filter": "..."}
+    ELSIF jsonb_typeof(v_value) = 'object' THEN
+      v_entity := v_value ->> 'entity';
+      IF v_entity IS NOT NULL AND v_entity != '' THEN
+        v_tables := array_append(v_tables, v_entity);
+      END IF;
+
+      -- Recursively handle nested relations (include or relations)
+      v_nested := v_value -> 'include';
+      IF v_nested IS NOT NULL AND jsonb_typeof(v_nested) = 'object' THEN
+        v_tables := v_tables || dzql.extract_scope_tables(NULL, v_nested);
+      END IF;
+
+      v_nested := v_value -> 'relations';
+      IF v_nested IS NOT NULL AND jsonb_typeof(v_nested) = 'object' THEN
+        v_tables := v_tables || dzql.extract_scope_tables(NULL, v_nested);
+      END IF;
+    END IF;
+  END LOOP;
+
+  -- Remove duplicates and nulls
+  SELECT array_agg(DISTINCT t) INTO v_tables
+  FROM unnest(v_tables) t
+  WHERE t IS NOT NULL;
+
+  RETURN COALESCE(v_tables, ARRAY[]::TEXT[]);
+END;
+$$ LANGUAGE plpgsql IMMUTABLE;
+
+COMMENT ON FUNCTION dzql.extract_scope_tables IS
+  'Extract all table names from a subscribable definition (root entity + all relations recursively)';
+
+-- ============================================================================
+-- Update register_subscribable to auto-populate scope_tables
+-- ============================================================================
+
+CREATE OR REPLACE FUNCTION dzql.register_subscribable(
+  p_name TEXT,
+  p_permission_paths JSONB,
+  p_param_schema JSONB,
+  p_root_entity TEXT,
+  p_relations JSONB
+) RETURNS TEXT AS $$
+DECLARE
+  v_result TEXT;
+  v_scope_tables TEXT[];
+BEGIN
+  -- Validate inputs
+  IF p_name IS NULL OR p_name = '' THEN
+    RAISE EXCEPTION 'Subscribable name cannot be empty';
+  END IF;
+
+  IF p_root_entity IS NULL OR p_root_entity = '' THEN
+    RAISE EXCEPTION 'Root entity cannot be empty';
+  END IF;
+
+  -- Extract scope tables from root entity and relations
+  v_scope_tables := dzql.extract_scope_tables(p_root_entity, p_relations);
+
+  -- Insert or update subscribable
+  INSERT INTO dzql.subscribables (
+    name,
+    permission_paths,
+    param_schema,
+    root_entity,
+    relations,
+    scope_tables,
+    created_at,
+    updated_at
+  ) VALUES (
+    p_name,
+    COALESCE(p_permission_paths, '{}'::jsonb),
+    COALESCE(p_param_schema, '{}'::jsonb),
+    p_root_entity,
+    COALESCE(p_relations, '{}'::jsonb),
+    v_scope_tables,
+    NOW(),
+    NOW()
+  )
+  ON CONFLICT (name) DO UPDATE SET
+    permission_paths = EXCLUDED.permission_paths,
+    param_schema = EXCLUDED.param_schema,
+    root_entity = EXCLUDED.root_entity,
+    relations = EXCLUDED.relations,
+    scope_tables = EXCLUDED.scope_tables,
+    updated_at = NOW();
+
+  v_result := format('Subscribable "%s" registered successfully with scope tables: %s',
+                     p_name, array_to_string(v_scope_tables, ', '));
+
+  RAISE NOTICE '%', v_result;
+
+  RETURN v_result;
+END;
+$$ LANGUAGE plpgsql;
+
+-- ============================================================================
+-- Backfill existing subscribables with scope_tables
+-- ============================================================================
+
+UPDATE dzql.subscribables s
+SET scope_tables = dzql.extract_scope_tables(s.root_entity, s.relations)
+WHERE scope_tables = '{}' OR scope_tables IS NULL;
+
+-- ============================================================================
+-- Verification
+-- ============================================================================
+
+DO $$
+BEGIN
+  RAISE NOTICE 'Migration 010: Atomic Updates - Complete';
+  RAISE NOTICE 'Created dzql.extract_scope_tables() function';
+  RAISE NOTICE 'Updated dzql.register_subscribable() to auto-populate scope_tables';
+  RAISE NOTICE 'Backfilled existing subscribables';
+END $$;

package/src/server/index.js

@@ -2,7 +2,7 @@ import { createWebSocketHandlers, verify_jwt_token } from "./ws.js";
 import { closeConnections, setupListeners, sql, db } from "./db.js";
 import * as defaultApi from "./api.js";
 import { serverLogger, notifyLogger } from "./logger.js";
-import { getSubscriptionsBySubscribable, paramsMatch } from "./subscriptions.js";
+import { getSubscriptionsBySubscribable, paramsMatch, getSubscribableScopeTables } from "./subscriptions.js";
 
 // Re-export commonly used utilities
 export { sql, db } from "./db.js";
@@ -11,12 +11,12 @@ export { createMCPRoute } from "./mcp.js";
 
 /**
  * Process subscription updates when a database event occurs
- * Checks if any active subscriptions are affected and sends updates
+ * Forwards atomic events to affected subscriptions for client-side patching
  * @param {Object} event - Database event {table, op, pk, before, after}
  * @param {Function} broadcast - Broadcast function from WebSocket handlers
  */
 async function processSubscriptionUpdates(event, broadcast) {
-  const { table, op, before, after } = event;
+  const { table, op, pk, before, after } = event;
 
   // Get all active subscriptions grouped by subscribable
   const subscriptionsByName = getSubscriptionsBySubscribable();
@@ -30,6 +30,14 @@ async function processSubscriptionUpdates(event, broadcast) {
   // For each unique subscribable, check if this event affects any subscriptions
   for (const [subscribableName, subs] of subscriptionsByName.entries()) {
     try {
+      // Check if this table is in scope for this subscribable
+      // This is an optimization to avoid calling _affected_documents for unrelated tables
+      const scopeTables = await getSubscribableScopeTables(subscribableName, sql);
+      if (scopeTables.length > 0 && !scopeTables.includes(table)) {
+        notifyLogger.debug(`Table ${table} not in scope for ${subscribableName}, skipping`);
+        continue;
+      }
+
       // Ask PostgreSQL which subscription instances are affected
       const result = await sql.unsafe(
         `SELECT ${subscribableName}_affected_documents($1, $2, $3, $4) as affected`,
@@ -42,7 +50,7 @@ async function processSubscriptionUpdates(event, broadcast) {
         continue; // This subscribable not affected
       }
 
-      notifyLogger.debug(`${subscribableName}: ${affectedParamSets.length} param set(s) affected`);
+      notifyLogger.debug(`${subscribableName}: ${affectedParamSets.length} param set(s) affected by ${table}:${op}`);
 
       // Match affected params to active subscriptions
       for (const affectedParams of affectedParamSets) {
@@ -50,33 +58,32 @@ async function processSubscriptionUpdates(event, broadcast) {
           // Check if this subscription matches the affected params
           if (paramsMatch(sub.params, affectedParams)) {
             try {
-              // Re-execute query to get updated data
-              const updated = await sql.unsafe(
-                `SELECT get_${subscribableName}($1, $2) as data`,
-                [sub.params, sub.user_id]
-              );
-
-              const data = updated[0]?.data;
-
-              // Send update to specific connection
+              // Forward atomic event instead of re-querying the full document
+              // Client will apply the patch to their local copy
               const message = JSON.stringify({
                 jsonrpc: "2.0",
-                method: "subscription:update",
+                method: "subscription:event",
                 params: {
                   subscription_id: sub.subscriptionId,
                   subscribable: subscribableName,
-                  data
+                  event: {
+                    table,
+                    op,
+                    pk,
+                    data: after,
+                    before
+                  }
                 }
               });
 
               const sent = broadcast.toConnection(sub.connection_id, message);
               if (sent) {
-                notifyLogger.debug(`Sent update to subscription ${sub.subscriptionId.slice(0, 8)}...`);
+                notifyLogger.debug(`Sent atomic event to subscription ${sub.subscriptionId.slice(0, 8)}... (${table}:${op})`);
               } else {
-                notifyLogger.warn(`Failed to send update to connection ${sub.connection_id.slice(0, 8)}...`);
+                notifyLogger.warn(`Failed to send event to connection ${sub.connection_id.slice(0, 8)}...`);
               }
             } catch (error) {
-              notifyLogger.error(`Failed to update subscription ${sub.subscriptionId}:`, error.message);
+              notifyLogger.error(`Failed to send event to subscription ${sub.subscriptionId}:`, error.message);
             }
           }
         }

package/src/server/subscriptions.js

@@ -18,6 +18,12 @@ const subscriptions = new Map();
  */
 const connectionSubscriptions = new Map();
 
+/**
+ * Cache for subscribable metadata (scope tables, path mappings)
+ * Structure: subscribable_name -> { scopeTables, pathMapping, rootEntity, relations }
+ */
+const subscribableMetadataCache = new Map();
+
 /**
  * Register a new subscription
  * @param {string} subscribableName - Name of the subscribable
@@ -207,3 +213,122 @@ export function getAllSubscriptions() {
     ...sub
   }));
 }
+
+/**
+ * Get subscribable metadata (scope tables, path mapping) with caching
+ * @param {string} subscribableName - Name of the subscribable
+ * @param {function} sql - Database query function
+ * @returns {Promise<{scopeTables: string[], pathMapping: object, rootEntity: string, relations: object}>}
+ */
+export async function getSubscribableMetadata(subscribableName, sql) {
+  // Check cache first
+  if (subscribableMetadataCache.has(subscribableName)) {
+    return subscribableMetadataCache.get(subscribableName);
+  }
+
+  // Fetch from database
+  const result = await sql`
+    SELECT scope_tables, root_entity, relations
+    FROM dzql.subscribables
+    WHERE name = ${subscribableName}
+  `;
+
+  if (!result || result.length === 0) {
+    // Return empty metadata if subscribable not found
+    const emptyMetadata = {
+      scopeTables: [],
+      pathMapping: {},
+      rootEntity: null,
+      relations: {}
+    };
+    return emptyMetadata;
+  }
+
+  const { scope_tables, root_entity, relations } = result[0];
+
+  // Build path mapping from relations
+  const pathMapping = buildPathMappingFromRelations(root_entity, relations);
+
+  const metadata = {
+    scopeTables: scope_tables || [],
+    pathMapping,
+    rootEntity: root_entity,
+    relations: relations || {}
+  };
+
+  // Cache for future use
+  subscribableMetadataCache.set(subscribableName, metadata);
+
+  wsLogger.debug(`Cached metadata for subscribable ${subscribableName}:`, {
+    scopeTables: metadata.scopeTables,
+    pathMapping: metadata.pathMapping
+  });
+
+  return metadata;
+}
+
+/**
+ * Build path mapping from relations configuration
+ * Maps table names to their document path for client-side patching
+ * @param {string} rootEntity - Root table name
+ * @param {object} relations - Relations configuration
+ * @returns {object} - Map of table name -> document path
+ */
+function buildPathMappingFromRelations(rootEntity, relations) {
+  const paths = {};
+
+  // Root entity maps to top level
+  if (rootEntity) {
+    paths[rootEntity] = '.';
+  }
+
+  const buildPaths = (rels, parentPath = '') => {
+    for (const [relName, relConfig] of Object.entries(rels || {})) {
+      const entity = typeof relConfig === 'string' ? relConfig : relConfig?.entity;
+      const currentPath = parentPath ? `${parentPath}.${relName}` : relName;
+
+      if (entity) {
+        paths[entity] = currentPath;
+      }
+
+      // Handle nested relations
+      if (typeof relConfig === 'object' && relConfig !== null) {
+        if (relConfig.include) {
+          buildPaths(relConfig.include, currentPath);
+        }
+        if (relConfig.relations) {
+          buildPaths(relConfig.relations, currentPath);
+        }
+      }
+    }
+  };
+
+  buildPaths(relations);
+  return paths;
+}
+
+/**
+ * Clear the subscribable metadata cache
+ * Called when subscribables are reregistered or updated
+ * @param {string} [subscribableName] - Optional: clear specific subscribable, or all if not provided
+ */
+export function clearSubscribableMetadataCache(subscribableName = null) {
+  if (subscribableName) {
+    subscribableMetadataCache.delete(subscribableName);
+    wsLogger.debug(`Cleared metadata cache for ${subscribableName}`);
+  } else {
+    subscribableMetadataCache.clear();
+    wsLogger.debug('Cleared all subscribable metadata cache');
+  }
+}
+
+/**
+ * Get scope tables for a subscribable (convenience function)
+ * @param {string} subscribableName - Name of the subscribable
+ * @param {function} sql - Database query function
+ * @returns {Promise<string[]>} - Array of table names in scope
+ */
+export async function getSubscribableScopeTables(subscribableName, sql) {
+  const metadata = await getSubscribableMetadata(subscribableName, sql);
+  return metadata.scopeTables;
+}

package/src/server/ws.js

@@ -11,7 +11,8 @@ import {
   registerSubscription,
   unregisterSubscription,
   unregisterSubscriptionByParams,
-  removeConnectionSubscriptions
+  removeConnectionSubscriptions,
+  getSubscribableMetadata
 } from "./subscriptions.js";
 
 // Environment configuration
@@ -327,6 +328,9 @@ export function createRPCHandler(customHandlers = {}) {
 
           const data = queryResult[0]?.data;
 
+          // Get subscribable metadata for schema (path mapping for atomic updates)
+          const metadata = await getSubscribableMetadata(subscribableName, sql);
+
           // Register subscription in memory
           const subscriptionId = registerSubscription(
             subscribableName,
@@ -335,9 +339,15 @@ export function createRPCHandler(customHandlers = {}) {
             params
           );
 
+          // Build result with schema for client-side patching
           const result = {
             subscription_id: subscriptionId,
-            data
+            data,
+            // Include schema for atomic update support
+            schema: {
+              root: metadata.rootEntity,
+              paths: metadata.pathMapping
+            }
           };
 
           wsLogger.response(method, result, Date.now() - startTime);