dzql 0.6.18 → 0.6.20

package/docs/for_ai.md

@@ -1,699 +1,502 @@
-# DZQL Guide for AI Assistants
+# DZQL Domain Modeling Guide
 
-This document defines the patterns and conventions for generating valid DZQL domain definitions. Use this guide when asked to "Create a DZQL app" or "Add an entity".
+This guide defines patterns for generating valid DZQL domain definitions.
 
-## Quick Start
+## Quick Reference
 
-The fastest way to create a new DZQL app:
-
-```bash
-bun create dzql my-app
-cd my-app
-bun install
-bun run db:rebuild
-bun run dev
 ```
+DOMAIN STRUCTURE
+================
+export default {
+  entities: { ... },
+  subscribables: { ... },
+  customFunctions: [ ... ],
+  auth: { ... }              // Optional: override auth types
+} satisfies DomainConfig;
+
+ENTITY PATTERN
+==============
+entity_name: {
+  schema: { column: 'pg_type constraints' },
+  primaryKey: ['id'],        // Default, override for composite
+  label: 'name',             // For lookups/display
+  searchable: ['name'],      // Text search fields
+  hidden: ['password_hash'], // Exclude from API responses
+  managed: true,             // false = skip CRUD generation
+  softDelete: false,         // true = use deleted_at
+  permissions: { view, create, update, delete },
+  includes: { rel: 'entity' },      // FK expansions
+  manyToMany: { ... },
+  graphRules: { on_create, on_update, on_delete },
+  notifications: { ... }
+}
 
-## Core Concept: The Domain Definition
-
-A DZQL application is defined by a single TypeScript/JavaScript module exporting `entities` and `subscribables`.
+PERMISSION DSL
+==============
+[]                                    = Deny all
+['TRUE']                              = Public access
+['@author_id']                        = @user_id == @author_id
+['@author_id == @user_id']            = Explicit equality
+['@org_id->acts_for[org_id=$].user_id']        = Traversal
+['@org_id->acts_for[org_id=$]{active}.user_id'] = With temporal filter
+
+SUBSCRIBABLE PATTERN
+====================
+sub_name: {
+  params: { param: 'type' },
+  root: { entity: 'table', key: 'param' },
+  includes: { rel: { entity: 'table', includes: {...} } },
+  scopeTables: ['all', 'affected', 'tables'],
+  canSubscribe: ['permission_path']
+}
+```
 
-### 1. Entity Definition Pattern
+## Entity Definition
 
-Each key in `entities` maps to a database table.
+Each key in `entities` maps to a PostgreSQL table.
 
-```javascript
+```typescript
 export const entities = {
-  // Key = Table Name (snake_case recommended)
-  [entity_name]: {
-    
-    // 1. Schema: Standard PostgreSQL types
-    // Format: 'type constraints'
+  posts: {
     schema: {
       id: 'serial PRIMARY KEY',
-      name: 'text NOT NULL',
-      org_id: 'int REFERENCES organisations(id) ON DELETE CASCADE', // Always define FK constraints
-      created_at: 'timestamptz DEFAULT now()'
+      title: 'text NOT NULL',
+      content: 'text',
+      author_id: 'int NOT NULL REFERENCES users(id)',
+      org_id: 'int REFERENCES organisations(id) ON DELETE CASCADE',
+      created_at: 'timestamptz DEFAULT now()',
+      deleted_at: 'timestamptz'  // For soft delete
     },
 
-    // 2. Configuration
-    label: 'name', // Field used for autocomplete/display
-    searchable: ['name', 'description'], // Fields indexed for search
+    label: 'title',
+    searchable: ['title', 'content'],
+    softDelete: true,
 
-    // 3. Permissions: Row-Level Security DSL
-    // Rules are OR-ed together. If any rule passes, access is granted.
-    // Empty array [] = Deny All (Default for strictness)
-    // ['TRUE'] = Public Access
     permissions: {
-      view: ['@org_id->acts_for[org_id=$]{active}.user_id'], // Complex traversal
-      create: ['@author_id == @user_id'], // Simple check
-      update: ['@id'], // Implies "User ID matches Record ID" (Owner)
-      delete: []
+      view: ['@org_id->acts_for[org_id=$]{active}.user_id'],
+      create: ['@org_id->acts_for[org_id=$]{active}.user_id'],
+      update: ['@author_id'],
+      delete: ['@author_id']
+    },
+
+    // FK expansions - automatically included in responses
+    includes: {
+      author: 'users',
+      org: 'organisations'
     },
 
-    // 4. Graph Rules: Side Effects & Cascades
     graphRules: {
-      // Triggered AFTER successful INSERT
       on_create: {
-        action_name: {
-          actions: [
-            // Database Side Effect
-            { 
-              type: 'create', 
-              entity: 'notifications', 
-              data: { user_id: '@user_id', message: 'Welcome' } 
-            },
-            // Async Reactor (External Side Effect via Runtime)
-            { 
-              type: 'reactor', 
-              name: 'send_email', 
-              params: { email: '@email' } 
-            }
-          ]
-        }
-      },
-      // Triggered BEFORE DELETE
-      on_delete: {
-        cascade_cleanup: {
+        notify_org: {
           actions: [
-            // Explicit Cascade (if not handled by DB FK)
-            { type: 'delete', target: 'comments', params: { post_id: '@id' } }
+            { type: 'reactor', name: 'send_notification', params: { org_id: '@org_id' } }
           ]
         }
       }
+    },
+
+    notifications: {
+      org_members: ['@org_id->acts_for[org_id=$]{active}.user_id']
     }
   }
 };
 ```
 
