dzql 0.2.1 → 0.2.2

package/README.md

@@ -4,11 +4,12 @@ PostgreSQL-powered framework with automatic CRUD operations, live query subscrip
 
 ## Documentation
 
-- **[Getting Started Guide](docs/GETTING_STARTED.md)** - Complete tutorial with working todo app
-- **[API Reference](docs/REFERENCE.md)** - Complete API documentation
-- **[Live Query Subscriptions](../../docs/SUBSCRIPTIONS_QUICK_START.md)** - Real-time denormalized documents (NEW in v0.2.0)
+- **[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)
 - **[Compiler Documentation](docs/compiler/)** - Entity compilation guide and coding standards
-- **[Claude Guide](docs/CLAUDE.md)** - Development guide for AI assistants
+- **[Claude Guide](docs/for-ai/claude-guide.md)** - Development guide for AI assistants
 - **[Venues Example](../venues/)** - Full working application
 
 ## Quick Install

package/docs/README.md

@@ -0,0 +1,71 @@
+# DZQL Documentation
+
+Complete documentation for the DZQL PostgreSQL-powered framework.
+
+## 📚 Getting Started
+
+New to DZQL? Start here:
+
+- **[Tutorial](getting-started/tutorial.md)** - Complete step-by-step guide with a working todo app
+- **[Subscriptions Quick Start](getting-started/subscriptions-quick-start.md)** - Get real-time subscriptions working in 5 minutes
+
+## 📖 Guides
+
+Feature-specific guides and how-tos:
+
+- **[Live Query Subscriptions](guides/subscriptions.md)** - Real-time denormalized documents
+- **[Client Stores](guides/client-stores.md)** - Pinia store patterns for Vue.js
+
+## 📘 Reference
+
+Complete API documentation:
+
+- **[API Reference](reference/api.md)** - The 5 operations, entities, permissions, graph rules
+- **[Client API](reference/client.md)** - WebSocket client and connection management
+- **[Compiler](compiler/)** - Entity compilation, code generation, and coding standards
+
+### Compiler 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
+
+## 🤖 For AI Assistants
+
+- **[Claude Guide](for-ai/claude-guide.md)** - Complete guide for AI-assisted DZQL development
+
+## 🔗 Quick Links
+
+- [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?
+
+- 📖 Check the guides above
+- 🐛 [Report an issue](https://github.com/blueshed/dzql/issues)
+- 💬 [Start a discussion](https://github.com/blueshed/dzql/discussions)
+- 🤖 Ask your AI assistant (they have access to this documentation!)

package/docs/compiler/README.md

@@ -0,0 +1,84 @@
+# DZQL Compiler Documentation
+
+The DZQL Compiler transforms declarative entity definitions into optimized PostgreSQL stored procedures.
+
+## Quick Start
+
+- **[Quickstart Guide](QUICKSTART.md)** - Get started with the compiler in 5 minutes
+
+## Guides
+
+- **[Advanced Filters](ADVANCED_FILTERS.md)** - Complex search operators and patterns
+- **[Coding Standards](CODING_STANDARDS.md)** - Best practices for DZQL code
+
+## Reference
+
+- **[Comparison](COMPARISON.md)** - How DZQL compares to other approaches
+- **[Session Summary](SESSION_SUMMARY.md)** - Development session documentation
+- **[Summary](SUMMARY.md)** - Compiler overview and architecture
+- **[Overnight Build](OVERNIGHT_BUILD.md)** - Batch compilation process
+
+## Using the Compiler
+
+### Via CLI
+
+```bash
+dzql compile database/domain.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
+```
+
+### Registering Entities
+
+```sql
+SELECT dzql.register_entity(
+  'todos',                              -- Table name
+  'title',                              -- Label field
+  array['title', 'description'],        -- Searchable fields
+  '{}'::jsonb,                          -- FK includes
+  false,                                -- Soft delete
+  '{}'::jsonb,                          -- Graph rules
+  jsonb_build_object(                   -- Notification paths
+    'owner', array['@user_id']
+  ),
+  jsonb_build_object(                   -- Permission paths
+    'view', array['@user_id'],
+    'create', array['@user_id'],
+    'update', array['@user_id'],
+    'delete', array['@user_id']
+  ),
+  '{}'::jsonb                           -- Temporal config
+);
+```
+
+This generates 5 PostgreSQL functions:
+- `get_todos(params, user_id)` - Retrieve single record
+- `save_todos(params, user_id)` - Create or update
+- `delete_todos(params, user_id)` - Delete record
+- `lookup_todos(params, user_id)` - Autocomplete
+- `search_todos(params, user_id)` - Search with filters
+
+## Architecture
+
+The compiler uses a three-phase approach:
+
+1. **Parse** - Extract entity definitions from SQL
+2. **Generate** - Create optimized PostgreSQL functions
+3. **Deploy** - Execute generated SQL
+
+All business logic runs in PostgreSQL, not application code.
+
+## See Also
+
+- [Main Documentation](../) - Full DZQL documentation
+- [API Reference](../reference/api.md) - The 5 operations
+- [For AI](../for-ai/claude-guide.md) - AI-assisted development

package/docs/{CLAUDE.md → for-ai/claude-guide.md}

@@ -1163,7 +1163,7 @@ array['name', 'address', 'city', 'description', 'notes', 'tags', 'metadata']
 
 ## Additional Resources
 
-- **API Reference**: See [packages/dzql/REFERENCE.md](packages/dzql/REFERENCE.md) for complete API documentation
-- **Tutorial**: See [packages/dzql/GETTING_STARTED.md](packages/dzql/GETTING_STARTED.md) for hands-on guide
+- **API Reference**: See [API Reference](../reference/api.md) for complete API documentation
+- **Tutorial**: See [Getting Started Tutorial](../getting-started/tutorial.md) for hands-on guide
 - **Examples**: See `packages/venues/` for complete working application
 - **Tests**: See `packages/venues/tests/` for comprehensive test patterns

package/docs/{SUBSCRIPTIONS_QUICK_START.md → getting-started/subscriptions-quick-start.md}

@@ -61,9 +61,9 @@ All change detection happens in PostgreSQL - zero configuration needed on the se
 
 ## Next Steps
 
-- [Full Documentation](./LIVE_QUERY_SUBSCRIPTIONS.md)
-- [Permission Paths Guide](./PATH_DSL.md)
-- [Example Subscribables](../packages/dzql/examples/subscribables/)
+- [Full Documentation](../guides/subscriptions.md)
+- [Permission Paths Guide](../../../../docs/architecture/PERMISSIONS.md)
+- [API Reference](../reference/api.md)
 
 ## Common Patterns
 

package/docs/{GETTING_STARTED.md → getting-started/tutorial.md}

@@ -2,7 +2,7 @@
 
 DZQL is a PostgreSQL framework that gives you **atomic real-time updates** via WebSocket. Every database change broadcasts instantly to all connected clients. Zero boilerplate.
 
-> **See also:** [REFERENCE.md](REFERENCE.md) for complete API documentation | [CLAUDE.md](../../docs/CLAUDE.md) for AI development guide
+> **See also:** [API Reference](../reference/api.md) for complete API documentation | [Claude Guide](../for-ai/claude-guide.md) for AI development guide
 
 ## The Core Pattern
 

package/docs/{LIVE_QUERY_SUBSCRIPTIONS.md → guides/subscriptions.md}

@@ -529,7 +529,7 @@ ws.api.subscribe_venue_detail(
 
 ## See Also
 
-- [Vision Document](../vision.md) - Architecture overview and patterns
-- [Path DSL](./PATH_DSL.md) - Permission path syntax
-- [WebSocket API](./WEBSOCKET_API.md) - Full WebSocket protocol reference
-- [Compiler Reference](./COMPILER.md) - Code generation details
+- [Vision Document](../../../../vision.md) - Architecture overview and patterns
+- [Permission Paths](../../../../docs/architecture/PERMISSIONS.md) - Permission path DSL syntax
+- [Subscription Architecture](../../../../docs/architecture/SUBSCRIPTIONS_STRATEGY.md) - Design decisions
+- [Compiler Documentation](../compiler/) - Code generation and compilation guide

package/docs/{REFERENCE.md → reference/api.md}

@@ -1,6 +1,6 @@
 # DZQL API Reference
 
-Complete API documentation for DZQL framework. For tutorials, see [GETTING_STARTED.md](GETTING_STARTED.md). For AI development guide, see [CLAUDE.md](../../docs/CLAUDE.md).
+Complete API documentation for DZQL framework. For tutorials, see [Getting Started Tutorial](../getting-started/tutorial.md). For AI development guide, see [Claude Guide](../for-ai/claude-guide.md).
 
 ## Table of Contents
 
@@ -869,7 +869,7 @@ ws.onBroadcast((method, params) => {
 
 Subscribe to denormalized documents and receive automatic updates when underlying data changes. Subscriptions use a PostgreSQL-first architecture where all change detection happens in the database.
 
-For complete documentation, see **[Live Query Subscriptions Guide](../../../docs/LIVE_QUERY_SUBSCRIPTIONS.md)** and **[Quick Start](../../../docs/SUBSCRIPTIONS_QUICK_START.md)**.
+For complete documentation, see **[Live Query Subscriptions Guide](../guides/subscriptions.md)** and **[Quick Start](../getting-started/subscriptions-quick-start.md)**.
 
 ### Quick Example
 
@@ -997,8 +997,8 @@ SELECT dzql.register_subscribable(
 
 ### See Also
 
-- **[Live Query Subscriptions Guide](../../../docs/LIVE_QUERY_SUBSCRIPTIONS.md)** - Complete reference
-- **[Quick Start Guide](../../../docs/SUBSCRIPTIONS_QUICK_START.md)** - 5-minute tutorial
+- **[Live Query Subscriptions Guide](../guides/subscriptions.md)** - Complete reference
+- **[Quick Start Guide](../getting-started/subscriptions-quick-start.md)** - 5-minute tutorial
 - **[Permission Paths](#permission--notification-paths)** - Path DSL syntax
 
 ---
@@ -1093,7 +1093,7 @@ const result = await db.api.myCustomFunction({param: 'value'}, userId);
 
 ## See Also
 
-- [GETTING_STARTED.md](GETTING_STARTED.md) - Hands-on tutorial
-- [CLAUDE.md](../../docs/CLAUDE.md) - AI development guide
-- [README.md](../../README.md) - Project overview
-- [Venues Example](../venues/) - Complete working application
+- [Getting Started Tutorial](../getting-started/tutorial.md) - Hands-on tutorial
+- [Claude Guide](../for-ai/claude-guide.md) - AI development guide
+- [Project README](../../../../README.md) - Project overview
+- [Venues Example](../../../venues/) - Complete working application

package/docs/{CLIENT-QUICK-START.md → reference/client.md}

@@ -154,7 +154,7 @@ You now have:
 
 ## Next Steps
 
-- Read [CLIENT-STORES.md](./CLIENT-STORES.md) for complete API reference
+- Read [Client Stores Guide](../guides/client-stores.md) for complete API reference
 - Customize the App.vue template
 - Add your own components
 - Style with Tailwind/DaisyUI
@@ -179,5 +179,5 @@ Check `packages/client` for a complete working example.
 ## Help
 
 For more help, see:
-- [CLIENT-STORES.md](./CLIENT-STORES.md) - Complete documentation
+- [Client Stores Guide](../guides/client-stores.md) - Complete documentation
 - [GitHub Issues](https://github.com/blueshed/dzql/issues)

package/package.json

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

package/src/database/migrations/008a_meta.sql

@@ -30,6 +30,13 @@ begin
       'temporal_fields', e.temporal_fields,
       'notification_paths', e.notification_paths,
       'permission_paths', e.permission_paths,
+      'primary_key', (
+        -- Get primary key columns
+        select jsonb_agg(a.attname order by a.attnum)
+        from pg_index i
+        join pg_attribute a on a.attrelid = i.indrelid and a.attnum = any(i.indkey)
+        where i.indrelid = e.table_name::regclass and i.indisprimary
+      ),
       'schema', (
         -- Get column schema from information_schema
         select jsonb_agg(

package/src/server/db.js

@@ -10,11 +10,17 @@ const DB_MAX_CONNECTIONS = parseInt(process.env.DB_MAX_CONNECTIONS || "10", 10);
 const DB_IDLE_TIMEOUT = parseInt(process.env.DB_IDLE_TIMEOUT || "20", 10);
 const DB_CONNECT_TIMEOUT = parseInt(process.env.DB_CONNECT_TIMEOUT || "10", 10);
 
+// SSL configuration for Heroku and other hosted databases
+const sslConfig = process.env.DATABASE_SSL === 'true'
+  ? { rejectUnauthorized: false }  // Heroku uses self-signed certs
+  : undefined;
+
 // Main PostgreSQL connection for queries
 export const sql = postgres(DATABASE_URL, {
   max: DB_MAX_CONNECTIONS,
   idle_timeout: DB_IDLE_TIMEOUT,
   connect_timeout: DB_CONNECT_TIMEOUT,
+  ssl: sslConfig,
   // Suppress NOTICE messages in test environment
   onnotice: process.env.NODE_ENV === 'test' ? () => {} : undefined,
 });
@@ -24,6 +30,7 @@ export const listen_sql = postgres(DATABASE_URL, {
   max: 1,
   idle_timeout: 0,
   connect_timeout: DB_CONNECT_TIMEOUT,
+  ssl: sslConfig,
   // Suppress NOTICE messages in test environment
   onnotice: process.env.NODE_ENV === 'test' ? () => {} : undefined,
 });

package/docs/LIVE_QUERY_SUBSCRIPTIONS_STRATEGY.md

@@ -1,488 +0,0 @@
-# Live Query Subscriptions Strategy
-
-**Date:** 2025-11-16
-**Status:** Phase 1 Complete (Compiler), Phase 2-4 Pending
-
----
-
-## Overview
-
-Live Query Subscriptions implement **Pattern 1** from `vision.md` - allowing clients to subscribe to denormalized documents and receive automatic updates when any related data changes.
-
-### Architecture Principles
-
-1. **PostgreSQL-First**: Database determines which subscriptions are affected
-2. **Compiler-Driven**: All logic compiled to PostgreSQL functions (zero runtime interpretation)
-3. **In-Memory Subscriptions**: Server holds active subscriptions in memory for performance
-4. **Naming Convention**: `subscribe_<name>` / `unsubscribe_<name>` for pattern matching
-
----
-
-## Core Concept: Subscribables
-
-**Subscribables** are separate from entities - they define denormalized documents that:
-- Combine data from multiple entities (root + relations)
-- Have their own access control (permission paths)
-- Define subscription parameters (subscription key)
-- Compile to PostgreSQL functions that determine affected documents
-
-### Example Subscribable
-
-```sql
-SELECT dzql.register_subscribable(
-  'venue_detail',              -- Subscribable name
-
-  -- Permission: who can subscribe?
-  jsonb_build_object(
-    'subscribe', ARRAY['@org_id->acts_for[org_id=$]{active}.user_id']
-  ),
-
-  -- Parameters: subscription key
-  jsonb_build_object(
-    'venue_id', 'int'
-  ),
-
-  -- Root entity
-  'venues',
-
-  -- Relations to include
-  jsonb_build_object(
-    'org', 'organisations',
-    'sites', jsonb_build_object(
-      'entity', 'sites',
-      'filter', 'venue_id=$venue_id'
-    ),
-    'packages', jsonb_build_object(
-      'entity', 'packages',
-      'filter', 'venue_id=$venue_id',
-      'include', jsonb_build_object(
-        'allocations', 'allocations'
-      )
-    )
-  )
-);
-```
-
----
-
-## Generated PostgreSQL Functions
-
-For each subscribable, the compiler generates 3 functions:
-
-###1. Access Control: `<name>_can_subscribe(user_id, params)`
-
-```sql
-CREATE OR REPLACE FUNCTION venue_detail_can_subscribe(
-  p_user_id INT,
-  p_params JSONB
-) RETURNS BOOLEAN AS $$
-BEGIN
-  -- Check permission path: @org_id->acts_for[org_id=$]{active}.user_id
-  RETURN EXISTS (
-    SELECT 1
-    FROM venues v
-    JOIN acts_for af ON af.org_id = v.org_id
-    WHERE v.id = (p_params->>'venue_id')::int
-      AND af.user_id = p_user_id
-      AND af.valid_to IS NULL
-  );
-END;
-$$ LANGUAGE plpgsql STABLE SECURITY DEFINER;
-```
-
-### 2. Query Function: `get_<name>(params, user_id)`
-
-```sql
-CREATE OR REPLACE FUNCTION get_venue_detail(
-  p_params JSONB,
-  p_user_id INT
-) RETURNS JSONB AS $$
-DECLARE
-  v_venue_id int;
-  v_result JSONB;
-BEGIN
-  v_venue_id := (p_params->>'venue_id')::int;
-
-  -- Check access control
-  IF NOT venue_detail_can_subscribe(p_user_id, p_params) THEN
-    RAISE EXCEPTION 'Permission denied';
-  END IF;
-
-  -- Build document with root and all relations
-  SELECT jsonb_build_object(
-    'venues', row_to_json(root.*),
-    'org', (SELECT row_to_json(o.*) FROM organisations o WHERE o.id = root.org_id),
-    'sites', (SELECT jsonb_agg(s.*) FROM sites s WHERE s.venue_id = root.id),
-    'packages', (
-      SELECT jsonb_agg(
-        jsonb_build_object(
-          'package', row_to_json(p.*),
-          'allocations', (SELECT jsonb_agg(a.*) FROM allocations a WHERE a.package_id = p.id)
-        )
-      )
-      FROM packages p WHERE p.venue_id = root.id
-    )
-  )
-  INTO v_result
-  FROM venues root
-  WHERE root.id = v_venue_id;
-
-  RETURN v_result;
-END;
-$$ LANGUAGE plpgsql SECURITY DEFINER;
-```
-
-### 3. Affected Documents: `<name>_affected_documents(table, op, old, new)`
-
-```sql
-CREATE OR REPLACE FUNCTION venue_detail_affected_documents(
-  p_table_name TEXT,
-  p_op TEXT,
-  p_old JSONB,
-  p_new JSONB
-) RETURNS JSONB[] AS $$
-DECLARE
-  v_affected JSONB[];
-BEGIN
-  CASE p_table_name
-    -- Venue changed: affects subscription for that venue
-    WHEN 'venues' THEN
-      v_affected := ARRAY[
-        jsonb_build_object('venue_id', COALESCE(p_new->>'id', p_old->>'id')::int)
-      ];
-
-    -- Organisation changed: affects all venues in that org
-    WHEN 'organisations' THEN
-      SELECT ARRAY_AGG(jsonb_build_object('venue_id', v.id))
-      INTO v_affected
-      FROM venues v
-      WHERE v.org_id = COALESCE((p_new->>'id')::int, (p_old->>'id')::int);
-
-    -- Site changed: affects parent venue
-    WHEN 'sites' THEN
-      v_affected := ARRAY[
-        jsonb_build_object('venue_id', COALESCE(p_new->>'venue_id', p_old->>'venue_id')::int)
-      ];
-
-    -- Package changed: affects parent venue
-    WHEN 'packages' THEN
-      v_affected := ARRAY[
-        jsonb_build_object('venue_id', COALESCE(p_new->>'venue_id', p_old->>'venue_id')::int)
-      ];
-
-    -- Allocation changed: affects venue via package
-    WHEN 'allocations' THEN
-      SELECT ARRAY_AGG(jsonb_build_object('venue_id', p.venue_id))
-      INTO v_affected
-      FROM packages p
-      WHERE p.id = COALESCE((p_new->>'package_id')::int, (p_old->>'package_id')::int);
-
-    ELSE
-      v_affected := ARRAY[]::JSONB[];
-  END CASE;
-
-  RETURN v_affected;
-END;
-$$ LANGUAGE plpgsql IMMUTABLE;
-```
-
----
-
-## Server Implementation (In-Memory)
-
-### Subscription Registry
-
-```javascript
-// In-memory storage
-const subscriptions = new Map();
-// subscription_id -> { subscribable, user_id, connection_id, params }
-
-const connectionSubscriptions = new Map();
-// connection_id -> Set<subscription_id>
-```
-
-### RPC Handlers
-
-```javascript
-// Pattern matching on method names
-if (method.startsWith('subscribe_')) {
-  const subscribableName = method.replace('subscribe_', '');
-  const subscriptionId = crypto.randomUUID();
-
-  // Execute initial query (checks permissions)
-  const data = await db.query(
-    `SELECT get_${subscribableName}($1, $2) as data`,
-    [params, userId]
-  );
-
-  // Store in memory
-  subscriptions.set(subscriptionId, {
-    subscribable: subscribableName,
-    user_id: userId,
-    connection_id: connectionId,
-    params
-  });
-
-  return {
-    subscription_id: subscriptionId,
-    data: data.rows[0].data
-  };
-}
-
-if (method.startsWith('unsubscribe_')) {
-  // Remove from in-memory registry
-  // Find and delete by params + connection
-}
-```
-
-### Event Listener
-
-```javascript
-setupListeners(async (event) => {
-  const { table, op, before, after } = event;
-
-  // EXISTING: Pattern 2 - Need to Know notifications
-  broadcast(...);
-
-  // NEW: Pattern 1 - Live Query subscriptions
-
-  // Group subscriptions by subscribable name
-  const subsByName = new Map();
-  for (const [subId, sub] of subscriptions.entries()) {
-    if (!subsByName.has(sub.subscribable)) {
-      subsByName.set(sub.subscribable, []);
-    }
-    subsByName.get(sub.subscribable).push({ subId, ...sub });
-  }
-
-  // For each subscribable, ask PostgreSQL which instances are affected
-  for (const [subscribableName, subs] of subsByName.entries()) {
-    const result = await db.query(
-      `SELECT ${subscribableName}_affected_documents($1, $2, $3, $4) as affected`,
-      [table, op, before, after]
-    );
-
-    const affectedParamSets = result.rows[0]?.affected || [];
-
-    // Match affected params to active subscriptions (in-memory)
-    for (const affectedParams of affectedParamSets) {
-      for (const sub of subs) {
-        if (paramsMatch(sub.params, affectedParams)) {
-          // Re-execute query
-          const updated = await db.query(
-            `SELECT get_${subscribableName}($1, $2) as data`,
-            [sub.params, sub.user_id]
-          );
-
-          // Broadcast to connection
-          broadcastToConnection(sub.connection_id, {
-            method: 'subscription:update',
-            params: {
-              subscription_id: sub.subId,
-              data: updated.rows[0].data
-            }
-          });
-        }
-      }
-    }
-  }
-});
-```
-
----
-
-## Client API
-
-```javascript
-// Subscribe
-const { data, unsubscribe } = await ws.api.subscribe_venue_detail(
-  { venue_id: 1 },
-  (updated) => {
-    console.log('Venue updated:', updated);
-    // Update UI
-  }
-);
-
-// Initial data available immediately
-console.log('Initial:', data);
-
-// Unsubscribe
-unsubscribe();
-
-// Or call directly
-await ws.api.unsubscribe_venue_detail({ venue_id: 1 });
-```
-
----
-
-## Implementation Status
-
-### ✅ Phase 1: Compiler (COMPLETE)
-
-**Files Created:**
-- `/packages/dzql/src/compiler/codegen/subscribable-codegen.js` - Code generation
-- `/packages/dzql/src/compiler/parser/subscribable-parser.js` - SQL parsing
-- `/packages/dzql/src/compiler/compiler.js` - Extended with subscribable support
-
-**Exports:**
-- `compileSubscribable(subscribable)` - Compile single subscribable
-- `compileAllSubscribables(subscribables[])` - Compile multiple
-- `compileSubscribablesFromSQL(sqlContent)` - Parse and compile from SQL file
-
-**Generated Functions:**
-- `<name>_can_subscribe(user_id, params)` - Access control
-- `get_<name>(params, user_id)` - Query function
-- `<name>_affected_documents(table, op, old, new)` - Affected params
-
-**Known Issue:**
-- Parser needs improvement for nested `jsonb_build_object()` calls
-- Test compilation failing on parameter splitting
-
----
-
-### 🔨 Phase 2: Database Schema (TODO)
-
-**Tasks:**
-1. Create `dzql.subscribables` table (metadata only)
-2. Create `register_subscribable()` SQL function
-3. Migration file: `011_subscriptions.sql`
-
-**Schema:**
-```sql
-CREATE TABLE IF NOT EXISTS dzql.subscribables (
-  name TEXT PRIMARY KEY,
-  permission_paths jsonb NOT NULL,
-  param_schema jsonb NOT NULL,
-  root_entity text NOT NULL,
-  relations jsonb NOT NULL,
-  created_at timestamptz DEFAULT NOW()
-);
-```
-
----
-
-### 🔨 Phase 3: Server Integration (TODO)
-
-**Files to Modify:**
-1. `/packages/dzql/src/server/ws.js`
-   - Add in-memory subscription registry
-   - Add `subscribe_*` / `unsubscribe_*` handlers
-   - Add `broadcastToConnection()` function
-
-2. `/packages/dzql/src/server/index.js`
-   - Extend event listener to check affected subscriptions
-   - Re-execute queries and broadcast updates
-
-**Estimated Effort:** 2-3 days
-
----
-
-### 🔨 Phase 4: Client Integration (TODO)
-
-**Files to Modify:**
-1. `/packages/dzql/src/client/ws.js`
-   - Add `subscribe_*` method handling
-   - Handle `subscription:update` messages
-   - Return `{ data, unsubscribe }` pattern
-
-**Estimated Effort:** 1-2 days
-
----
-
-## Testing Strategy
-
-### Unit Tests (Compiler)
-```javascript
-test('generates subscribable functions', () => {
-  const result = compileSubscribable({
-    name: 'venue_detail',
-    permissionPaths: { subscribe: ['@org_id->acts_for...'] },
-    paramSchema: { venue_id: 'int' },
-    rootEntity: 'venues',
-    relations: { org: 'organisations', sites: 'sites' }
-  });
-
-  expect(result.sql).toContain('venue_detail_can_subscribe');
-  expect(result.sql).toContain('get_venue_detail');
-  expect(result.sql).toContain('venue_detail_affected_documents');
-});
-```
-
-### Integration Tests (Database)
-```sql
--- Test affected documents function
-SELECT venue_detail_affected_documents(
-  'venues', 'update',
-  '{"id": 1, "name": "Old"}'::jsonb,
-  '{"id": 1, "name": "New"}'::jsonb
-);
--- Should return: [{"venue_id": 1}]
-
--- Test query function
-SELECT get_venue_detail('{"venue_id": 1}'::jsonb, 5);
--- Should return denormalized document
-```
-
-### E2E Tests
-```javascript
-test('subscription receives updates', async () => {
-  const updates = [];
-
-  const { data, unsubscribe } = await ws.api.subscribe_venue_detail(
-    { venue_id: 1 },
-    (updated) => updates.push(updated)
-  );
-
-  // Trigger change
-  await ws.api.save.venues({ id: 1, name: 'Updated' });
-
-  await waitFor(() => updates.length > 0);
-  expect(updates[0].venues.name).toBe('Updated');
-
-  unsubscribe();
-});
-```
-
----
-
-## Next Steps
-
-1. **Fix Parser** - Handle nested `jsonb_build_object()` correctly
-2. **Test Compilation** - Verify generated SQL is correct
-3. **Create Migration** - `011_subscriptions.sql` with schema
-4. **Implement Server Handlers** - In-memory subscriptions + event processing
-5. **Implement Client Support** - `subscribe_*` methods
-6. **Integration Testing** - End-to-end subscription flow
-7. **Documentation** - API docs and examples
-
----
-
-## Estimated Timeline
-
-| Phase | Tasks | Effort |
-|-------|-------|--------|
-| Phase 1: Compiler | ✅ Complete | 4 hours |
-| Phase 2: Database | Schema + migration | 1 day |
-| Phase 3: Server | Handlers + event processing | 2-3 days |
-| Phase 4: Client | Client API | 1-2 days |
-| Testing | Unit + Integration + E2E | 2-3 days |
-| **Total** | | **7-10 days** |
-
----
-
-## Success Criteria
-
-- ✅ Compiler generates 3 PostgreSQL functions per subscribable
-- ⏳ PostgreSQL determines affected subscription instances (not server)
-- ⏳ Server holds subscriptions in-memory (fast lookup)
-- ⏳ Naming convention: `subscribe_<name>` / `unsubscribe_<name>`
-- ⏳ Client receives automatic updates on data changes
-- ⏳ < 100ms latency from DB change to client update
-- ⏳ Supports 1000+ concurrent subscriptions per server
-- ⏳ Zero runtime interpretation (all logic compiled)
-
----
-
-**Implementation by:** Claude Sonnet 4.5
-**Project:** DZQL Live Query Subscriptions
-**Version:** 0.1.4+subscriptions