-### 2. Permission DSL Guide
+## Permission Patterns
 
-Permissions are compiled to SQL `EXISTS` clauses.
+Permissions compile to SQL `EXISTS` clauses. Rules are OR'd together.
 
-*   **Variables:**
-    *   `@user_id`: The authenticated user's ID.
-    *   `@id`: The Record's ID (or value of `id` column).
-    *   `@field`: The value of a field in the record (or input data).
+### Variables
+- `@user_id` - Authenticated user's ID
+- `@field` - Value of field in the record
+- `@id` - Record's primary key value
 
-*   **Patterns:**
-    *   **Self-Ownership:** `'@user_id == @owner_id'` (or just `'@owner_id'` shorthand).
-    *   **Traversal:** `'@org_id->acts_for[org_id=$]{active}.user_id'`
-        *   `@org_id`: Start from this field on the current entity.
-        *   `->acts_for`: Join to `acts_for` table.
-        *   `[org_id=$]`: Join condition (`acts_for.org_id = current.org_id`).
-        *   `{active}`: Filter condition (`acts_for.active = true` or temporal check).
-        *   `.user_id`: Final check (`acts_for.user_id = @user_id`).
+### Common Patterns
 
-### 3. Subscribable Definition Pattern (The "Smart Store")
+```typescript
+// Owner only
+update: ['@author_id']  // Shorthand for @author_id == @user_id
 
-Subscribables define the *shape* of the data the client needs. They are more than just queries; they define the **Graph Patching Strategy**.
+// Organization member via junction table
+view: ['@org_id->acts_for[org_id=$]{active}.user_id']
+// Reads as: "user exists in acts_for where org_id matches and active=true"
 
-```javascript
-export const subscribables = {
-  // Key = Subscription Name
-  venue_detail: {
-    // 1. Parameters (Inputs)
-    params: { venue_id: 'int' },
+// Self (user can only access own record)
+view: ['@id']  // For users table: @id == @user_id
 
-    // 2. Root Entity
-    root: {
-      entity: 'venues',
-      key: 'venue_id' // Maps param 'venue_id' to entity PK
-    },
+// Public read, authenticated write
+view: ['TRUE'],
+create: []  // Empty = logged-in users only
 
-    // 3. Graph Structure (Nested Includes)
-    includes: {
-      // Simple relation
-      org: { relation: 'org', entity: 'organisations' },
-      
-      // Nested relation
-      sites: {
-        relation: 'sites',
-        entity: 'sites',
-        // Recursive nesting
-        includes: {
-          allocations: { relation: 'allocations', entity: 'allocations' }
-        }
-      }
-    },
+// Multiple paths (OR'd)
+view: ['@author_id', '@org_id->acts_for[org_id=$].user_id']
+```
 
-    // 4. Scope Tables (Crucial for Realtime)
-    // List ALL tables that appear in this graph.
-    // The Runtime uses this to route events.
-    scopeTables: ['venues', 'organisations', 'sites', 'allocations'],
+### Traversal Syntax
 
-    // 5. Subscription Permission
-    // Who is allowed to listen to this feed?
-    canSubscribe: ['@venue_id->venues.org_id->acts_for[org_id=$]{active}.user_id']
-  }
-};
+```
+@field->table[join_condition]{filter}.target_field
+  │      │          │           │          │
+  │      │          │           │          └── Final check: table.target_field = @user_id
+  │      │          │           └── Optional: WHERE filter (e.g., active=true, temporal)
+  │      │          └── Join: table.join_field = current.@field
+  │      └── Target table
+  └── Starting field on current entity
 ```
 
-### When to use what?
+## CRUD Operations
 
-*   **Entities:** Always define entities for every physical table.
-*   **Subscribables:** Define a subscribable for every **Screen** or **Major Component** in the UI. (e.g., `dashboard`, `profile`, `item_detail`).
-    *   *Do not* write manual API fetchers. Use subscribables to generate "Smart Stores" that self-update.
+Every entity gets 5 operations: `get`, `save`, `delete`, `search`, `lookup`.
 
-### Using Generated Subscribable Stores
+### Get - Rich Document
 
-Each subscribable in your domain generates a Pinia store with this structure:
+`get` returns a **rich document** with FK and M2M expansions:
 
 ```typescript
-// Generated store API
-const store = useVenueDetailStore();
+// Entity with includes and manyToMany
+posts: {
+  schema: { id: 'serial PRIMARY KEY', author_id: 'int', org_id: 'int', title: 'text' },
+  includes: { author: 'users', org: 'organisations' },
+  manyToMany: { tags: { junctionTable: 'post_tags', ... } }
+}
 
-store.bind(params)    // Async - subscribe and get { data, loading, ready }
-store.unbind(params)  // Unsubscribe and remove document from store
-store.documents       // Ref - all bound documents keyed by JSON params
+// get_posts({ id: 1 }) returns:
+{
+  id: 1,
+  author_id: 5,
+  org_id: 2,
+  title: 'Hello',
+  author: { id: 5, name: 'Alice', email: '...' },  // Direct FK expanded
+  org: { id: 2, name: 'Acme Corp' },               // Direct FK expanded
+  tag_ids: [1, 3, 7],                               // M2M IDs
+  tags: [{ id: 1, name: 'tech' }, ...]             // M2M expanded (if expand: true)
+}
 ```
 
-**Basic Usage:**
+**Key insight:** `get` is already a rich document. Use it as the starting point. Only move to subscribables when you need:
+- One-to-many (reverse FK) expansion
+- Complex nested includes
+- Realtime updates across multiple tables
 
-```typescript
-import { useVenueDetailStore } from '@/generated/client/stores';
+### Save - Atomic with Side Effects
 
-const store = useVenueDetailStore();
+`save` handles insert/update, M2M sync, and graph rules in one transaction:
 
-// bind() returns a Promise that resolves when first data arrives
-const { data, loading, ready } = await store.bind({ venue_id: 1 });
+```typescript
+// Insert (no id)
+await ws.api.save_posts({ title: 'New', author_id: 1, tag_ids: [1, 2] });
 
-// data is now populated - no need to check loading
-console.log(data.name); // 'My Venue'
-console.log(data.org.name); // 'My Org' (nested include)
-console.log(data.sites); // [{...}, {...}] (array of related records)
+// Update (has id) - partial update, only provided fields change
+await ws.api.save_posts({ id: 1, title: 'Updated' });
 
-// Subsequent calls with same params return cached subscription immediately
-const cached = await store.bind({ venue_id: 1 }); // No new subscription created
+// M2M sync happens automatically
+await ws.api.save_posts({ id: 1, tag_ids: [3, 4] });  // Replaces old tags
 ```
 
-**Vue Component Pattern (with Suspense):**
-
-```vue
-<script setup>
-import { useVenueDetailStore } from '@/generated/client/stores';
+Returns the full document with FK/M2M expansions.
 
-const props = defineProps(['venueId']);
-const store = useVenueDetailStore();
+### Search - Filtered List
 
-// Top-level await - component suspends until data arrives
-const { data } = await store.bind({ venue_id: props.venueId });
-</script>
-
-<template>
-  <h1>{{ data.name }}</h1>
-  <p>Org: {{ data.org.name }}</p>
-  <ul>
-    <li v-for="site in data.sites" :key="site.id">
-      {{ site.name }}
-    </li>
-  </ul>
-</template>
+```typescript
+await ws.api.search_posts({
+  filters: { org_id: { eq: 1 }, title: { ilike: '%hello%' } },
+  sort_field: 'created_at',
+  sort_order: 'desc',
+  limit: 20,
+  offset: 0
+});
 ```
 
-**Vue Component Pattern (with loading state):**
-
-```vue
-<script setup>
-import { useVenueDetailStore } from '@/generated/client/stores';
-import { ref, onMounted, watch } from 'vue';
+Filter operators: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `not_in`, `ilike`, `is_null`.
 
-const props = defineProps(['venueId']);
-const store = useVenueDetailStore();
-const doc = ref({ data: null, loading: true });
-
-onMounted(async () => {
-  doc.value = await store.bind({ venue_id: props.venueId });
-});
+### Lookup - Autocomplete
 
-// Re-bind when venueId changes
-watch(() => props.venueId, async (newId) => {
-  doc.value = await store.bind({ venue_id: newId });
-});
-</script>
-
-<template>
-  <div v-if="doc.loading">Loading...</div>
-  <template v-else>
-    <h1>{{ doc.data.name }}</h1>
-  </template>
-</template>
+```typescript
+await ws.api.lookup_posts({ q: 'hel' });  // Returns [{label: 'Hello World', value: 1}, ...]
 ```
 
-**Accessing Multiple Subscriptions:**
+Uses the entity's `label` field for display.
 
-```typescript
-const store = useVenueDetailStore();
+### Delete
 
-// Each unique params set creates a separate subscription
-await store.bind({ venue_id: 1 });
-await store.bind({ venue_id: 2 });
-
-// Access all documents via store.documents
-for (const [key, docState] of Object.entries(store.documents)) {
-  console.log(key, docState.data);
-}
-// '{"venue_id":1}' { id: 1, name: 'Venue 1', ... }
-// '{"venue_id":2}' { id: 2, name: 'Venue 2', ... }
+```typescript
+await ws.api.delete_posts({ id: 1 });  // Hard delete or soft delete based on entity config
 ```
 
-**Key Points:**
-- `bind()` is async and awaits first data before returning
-- Same params = same cached subscription (deduplication by JSON key)
-- The `ready` Promise is stored for repeat callers to await
-- **Stores own their data** - the WebSocket is just transport
-- Data is reactive - changes trigger Vue reactivity automatically
+## Subscribable Definition
 
-### How Realtime Works
+Subscribables define realtime data shapes for UI components.
 
-DZQL uses a unified `table_changed` pattern for all stores:
+```typescript
+export const subscribables = {
+  // Name becomes: subscribe_venue_detail, get_venue_detail, useVenueDetailStore
+  venue_detail: {
+    params: { venue_id: 'int' },
 
-1. **Database events:** PostgreSQL triggers emit events to `dzql_v2.events`
-2. **Server broadcasts:** Runtime sends `{table}:{op}` messages (e.g., `venues:update`) to clients
-3. **Auto-dispatch:** WebSocket client routes broadcasts to registered store handlers
-4. **Store updates:** Each store's `table_changed` method applies updates to local data
+    root: {
+      entity: 'venues',
+      key: 'venue_id'  // Maps param to entity PK
+    },
 
-**Stores self-register - no manual setup needed:**
+    includes: {
+      org: 'organisations',  // Simple: FK expansion
+      sites: {
+        entity: 'sites',
+        includes: {
+          allocations: 'allocations'  // Nested
+        }
+      }
+    },
 
-```typescript
-// Generated store (simplified)
-export const useVenuesStore = defineStore('venues-store', () => {
-  const records = ref([]);
+    // ALL tables that can trigger updates
+    scopeTables: ['venues', 'organisations', 'sites', 'allocations'],
 
-  function table_changed(table: string, op: string, pk: Record<string, unknown>, data: unknown) {
-    if (table !== 'venues') return;
-    // Update records based on op (insert/update/delete)
+    // Who can subscribe
+    canSubscribe: ['@venue_id->venues.org_id->acts_for[org_id=$]{active}.user_id']
   }
+};
+```
 
-  // Self-register with WebSocket
-  ws.registerStore(table_changed);
+### Generated Types
 
-  return { records, get, save, search, table_changed };
-});
-```
+The compiler generates TypeScript types for subscribables:
 
-**User code - just works:**
 ```typescript
-const venuesStore = useVenuesStore();  // Auto-registers for broadcasts
-await venuesStore.search({ org_id: 1 });
-// records update automatically when broadcasts arrive!
-```
-
-### Entity Notifications
+// Generated in client/ws.ts
+export interface VenueDetailParams {
+  venue_id: number;
+}
 
-Entities can define `notifications` paths to specify who receives broadcasts:
+export interface VenueDetailResult extends Venues {
+  org?: Organisations;      // Many-to-one (singular)
+  sites?: Sites[];          // One-to-many (array)
+}
 
-```javascript
-export const entities = {
-  venues: {
-    schema: { id: 'serial PRIMARY KEY', org_id: 'int', name: 'text' },
-    notifications: {
-      members: ['@org_id->acts_for[org_id=$]{active}.user_id']
-    }
-  }
-};
+// In DzqlAPI interface
+subscribe_venue_detail: (
+  params: VenueDetailParams,
+  callback: (data: VenueDetailResult) => void
+) => Promise<{ data: VenueDetailResult; unsubscribe: () => Promise<void> }>;
 ```
 
-When a venue is created/updated/deleted, all active members of that org receive the broadcast
+## Many-to-Many Relationships
 
-### Common Patterns
+```typescript
+brands: {
+  schema: {
+    id: 'serial PRIMARY KEY',
+    name: 'text NOT NULL'
+  },
+  manyToMany: {
+    tags: {
+      junctionTable: 'brand_tags',
+      localKey: 'brand_id',
+      foreignKey: 'tag_id',
+      targetEntity: 'tags',
+      idField: 'tag_ids'  // Param name for save: { tag_ids: [1,2,3] }
+    }
+  }
+},
 
-**1. The "Owner" Pattern:**
-```javascript
-create: ['@author_id == @user_id']
+// Junction table - skip CRUD generation
+brand_tags: {
+  schema: {
+    brand_id: 'int NOT NULL REFERENCES brands(id) ON DELETE CASCADE',
+    tag_id: 'int NOT NULL REFERENCES tags(id) ON DELETE CASCADE'
+  },
+  primaryKey: ['brand_id', 'tag_id'],
+  managed: false  // No get_brand_tags, save_brand_tags, etc.
+}
 ```
 
-**2. The "Organization Member" Pattern:**
-```javascript
-view: ['@org_id->memberships[org_id=$].user_id']
-```
+## Graph Rules (Side Effects)
 
-**3. The "Creator Side Effect" Pattern:**
-Use `graphRules.on_create` to create related records automatically (e.g., creating a default 'Settings' record when a 'User' is created).
+```typescript
+graphRules: {
+  on_create: {
+    rule_name: {
+      description: 'Create audit log on insert',
+      actions: [
+        // Create related record
+        {
+          type: 'create',
+          entity: 'audit_logs',
+          data: { entity: 'posts', entity_id: '@id', action: 'created' }
+        },
+        // Call external service via runtime
+        {
+          type: 'reactor',
+          name: 'send_email',
+          params: { user_id: '@author_id', template: 'post_created' }
+        }
+      ]
+    }
+  },
 
-**4. The "Reactor" Pattern:**
-Use `type: 'reactor'` for anything that requires Node.js (Email, Stripe, AI processing). Do not try to do complex logic in SQL.
+  on_update: {
+    status_change: {
+      condition: "@before.status = 'draft' AND @after.status = 'published'",
+      actions: [
+        { type: 'reactor', name: 'notify_subscribers', params: { post_id: '@id' } }
+      ]
+    }
+  },
 
----
+  on_delete: {
+    cleanup: {
+      actions: [
+        { type: 'delete', target: 'comments', match: { post_id: '@id' } }
+      ]
+    }
+  }
+}
+```
 
 ## Custom Functions
 
-DZQL supports two types of custom functions that can be called via RPC:
-
-### 1. SQL Custom Functions
-
-SQL custom functions are defined in your domain and compiled into the database migrations. They run inside PostgreSQL and are ideal for complex queries, aggregations, or operations that benefit from database-level performance.
+### SQL Functions
 
-**Domain Definition:**
-
-```javascript
-// domain.js
-export const entities = { /* ... */ };
-export const subscribables = { /* ... */ };
-
-// Add custom SQL functions
+```typescript
 export const customFunctions = [
   {
-    name: 'calculate_org_stats',
+    name: 'calculate_stats',
     sql: `
-CREATE OR REPLACE FUNCTION dzql_v2.calculate_org_stats(p_user_id int, p_params jsonb)
+CREATE OR REPLACE FUNCTION dzql_v2.calculate_stats(p_user_id int, p_params jsonb)
 RETURNS jsonb LANGUAGE plpgsql AS $$
-DECLARE
-  v_org_id int;
-  v_venue_count int;
-  v_total_revenue numeric;
 BEGIN
-  v_org_id := (p_params->>'org_id')::int;
-
-  -- Permission check (optional but recommended)
-  IF NOT EXISTS (
-    SELECT 1 FROM acts_for
-    WHERE user_id = p_user_id AND org_id = v_org_id AND active = true
-  ) THEN
-    RAISE EXCEPTION 'permission_denied' USING ERRCODE = 'P0001';
-  END IF;
-
-  SELECT COUNT(*) INTO v_venue_count
-  FROM venues WHERE org_id = v_org_id;
-
-  SELECT COALESCE(SUM(amount), 0) INTO v_total_revenue
-  FROM orders WHERE org_id = v_org_id;
-
   RETURN jsonb_build_object(
-    'org_id', v_org_id,
-    'venue_count', v_venue_count,
-    'total_revenue', v_total_revenue
+    'total', (SELECT count(*) FROM posts WHERE org_id = (p_params->>'org_id')::int)
   );
 END;
-$$;
-    `,
-    args: ['p_user_id', 'p_params']  // Optional, defaults to these
+$$;`,
+    args: ['p_user_id', 'p_params'],
+    // Type information for generated client
+    params: { org_id: 'number' },
+    returns: { total: 'number' }
   }
 ];
 ```
 
-**Calling from Client:**
-
-```typescript
-// The function is automatically added to the client SDK
-const stats = await ws.api.calculate_org_stats({ org_id: 1 });
-console.log(stats.venue_count, stats.total_revenue);
-```
-
-**Key Points:**
-- Functions must be in the `dzql_v2` schema
-- Standard signature: `(p_user_id int, p_params jsonb) RETURNS jsonb`
-- Automatically added to the manifest allowlist (security)
-- Compiled into the database migrations
-
-### 2. JavaScript Custom Functions
+### JavaScript Functions
 
-JavaScript custom functions run in the Bun/Node runtime. They are ideal for:
-- External API calls (Stripe, SendGrid, etc.)
-- Complex business logic that's easier in JS than SQL
-- Operations that need access to environment variables or external services
-
-**Registration (in your server startup):**
+Register in server startup for external APIs, complex logic, or env access:
 
 ```typescript
-// server.ts or wherever you start your runtime
-import { registerJsFunction } from 'dzql/runtime';
-
-// Simple function
-registerJsFunction('hello_world', async (ctx) => {
-  return {
-    message: `Hello, User ${ctx.userId}!`,
-    timestamp: new Date().toISOString()
-  };
-});
+import { registerJsFunction } from 'dzql';
 
-// Function with database access
-registerJsFunction('get_user_dashboard', async (ctx) => {
+registerJsFunction('send_email', async (ctx) => {
   const { userId, params, db } = ctx;
-
-  // Query the database
-  const orgs = await db.query(
-    'SELECT o.* FROM organisations o JOIN acts_for af ON o.id = af.org_id WHERE af.user_id = $1 AND af.active = true',
-    [userId]
-  );
-
-  const venues = await db.query(
-    'SELECT * FROM venues WHERE org_id = ANY($1)',
-    [orgs.map(o => o.id)]
-  );
-
-  return {
-    organizations: orgs,
-    venues: venues,
-    total_venues: venues.length
-  };
-});
-
-// Function calling external API
-registerJsFunction('send_notification', async (ctx) => {
-  const { userId, params } = ctx;
-
-  // Call external service
-  const response = await fetch('https://api.sendgrid.com/v3/mail/send', {
-    method: 'POST',
-    headers: {
-      'Authorization': `Bearer ${process.env.SENDGRID_API_KEY}`,
-      'Content-Type': 'application/json'
-    },
-    body: JSON.stringify({
-      to: params.email,
-      subject: params.subject,
-      content: params.message
-    })
-  });
-
-  return { success: response.ok };
+  await fetch('https://api.sendgrid.com/...', { ... });
+  return { sent: true };
 });
 ```
 
-**Calling from Client:**
+## Auth Configuration
 
-```typescript
-// JS functions are called the same way as SQL functions
-const dashboard = await ws.api.get_user_dashboard({});
-const result = await ws.api.send_notification({
-  email: 'user@example.com',
-  subject: 'Hello',
-  message: 'Welcome!'
-});
-```
-
-**Context Object:**
+Override default auth types for client generation:
 
 ```typescript
-interface JsFunctionContext {
-  userId: number;        // Authenticated user's ID
-  params: any;           // Parameters passed from client
-  db: {
-    query(sql: string, params?: any[]): Promise<any[]>;  // Database access
-  };
-}
-```
-
-**Key Points:**
-- JS functions take precedence over SQL functions with the same name
-- No manifest entry needed - registration is enough
-- Full access to Node.js/Bun APIs (fetch, fs, etc.)
-- Can query the database via `ctx.db.query()`
-- Errors thrown are propagated to the client
-
-### When to Use Which?
-
-| Use Case | SQL | JavaScript |
-|----------|-----|------------|
-| Complex aggregations | ✅ | |
-| Data transformations | ✅ | |
-| External API calls | | ✅ |
-| Email/SMS notifications | | ✅ |
-| File processing | | ✅ |
-| Payment processing | | ✅ |
-| Performance-critical queries | ✅ | |
-| Access to env variables | | ✅ |
-| Multi-step transactions | ✅ | |
-| Real-time calculations | ✅ | |
-
----
-
-## Unmanaged Entities (Junction Tables)
-
-For junction tables used in many-to-many relationships, you typically don't want DZQL to generate CRUD functions. These tables are managed via the M2M relationship on the parent entity.
-
-Use `managed: false` to skip CRUD generation:
-
-```javascript
-export const entities = {
-  brands: {
-    schema: {
-      id: 'serial PRIMARY KEY',
-      name: 'text NOT NULL'
+export default {
+  entities: { ... },
+  
+  auth: {
+    userFields: {
+      user_id: 'number',
+      email: 'string',
+      name: 'string',
+      avatar_url: 'string'
     },
-    // M2M relationship manages brand_tags automatically
-    manyToMany: {
-      tags: {
-        junctionTable: 'brand_tags',
-        localKey: 'brand_id',
-        foreignKey: 'tag_id',
-        targetEntity: 'tags',
-        idField: 'tag_ids'
-      }
-    }
-  },
-
-  tags: {
-    schema: {
-      id: 'serial PRIMARY KEY',
-      name: 'text NOT NULL'
-    }
-  },
-
-  // Junction table - no CRUD functions generated
-  brand_tags: {
-    schema: {
-      brand_id: 'int NOT NULL REFERENCES brands(id) ON DELETE CASCADE',
-      tag_id: 'int NOT NULL REFERENCES tags(id) ON DELETE CASCADE'
-    },
-    primaryKey: ['brand_id', 'tag_id'],
-    managed: false  // Skip CRUD generation
+    loginParams: { email: 'string', password: 'string' },
+    registerParams: { email: 'string', password: 'string', name: 'string' }
   }
-};
+} satisfies DomainConfig;
 ```
 
-**What `managed: false` does:**
-- The table schema is still created in the database
-- No `get_brand_tags`, `save_brand_tags`, `delete_brand_tags`, etc. functions are generated
-- No manifest entries for CRUD operations
-- The junction table is managed via the parent entity's M2M operations
-
----
-
-## Client Connection & Authentication
-
-When a client connects to the WebSocket server, it immediately receives a `connection:ready` message containing the authenticated user profile (or `null` if not authenticated).
-
-### Connection Flow
-
-1. Client connects with optional `?token=...` in URL
-2. Server validates token (if present) and fetches user profile
-3. Server sends: `{"method": "connection:ready", "params": {"user": {...} | null}}`
-4. Client knows auth state immediately, can render accordingly
-
-### WebSocketManager API
-
+Generated types:
 ```typescript
-import { ws } from '@generated/client/ws';
-
-await ws.connect('/ws');
-
-// Authentication via typed API
-const user = await ws.api.login_user({ email: '...', password: '...' });
-// Token is returned in response - store in localStorage
-if (user.token) {
-  localStorage.setItem('dzql_token', user.token);
-}
-
-const newUser = await ws.api.register_user({ name: '...', email: '...', password: '...' });
-// Token is returned in response
-
-// Logout - clear token and disconnect
-localStorage.removeItem('dzql_token');
-ws.disconnect();
-await ws.connect('/ws');  // Reconnect without token
+interface LoginParams { email: string; password: string; }
+interface LoginResult extends AuthUser { token: string; }
+interface RegisterParams { email: string; password: string; name: string; }
+interface RegisterResult extends AuthUser { token: string; }
 ```
 
-### Vue/Pinia Usage Pattern
-
-```vue
-<template>
-  <div v-if="!ws.ready">Loading...</div>
-  <LoginModal v-else-if="!ws.user" />
-  <RouterView v-else />
-</template>
-```
+## Client Usage
 
-### Why This Matters
-
-- **Single source of truth:** WebSocket connection determines auth state, not localStorage
-- **No race conditions:** UI waits for `connection:ready` before rendering
-- **Simpler client code:** No need for separate auth check after connect
-- **Better UX:** App shows loading state until connection ready, then immediately correct view
-
----
-
-## CLI Integration with Namespace
-
-DZQL provides a namespace export for CLI tools like `invokej` to interact with the database directly without going through the WebSocket runtime.
-
-### Setup
+### WebSocket Connection
 
 ```typescript
-// cli.ts or server-side script
-import { DzqlNamespace } from 'dzql/namespace';
-import postgres from 'postgres';
+import { ws } from '@generated/client';
 
-const sql = postgres(process.env.DATABASE_URL);
-const manifest = await import('./dist/runtime/manifest.json');
+await ws.connect('/ws');
 
-const dzql = new DzqlNamespace(sql, manifest);
+// Typed API
+const user = await ws.api.login_user({ email: '...', password: '...' });
+const post = await ws.api.save_posts({ title: 'Hello', org_id: 1 });
+const posts = await ws.api.search_posts({ filters: { org_id: { eq: 1 } } });
 ```
 
-### CRUD Operations
+### Subscribable Stores
 
 ```typescript
-// Get a record
-const venue = await dzql.get('venues', { id: 1 }, userId);
-
-// Save (create or update)
-const newVenue = await dzql.save('venues', { name: 'New Venue', org_id: 1 }, userId);
-
-// Delete
-const deleted = await dzql.delete('venues', { id: 1 }, userId);
+import { useVenueDetailStore } from '@generated/client/stores';
 
-// Search with filters
-const venues = await dzql.search('venues', { org_id: 1, limit: 10 }, userId);
+const store = useVenueDetailStore();
+const { data } = await store.bind({ venue_id: 1 });
 
-// Lookup for autocomplete
-const options = await dzql.lookup('venues', { q: 'test' }, userId);
+// data is reactive - updates automatically on changes
+console.log(data.name, data.org.name, data.sites.length);
 ```
 
-### Ad-hoc Function Calls
+## Common Modeling Patterns
 
-Call any function in the manifest directly:
+### Multi-tenant with Organizations
 
 ```typescript
-// Call a custom function
-const result = await dzql.call('calculate_org_stats', { org_id: 1 }, userId);
-
-// Call a subscribable getter
-const detail = await dzql.call('get_venue_detail', { venue_id: 1 }, userId);
+entities: {
+  users: { schema: { id: 'serial PRIMARY KEY', email: 'text UNIQUE NOT NULL' } },
+  organisations: { schema: { id: 'serial PRIMARY KEY', name: 'text NOT NULL' } },
+  acts_for: {
+    schema: {
+      user_id: 'int REFERENCES users(id)',
+      org_id: 'int REFERENCES organisations(id)',
+      valid_from: 'date DEFAULT CURRENT_DATE',
+      valid_to: 'date',
+      active: 'boolean GENERATED ALWAYS AS (valid_to IS NULL OR valid_to > CURRENT_DATE) STORED'
+    },
+    primaryKey: ['user_id', 'org_id', 'valid_from']
+  },
+  // All tenant data uses org_id and permission path
+  posts: {
+    schema: { ..., org_id: 'int REFERENCES organisations(id)' },
+    permissions: {
+      view: ['@org_id->acts_for[org_id=$]{active}.user_id']
+    }
+  }
+}
 ```
 
-### List Available Functions
+### Ownership Pattern
 
 ```typescript
-// Get all functions from manifest
-const functions = dzql.functions();
-// Returns: ['login_user', 'register_user', 'get_venues', 'save_venues', ...]
+posts: {
+  schema: { ..., author_id: 'int REFERENCES users(id)' },
+  fieldDefaults: { author_id: '@user_id' },  // Auto-set on create
+  permissions: {
+    view: ['TRUE'],
+    create: [],
+    update: ['@author_id'],
+    delete: ['@author_id']
+  }
+}
 ```
 
-### Use with invokej
-
-The namespace is designed for use with `invokej`, a CLI tool for invoking functions:
+### Soft Delete
 
-```bash
-# In your invokej configuration, register the DZQL namespace
-invokej dzql:get venues '{"id": 1}'
-invokej dzql:save venues '{"name": "Updated Venue", "id": 1}'
-invokej dzql:call calculate_org_stats '{"org_id": 1}'
-invokej dzql:functions
+```typescript
+posts: {
+  schema: { ..., deleted_at: 'timestamptz' },
+  softDelete: true
+  // delete_posts sets deleted_at instead of removing row
+  // search_posts excludes deleted_at IS NOT NULL by default
+}
 ```
-
-**Key Points:**
-- All operations respect the same permissions as the WebSocket runtime
-- The `userId` parameter is required for permission checks
-- Operations are atomic (single transaction)
-- Results are returned as JSON objects