dzql 0.6.8 → 0.6.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dzql",
-  "version": "0.6.8",
+  "version": "0.6.10",
   "description": "Database-first real-time framework with TypeScript support",
   "repository": {
     "type": "git",

package/src/cli/compiler/graph_rules.ts

@@ -7,7 +7,11 @@ import type { GraphRuleIR } from "../../shared/ir.js";
  * @param trigger - The trigger context ('create', 'update', 'delete')
  * @param castToInt - Whether to cast the result to integer (for FK columns)
  */
-function resolveValue(value: string, trigger: string, castToInt: boolean = false): string {
+function resolveValue(value: string | null, trigger: string, castToInt: boolean = false): string {
+  if (value === null) {
+    return 'NULL';
+  }
+
   if (typeof value !== 'string') {
     return String(value);
   }

package/src/client/ws.ts

@@ -49,7 +49,7 @@ export class WebSocketManager {
 
   async login(credentials: any) {
     try {
-      const result = await this.call('login_user', credentials);
+      const result = await this.call('login_user', credentials) as { token?: string };
       if (result && result.token) {
         if (typeof localStorage !== 'undefined') {
           localStorage.setItem(this.tokenName, result.token);
@@ -69,7 +69,7 @@ export class WebSocketManager {
   async register(credentials: any, options: any = {}) {
     try {
       const params = { ...credentials, options };
-      const result = await this.call('register_user', params);
+      const result = await this.call('register_user', params) as { token?: string };
       if (result && result.token) {
         if (typeof localStorage !== 'undefined') {
           localStorage.setItem(this.tokenName, result.token);
@@ -98,9 +98,10 @@ export class WebSocketManager {
 
       let wsUrl = url;
       if (!wsUrl) {
-        if (typeof window !== "undefined") {
-          const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
-          wsUrl = protocol + "//" + window.location.host + "/ws";
+        if (typeof globalThis !== "undefined" && "window" in globalThis) {
+          const win = globalThis as unknown as { location: { protocol: string; host: string } };
+          const protocol = win.location.protocol === "https:" ? "wss:" : "ws:";
+          wsUrl = protocol + "//" + win.location.host + "/ws";
         } else {
           wsUrl = "ws://localhost:3000/ws";
         }

package/src/runtime/index.ts

@@ -5,6 +5,7 @@ import { WebSocketServer } from "./ws.js";
 import { loadManifest } from "./manifest_loader.js";
 import { readFileSync } from "fs";
 import { resolve } from "path";
+import { runtimeLogger, notifyLogger, serverLogger } from "./logger.js";
 
 // Re-export JS function registration API for custom functions
 export { registerJsFunction, type JsFunctionHandler, type JsFunctionContext } from "./js_functions.js";
@@ -26,9 +27,9 @@ try {
   const manifestContent = readFileSync(manifestPath, "utf-8");
   const manifest = JSON.parse(manifestContent);
   loadManifest(manifest);
-  console.log(`[Runtime] Loaded Manifest v${manifest.version}`);
+  runtimeLogger.info(`Loaded Manifest v${manifest.version}`);
 } catch (e) {
-  console.warn(`[Runtime] Warning: Could not load manifest from ${MANIFEST_PATH}. Ensure you have compiled the project.`);
+  runtimeLogger.warn(`Could not load manifest from ${MANIFEST_PATH}. Ensure you have compiled the project.`);
 }
 
 // 3. Initialize WebSocket Server
@@ -36,12 +37,12 @@ const wsServer = new WebSocketServer(db);
 
 // 4. Start Commit Listener (Realtime)
 async function startListener() {
-  console.log("[Runtime] Setting up LISTEN on dzql_v2 channel...");
+  runtimeLogger.info("Setting up LISTEN on dzql_v2 channel...");
   await db.listen("dzql_v2", async (payload) => {
-    console.log(`[Runtime] RAW NOTIFY received:`, payload);
+    notifyLogger.debug(`RAW NOTIFY received:`, payload);
     try {
       const { commit_id } = JSON.parse(payload);
-      console.log(`[Runtime] Received Commit: ${commit_id}`);
+      notifyLogger.debug(`Received Commit: ${commit_id}`);
 
       // Fetch events
       const events = await db.query(`
@@ -67,12 +68,13 @@ async function startListener() {
           }
         });
         wsServer.broadcast(message);
+        notifyLogger.trace(`Broadcast ${event.op} on ${event.table_name}`);
       }
-    } catch (e) {
-      console.error("[Runtime] Listener Error:", e);
+    } catch (e: any) {
+      notifyLogger.error("Listener Error:", e.message);
     }
   });
-  console.log("[Runtime] Listening for DB Events...");
+  runtimeLogger.info("Listening for DB Events...");
 }
 
 // Wait for listener to be ready before starting server
@@ -85,14 +87,14 @@ const server = serve({
     const url = new URL(req.url);
 
     // Extract token from query params for WebSocket connections
-    const token = url.searchParams.get("token");
+    const token = url.searchParams.get("token") ?? undefined;
 
     if (server.upgrade(req, { data: { token } })) {
-        return;
+      return;
     }
     return new Response("DZQL Runtime Active", { status: 200 });
   },
   websocket: wsServer.handlers
 });
 
-console.log(`[Runtime] Server listening on port ${PORT}`);
+serverLogger.info(`Server listening on port ${PORT}`);

package/src/runtime/js_functions.ts

@@ -2,7 +2,7 @@
 // Allows registering JS/Bun functions that can be called via RPC
 
 export interface JsFunctionContext {
-  userId: number;
+  userId: number | null;
   params: any;
   db: {
     query(sql: string, params?: any[]): Promise<any[]>;

package/src/runtime/logger.ts

@@ -0,0 +1,308 @@
+// logger.ts - Flexible logging system with categories and levels
+
+// Log levels
+const LOG_LEVELS: Record<string, number> = {
+  ERROR: 0,
+  WARN: 1,
+  INFO: 2,
+  DEBUG: 3,
+  TRACE: 4,
+};
+
+// Default log level from environment or INFO
+const DEFAULT_LEVEL = process.env.LOG_LEVEL?.toUpperCase() || "INFO";
+
+// Parse LOG_CATEGORIES from environment
+// Format: "ws:debug,db:trace,auth:info" or "*:debug" for all
+const parseCategories = (): Record<string, number> => {
+  const categories: Record<string, number> = {};
+  const envCategories = process.env.LOG_CATEGORIES || "";
+
+  if (!envCategories) {
+    // Default: INFO level unless in production/test
+    if (process.env.NODE_ENV === "production") {
+      categories["*"] = LOG_LEVELS.ERROR;
+    } else if (process.env.NODE_ENV === "test") {
+      categories["*"] = LOG_LEVELS.ERROR;
+    } else {
+      categories["*"] = LOG_LEVELS[DEFAULT_LEVEL] ?? LOG_LEVELS.INFO;
+    }
+    return categories;
+  }
+
+  // Parse category:level pairs
+  envCategories.split(",").forEach((pair) => {
+    const [category, level] = pair.trim().split(":");
+    if (category && level) {
+      const levelValue = LOG_LEVELS[level.toUpperCase()];
+      if (levelValue !== undefined) {
+        categories[category] = levelValue;
+      }
+    }
+  });
+
+  // Set default for non-specified categories
+  if (!categories["*"]) {
+    categories["*"] = LOG_LEVELS[DEFAULT_LEVEL] ?? LOG_LEVELS.INFO;
+  }
+
+  return categories;
+};
+
+// Initialize categories
+let logCategories = parseCategories();
+
+// Colors for terminal output
+const colors = {
+  reset: "\x1b[0m",
+  bright: "\x1b[1m",
+  dim: "\x1b[2m",
+  red: "\x1b[31m",
+  green: "\x1b[32m",
+  yellow: "\x1b[33m",
+  blue: "\x1b[34m",
+  magenta: "\x1b[35m",
+  cyan: "\x1b[36m",
+  white: "\x1b[37m",
+  gray: "\x1b[90m",
+};
+
+// Level colors
+const levelColors: Record<string, string> = {
+  ERROR: colors.red,
+  WARN: colors.yellow,
+  INFO: colors.blue,
+  DEBUG: colors.cyan,
+  TRACE: colors.gray,
+};
+
+// Category colors
+const categoryColors: Record<string, string> = {
+  ws: colors.green,
+  db: colors.magenta,
+  auth: colors.yellow,
+  api: colors.cyan,
+  server: colors.blue,
+  notify: colors.magenta,
+  access: colors.green,
+  runtime: colors.blue,
+};
+
+// Format timestamp
+const timestamp = (): string => {
+  const now = new Date();
+  return now.toISOString().replace("T", " ").slice(0, -5);
+};
+
+// Check if logging is enabled for category and level
+const shouldLog = (category: string, level: string): boolean => {
+  const categoryLevel = logCategories[category] ?? logCategories["*"] ?? LOG_LEVELS.INFO;
+  return LOG_LEVELS[level] <= categoryLevel;
+};
+
+// Format log message with colors
+const formatMessage = (category: string, level: string, message: string, ...args: any[]): any[] => {
+  const useColors = process.env.NO_COLOR !== "1" && process.env.NODE_ENV !== "test";
+
+  if (useColors) {
+    const catColor = categoryColors[category] || colors.white;
+    const lvlColor = levelColors[level];
+
+    return [
+      `${colors.gray}${timestamp()}${colors.reset}`,
+      `${lvlColor}[${level}]${colors.reset}`,
+      `${catColor}[${category}]${colors.reset}`,
+      message,
+      ...args,
+    ];
+  } else {
+    return [timestamp(), `[${level}]`, `[${category}]`, message, ...args];
+  }
+};
+
+export interface Logger {
+  error: (message: string, ...args: any[]) => void;
+  warn: (message: string, ...args: any[]) => void;
+  info: (message: string, ...args: any[]) => void;
+  debug: (message: string, ...args: any[]) => void;
+  trace: (message: string, ...args: any[]) => void;
+  request: (method: string, params?: any) => void;
+  response: (method: string, result: any, duration: number) => void;
+}
+
+// Create logger for a specific category
+export const createLogger = (category: string): Logger => {
+  return {
+    error: (message: string, ...args: any[]) => {
+      if (shouldLog(category, "ERROR")) {
+        console.error(...formatMessage(category, "ERROR", message, ...args));
+      }
+    },
+    warn: (message: string, ...args: any[]) => {
+      if (shouldLog(category, "WARN")) {
+        console.warn(...formatMessage(category, "WARN", message, ...args));
+      }
+    },
+    info: (message: string, ...args: any[]) => {
+      if (shouldLog(category, "INFO")) {
+        console.log(...formatMessage(category, "INFO", message, ...args));
+      }
+    },
+    debug: (message: string, ...args: any[]) => {
+      if (shouldLog(category, "DEBUG")) {
+        console.log(...formatMessage(category, "DEBUG", message, ...args));
+      }
+    },
+    trace: (message: string, ...args: any[]) => {
+      if (shouldLog(category, "TRACE")) {
+        console.log(...formatMessage(category, "TRACE", message, ...args));
+      }
+    },
+    // For request/response logging
+    request: (method: string, params?: any) => {
+      if (shouldLog(category, "DEBUG")) {
+        console.log(
+          ...formatMessage(category, "DEBUG", `→ ${method}`, params ? JSON.stringify(params) : "")
+        );
+      }
+    },
+    response: (method: string, result: any, duration: number) => {
+      if (shouldLog(category, "DEBUG")) {
+        const resultStr =
+          result === undefined
+            ? "void"
+            : typeof result === "object"
+              ? `${JSON.stringify(result).slice(0, 100)}...`
+              : result;
+        console.log(...formatMessage(category, "DEBUG", `← ${method} (${duration}ms)`, resultStr));
+      }
+    },
+  };
+};
+
+// Pre-configured loggers for common categories
+export const wsLogger = createLogger("ws");
+export const dbLogger = createLogger("db");
+export const authLogger = createLogger("auth");
+export const serverLogger = createLogger("server");
+export const notifyLogger = createLogger("notify");
+export const accessLogger = createLogger("access");
+export const runtimeLogger = createLogger("runtime");
+
+// Reload configuration (useful for runtime changes)
+export const reloadConfig = (): void => {
+  logCategories = parseCategories();
+};
+
+// Get current configuration
+export const getConfig = (): { categories: Record<string, number>; levels: Record<string, number> } => {
+  return {
+    categories: logCategories,
+    levels: LOG_LEVELS,
+  };
+};
+
+// Middleware for timing operations
+export const timed = async <T>(category: string, operation: string, fn: () => Promise<T>): Promise<T> => {
+  const logger = createLogger(category);
+  const start = Date.now();
+
+  try {
+    logger.trace(`Starting ${operation}`);
+    const result = await fn();
+    const duration = Date.now() - start;
+    logger.debug(`Completed ${operation} in ${duration}ms`);
+    return result;
+  } catch (error: any) {
+    const duration = Date.now() - start;
+    logger.error(`Failed ${operation} after ${duration}ms:`, error.message);
+    throw error;
+  }
+};
+
+// Access log format: "method path status duration"
+export const logAccess = (
+  method: string,
+  path: string,
+  status: number,
+  duration: number,
+  userId?: number | null
+): void => {
+  if (shouldLog("access", "INFO")) {
+    const userStr = userId ? `user:${userId}` : "anon";
+    const statusColor = status >= 400 ? colors.red : status >= 300 ? colors.yellow : colors.green;
+    const useColors = process.env.NO_COLOR !== "1" && process.env.NODE_ENV !== "test";
+
+    if (useColors) {
+      console.log(
+        `${colors.gray}${timestamp()}${colors.reset}`,
+        `${colors.blue}[INFO]${colors.reset}`,
+        `${colors.green}[access]${colors.reset}`,
+        `${method} ${path}`,
+        `${statusColor}${status}${colors.reset}`,
+        `${duration}ms`,
+        `${colors.gray}${userStr}${colors.reset}`
+      );
+    } else {
+      console.log(timestamp(), "[INFO]", "[access]", `${method} ${path}`, status, `${duration}ms`, userStr);
+    }
+  }
+};
+
+// WebSocket access log
+export const logWsAccess = (
+  action: string,
+  method: string,
+  duration: number,
+  userId?: number | null,
+  error?: string
+): void => {
+  if (shouldLog("access", "INFO")) {
+    const userStr = userId ? `user:${userId}` : "anon";
+    const useColors = process.env.NO_COLOR !== "1" && process.env.NODE_ENV !== "test";
+    const statusColor = error ? colors.red : colors.green;
+    const status = error ? "ERR" : "OK";
+
+    if (useColors) {
+      console.log(
+        `${colors.gray}${timestamp()}${colors.reset}`,
+        `${colors.blue}[INFO]${colors.reset}`,
+        `${colors.green}[access]${colors.reset}`,
+        `WS ${action}`,
+        method,
+        `${statusColor}${status}${colors.reset}`,
+        `${duration}ms`,
+        `${colors.gray}${userStr}${colors.reset}`,
+        error ? `${colors.red}${error}${colors.reset}` : ""
+      );
+    } else {
+      console.log(
+        timestamp(),
+        "[INFO]",
+        "[access]",
+        `WS ${action}`,
+        method,
+        status,
+        `${duration}ms`,
+        userStr,
+        error || ""
+      );
+    }
+  }
+};
+
+export default {
+  createLogger,
+  wsLogger,
+  dbLogger,
+  authLogger,
+  serverLogger,
+  notifyLogger,
+  accessLogger,
+  runtimeLogger,
+  reloadConfig,
+  getConfig,
+  timed,
+  logAccess,
+  logWsAccess,
+};

package/src/runtime/manifest_loader.ts

@@ -1,16 +1,17 @@
 import { Manifest } from "../cli/codegen/manifest.js";
+import { runtimeLogger } from "./logger.js";
 
 // Global cache for the loaded manifest
 let activeManifest: Manifest | null = null;
 
 export function loadManifest(manifest: Manifest) {
-  console.log(`[Runtime] Loading manifest v${manifest.version}`);
+  runtimeLogger.debug(`Loading manifest v${manifest.version}`);
   activeManifest = manifest;
 }
 
 export function getManifest(): Manifest {
   if (!activeManifest) {
-    throw new Error("[Runtime] Manifest not loaded.");
+    throw new Error("Manifest not loaded.");
   }
   return activeManifest;
 }
@@ -18,11 +19,11 @@ export function getManifest(): Manifest {
 export function resolveFunction(name: string) {
   const manifest = getManifest();
   const fn = manifest.functions[name];
-  
+
   if (!fn) {
     return null;
   }
-  
+
   // In a real DB-connected runtime, we would resolve OID here.
   // For now, we return the schema-qualified name.
   return `${fn.schema}.${fn.name}`;

package/src/runtime/namespace.ts

@@ -1,43 +1,42 @@
 /**
- * DZQL Namespace for invokej integration
+ * DZQL Namespace for invoket integration
  *
  * Provides CLI-style access to DZQL operations via the compiled manifest.
  * Each method outputs JSON to console and closes the connection before returning.
  *
- * Setup - add to your tasks.js:
- * ```js
- * import { DzqlNamespace } from 'dzql/namespace';
+ * Setup - add to your tasks.ts:
+ * ```ts
+ * import { Context } from "invoket/context";
+ * import { DzqlNamespace } from "dzql/namespace";
  *
  * export class Tasks {
- *   constructor() {
- *     this.dzql = new DzqlNamespace();
- *   }
+ *   dzql = new DzqlNamespace();
  * }
  * ```
  *
  * Available Commands:
  *
  * Discovery:
- *   invj dzql:entities                              # List all entities
- *   invj dzql:subscribables                         # List all subscribables
- *   invj dzql:functions                             # List all manifest functions
+ *   invt dzql:entities                              # List all entities
+ *   invt dzql:subscribables                         # List all subscribables
+ *   invt dzql:functions                             # List all manifest functions
  *
  * Entity CRUD:
- *   invj dzql:search venues '{"query": "test"}'     # Search with filters
- *   invj dzql:get venues '{"id": 1}'                # Get by primary key
- *   invj dzql:save venues '{"name": "New", "org_id": 1}'  # Create (no id)
- *   invj dzql:save venues '{"id": 1, "name": "Updated"}'  # Update (with id)
- *   invj dzql:delete venues '{"id": 1}'             # Delete by primary key
- *   invj dzql:lookup venues '{"query": "test"}'     # Lookup for dropdowns
+ *   invt dzql:search venues '{"query": "test"}'     # Search with filters
+ *   invt dzql:get venues '{"id": 1}'                # Get by primary key
+ *   invt dzql:save venues '{"name": "New", "org_id": 1}'  # Create (no id)
+ *   invt dzql:save venues '{"id": 1, "name": "Updated"}'  # Update (with id)
+ *   invt dzql:delete venues '{"id": 1}'             # Delete by primary key
+ *   invt dzql:lookup venues '{"query": "test"}'     # Lookup for dropdowns
  *
  * Subscribables:
- *   invj dzql:subscribe venue_detail '{"venue_id": 1}'  # Get snapshot
+ *   invt dzql:subscribe venue_detail '{"venue_id": 1}'  # Get snapshot
  *
  * Ad-hoc Function Calls:
- *   invj dzql:call login_user '{"email": "x", "password": "y"}'
- *   invj dzql:call register_user '{"email": "x", "password": "y"}'
- *   invj dzql:call get_venue_detail '{"venue_id": 1}'
- *   invj dzql:call save_venues '{"name": "Test", "org_id": 1}'
+ *   invt dzql:call login_user '{"email": "x", "password": "y"}'
+ *   invt dzql:call register_user '{"email": "x", "password": "y"}'
+ *   invt dzql:call get_venue_detail '{"venue_id": 1}'
+ *   invt dzql:call save_venues '{"name": "Test", "org_id": 1}'
  *
  * Environment:
  *   DATABASE_URL - PostgreSQL connection string (default: postgres://localhost:5432/dzql)
@@ -54,6 +53,27 @@ import type { Manifest, FunctionDef } from "../cli/codegen/manifest.js";
 // Default user for CLI operations
 const DEFAULT_USER_ID = 1;
 
+/** Query parameters for search operations */
+export interface SearchParams {
+  query?: string;
+  filters?: Record<string, unknown>;
+  sort_field?: string;
+  sort_order?: "asc" | "desc";
+  limit?: number;
+  offset?: number;
+}
+
+/** Primary key for get/delete operations */
+export interface PkParams {
+  id?: number;
+  [key: string]: unknown;
+}
+
+/** Generic params for any operation */
+export interface CallParams {
+  [key: string]: unknown;
+}
+
 /**
  * Load manifest from MANIFEST_PATH env var or default locations
  */
@@ -122,7 +142,16 @@ function discoverSubscribables(manifest: Manifest): Record<string, { params: Rec
 }
 
 /**
- * DZQL operations namespace for invokej
+ * DZQL operations namespace for invoket
+ *
+ * Use with invoket task runner:
+ * ```ts
+ * import { DzqlNamespace } from "dzql/namespace";
+ *
+ * export class Tasks {
+ *   dzql = new DzqlNamespace();
+ * }
+ * ```
  */
 export class DzqlNamespace {
   private userId: number;
@@ -193,8 +222,9 @@ export class DzqlNamespace {
 
   /**
    * List all available entities
+   * @example invt dzql:entities
    */
-  async entities(_context?: any): Promise<void> {
+  async entities(_context: unknown): Promise<void> {
     try {
       const { manifest } = await this.init();
       const entities = discoverEntities(manifest);
@@ -209,8 +239,9 @@ export class DzqlNamespace {
 
   /**
    * List all available subscribables
+   * @example invt dzql:subscribables
    */
-  async subscribables(_context?: any): Promise<void> {
+  async subscribables(_context: unknown): Promise<void> {
     try {
       const { manifest } = await this.init();
       const subscribables = discoverSubscribables(manifest);
@@ -225,28 +256,11 @@ export class DzqlNamespace {
 
   /**
    * Search an entity
-   * @example invj dzql:search venues '{"query": "test"}'
+   * @example invt dzql:search venues '{"query": "test"}'
    */
-  async search(_context: any, entity?: string, argsJson: string = "{}"): Promise<void> {
-    if (!entity) {
-      console.error("Error: entity name required");
-      console.error("Usage: invj dzql:search <entity> '<json_args>'");
-      console.error('Example: invj dzql:search venues \'{"query": "test"}\'');
-      await this.cleanup();
-      process.exit(1);
-    }
-
-    let args: any;
+  async search(_context: unknown, entity: string, params: SearchParams = {}): Promise<void> {
     try {
-      args = JSON.parse(argsJson);
-    } catch {
-      console.error("Error: arguments must be valid JSON");
-      await this.cleanup();
-      process.exit(1);
-    }
-
-    try {
-      const result = await this.executeFunction(`search_${entity}`, args);
+      const result = await this.executeFunction(`search_${entity}`, params);
       console.log(JSON.stringify({ success: true, result }, null, 2));
       await this.cleanup();
     } catch (error: any) {
@@ -258,28 +272,11 @@ export class DzqlNamespace {
 
   /**
    * Get entity by ID
-   * @example invj dzql:get venues '{"id": 1}'
+   * @example invt dzql:get venues '{"id": 1}'
    */
-  async get(_context: any, entity?: string, argsJson: string = "{}"): Promise<void> {
-    if (!entity) {
-      console.error("Error: entity name required");
-      console.error("Usage: invj dzql:get <entity> '<json_args>'");
-      console.error('Example: invj dzql:get venues \'{"id": 1}\'');
-      await this.cleanup();
-      process.exit(1);
-    }
-
-    let args: any;
-    try {
-      args = JSON.parse(argsJson);
-    } catch {
-      console.error("Error: arguments must be valid JSON");
-      await this.cleanup();
-      process.exit(1);
-    }
-
+  async get(_context: unknown, entity: string, pk: PkParams): Promise<void> {
     try {
-      const result = await this.executeFunction(`get_${entity}`, args);
+      const result = await this.executeFunction(`get_${entity}`, pk);
       console.log(JSON.stringify({ success: true, result }, null, 2));
       await this.cleanup();
     } catch (error: any) {
@@ -291,28 +288,11 @@ export class DzqlNamespace {
 
   /**
    * Save (create or update) entity
-   * @example invj dzql:save venues '{"name": "New Venue", "org_id": 1}'
+   * @example invt dzql:save venues '{"name": "New Venue", "org_id": 1}'
    */
-  async save(_context: any, entity?: string, argsJson: string = "{}"): Promise<void> {
-    if (!entity) {
-      console.error("Error: entity name required");
-      console.error("Usage: invj dzql:save <entity> '<json_args>'");
-      console.error('Example: invj dzql:save venues \'{"name": "Test Venue", "org_id": 1}\'');
-      await this.cleanup();
-      process.exit(1);
-    }
-
-    let args: any;
-    try {
-      args = JSON.parse(argsJson);
-    } catch {
-      console.error("Error: arguments must be valid JSON");
-      await this.cleanup();
-      process.exit(1);
-    }
-
+  async save(_context: unknown, entity: string, data: CallParams): Promise<void> {
     try {
-      const result = await this.executeFunction(`save_${entity}`, args);
+      const result = await this.executeFunction(`save_${entity}`, data);
       console.log(JSON.stringify({ success: true, result }, null, 2));
       await this.cleanup();
     } catch (error: any) {
@@ -324,28 +304,11 @@ export class DzqlNamespace {
 
   /**
    * Delete entity by ID
-   * @example invj dzql:delete venues '{"id": 1}'
+   * @example invt dzql:delete venues '{"id": 1}'
    */
-  async delete(_context: any, entity?: string, argsJson: string = "{}"): Promise<void> {
-    if (!entity) {
-      console.error("Error: entity name required");
-      console.error("Usage: invj dzql:delete <entity> '<json_args>'");
-      console.error('Example: invj dzql:delete venues \'{"id": 1}\'');
-      await this.cleanup();
-      process.exit(1);
-    }
-
-    let args: any;
-    try {
-      args = JSON.parse(argsJson);
-    } catch {
-      console.error("Error: arguments must be valid JSON");
-      await this.cleanup();
-      process.exit(1);
-    }
-
+  async delete(_context: unknown, entity: string, pk: PkParams): Promise<void> {
     try {
-      const result = await this.executeFunction(`delete_${entity}`, args);
+      const result = await this.executeFunction(`delete_${entity}`, pk);
       console.log(JSON.stringify({ success: true, result }, null, 2));
       await this.cleanup();
     } catch (error: any) {
@@ -357,28 +320,11 @@ export class DzqlNamespace {
 
   /**
    * Lookup entity (for dropdowns/autocomplete)
-   * @example invj dzql:lookup organisations '{"query": "acme"}'
+   * @example invt dzql:lookup organisations '{"query": "acme"}'
    */
-  async lookup(_context: any, entity?: string, argsJson: string = "{}"): Promise<void> {
-    if (!entity) {
-      console.error("Error: entity name required");
-      console.error("Usage: invj dzql:lookup <entity> '<json_args>'");
-      console.error('Example: invj dzql:lookup organisations \'{"query": "acme"}\'');
-      await this.cleanup();
-      process.exit(1);
-    }
-
-    let args: any;
-    try {
-      args = JSON.parse(argsJson);
-    } catch {
-      console.error("Error: arguments must be valid JSON");
-      await this.cleanup();
-      process.exit(1);
-    }
-
+  async lookup(_context: unknown, entity: string, params: SearchParams = {}): Promise<void> {
     try {
-      const result = await this.executeFunction(`lookup_${entity}`, args);
+      const result = await this.executeFunction(`lookup_${entity}`, params);
       console.log(JSON.stringify({ success: true, result }, null, 2));
       await this.cleanup();
     } catch (error: any) {
@@ -390,28 +336,11 @@ export class DzqlNamespace {
 
   /**
    * Get subscribable snapshot
-   * @example invj dzql:subscribe venue_detail '{"venue_id": 1}'
+   * @example invt dzql:subscribe venue_detail '{"venue_id": 1}'
    */
-  async subscribe(_context: any, name?: string, argsJson: string = "{}"): Promise<void> {
-    if (!name) {
-      console.error("Error: subscribable name required");
-      console.error("Usage: invj dzql:subscribe <name> '<json_args>'");
-      console.error('Example: invj dzql:subscribe venue_detail \'{"venue_id": 1}\'');
-      await this.cleanup();
-      process.exit(1);
-    }
-
-    let args: any;
-    try {
-      args = JSON.parse(argsJson);
-    } catch {
-      console.error("Error: arguments must be valid JSON");
-      await this.cleanup();
-      process.exit(1);
-    }
-
+  async subscribe(_context: unknown, name: string, params: CallParams = {}): Promise<void> {
     try {
-      const result = await this.executeFunction(`get_${name}`, args);
+      const result = await this.executeFunction(`get_${name}`, params);
       console.log(JSON.stringify({ success: true, result }, null, 2));
       await this.cleanup();
     } catch (error: any) {
@@ -423,30 +352,12 @@ export class DzqlNamespace {
 
   /**
    * Call any function in the manifest by name
-   * @example invj dzql:call login_user '{"email": "test@example.com", "password": "secret"}'
-   * @example invj dzql:call get_venue_detail '{"venue_id": 1}'
+   * @example invt dzql:call login_user '{"email": "test@example.com", "password": "secret"}'
+   * @example invt dzql:call get_venue_detail '{"venue_id": 1}'
    */
-  async call(_context: any, funcName?: string, argsJson: string = "{}"): Promise<void> {
-    if (!funcName) {
-      console.error("Error: function name required");
-      console.error("Usage: invj dzql:call <function_name> '<json_args>'");
-      console.error('Example: invj dzql:call login_user \'{"email": "test@example.com", "password": "secret"}\'');
-      console.error('Example: invj dzql:call get_venue_detail \'{"venue_id": 1}\'');
-      await this.cleanup();
-      process.exit(1);
-    }
-
-    let args: any;
-    try {
-      args = JSON.parse(argsJson);
-    } catch {
-      console.error("Error: arguments must be valid JSON");
-      await this.cleanup();
-      process.exit(1);
-    }
-
+  async call(_context: unknown, funcName: string, params: CallParams = {}): Promise<void> {
     try {
-      const result = await this.executeFunction(funcName, args);
+      const result = await this.executeFunction(funcName, params);
       console.log(JSON.stringify({ success: true, result }, null, 2));
       await this.cleanup();
     } catch (error: any) {
@@ -458,9 +369,9 @@ export class DzqlNamespace {
 
   /**
    * List all available functions in the manifest
-   * @example invj dzql:functions
+   * @example invt dzql:functions
    */
-  async functions(_context?: any): Promise<void> {
+  async functions(_context: unknown): Promise<void> {
     try {
       const { manifest } = await this.init();
       const functions: Record<string, { args: string[]; returnType: string }> = {};

package/src/runtime/server.ts

@@ -11,7 +11,7 @@ export async function handleRequest(
   db: DBClient,
   method: string,
   params: any,
-  userId: number
+  userId: number | null
 ) {
   // 1. Check for JS function handler first (takes precedence)
   if (hasJsFunction(method)) {

package/src/runtime/ws.ts

@@ -2,15 +2,16 @@ import { ServerWebSocket } from "bun";
 import { handleRequest } from "./server.js"; // The secure router
 import { verifyToken, signToken } from "./auth.js";
 import { Database } from "./db.js";
+import { wsLogger, authLogger, logWsAccess } from "./logger.js";
 
 // WebSocket configuration
 const WS_MAX_MESSAGE_SIZE = parseInt(process.env.WS_MAX_MESSAGE_SIZE || "1048576", 10); // 1MB default
 
 interface WSContext {
-  id: string;
+  id?: string;  // Set in handleOpen
   userId?: number;
-  subscriptions: Set<string>; // Set of subscription IDs
-  lastPing: number;
+  subscriptions?: Set<string>; // Set of subscription IDs, set in handleOpen
+  lastPing?: number;  // Set in handleOpen
   token?: string; // Token passed from URL query params during upgrade
 }
 
@@ -53,7 +54,7 @@ export class WebSocketServer {
       lastPing: Date.now()
     };
     this.connections.set(id, ws);
-    console.log(`[WS] Client ${id} connected`);
+    wsLogger.info(`Client ${id} connected`);
 
     // Subscribe to global broadcast channel initially
     ws.subscribe("broadcast");
@@ -64,7 +65,7 @@ export class WebSocketServer {
       try {
         const session = await verifyToken(token);
         ws.data.userId = session.userId;
-        console.log(`[WS] Client ${id} authenticated via token as user ${session.userId}`);
+        authLogger.info(`Client ${id} authenticated via token as user ${session.userId}`);
 
         // Fetch user profile using get_users
         try {
@@ -74,13 +75,13 @@ export class WebSocketServer {
             const { password_hash, ...safeProfile } = profile;
             user = safeProfile;
           }
-        } catch (e) {
-          console.error(`[WS] Failed to fetch profile for user ${session.userId}:`, e);
+        } catch (e: any) {
+          authLogger.error(`Failed to fetch profile for user ${session.userId}:`, e.message);
           // Still authenticated, just no profile
           user = { id: session.userId };
         }
       } catch (e: any) {
-        console.log(`[WS] Client ${id} token verification failed:`, e.message);
+        authLogger.debug(`Client ${id} token verification failed:`, e.message);
         // Token invalid, user remains null (anonymous connection)
       }
     }
@@ -95,27 +96,33 @@ export class WebSocketServer {
 
   private async handleMessage(ws: ServerWebSocket<WSContext>, message: string) {
     ws.data.lastPing = Date.now(); // Update activity
+    const start = Date.now();
+    let method = "unknown";
 
     try {
       const req = JSON.parse(message);
+      method = req.method || "unknown";
 
       // Handle Ping (Client-side heartbeat)
       if (req.method === 'ping') {
-          ws.send(JSON.stringify({ id: req.id, result: 'pong' }));
-          return;
+        ws.send(JSON.stringify({ id: req.id, result: 'pong' }));
+        wsLogger.trace(`Client ${ws.data.id} ping`);
+        return;
       }
 
       // Handle Auth Handshake
       if (req.method === 'auth') {
-          try {
-              const session = await verifyToken(req.params.token);
-              ws.data.userId = session.userId;
-              ws.send(JSON.stringify({ id: req.id, result: { success: true, userId: session.userId } }));
-              console.log(`[WS] Client ${ws.data.id} authenticated as user ${session.userId}`);
-          } catch (e: any) {
-              ws.send(JSON.stringify({ id: req.id, error: { code: 'UNAUTHORIZED', message: e.message } }));
-          }
-          return;
+        try {
+          const session = await verifyToken(req.params.token);
+          ws.data.userId = session.userId;
+          ws.send(JSON.stringify({ id: req.id, result: { success: true, userId: session.userId } }));
+          authLogger.info(`Client ${ws.data.id} authenticated as user ${session.userId}`);
+          logWsAccess("CALL", "auth", Date.now() - start, session.userId);
+        } catch (e: any) {
+          ws.send(JSON.stringify({ id: req.id, error: { code: 'UNAUTHORIZED', message: e.message } }));
+          logWsAccess("CALL", "auth", Date.now() - start, null, e.message);
+        }
+        return;
       }
 
       // Require Auth for other methods?
@@ -125,76 +132,92 @@ export class WebSocketServer {
 
       // Handle RPC
       if (req.method) {
-          if (req.method.startsWith("subscribe_")) {
-             // Handle Subscription Registration
-             const subscribableName = req.method.replace("subscribe_", "");
-             const getFnName = `get_${subscribableName}`;
-
-             try {
-               // Call the get_ function to fetch initial data
-               const snapshot = await handleRequest(this.db, getFnName, req.params, userId);
-
-               // Register subscription
-               const subId = `${subscribableName}:${JSON.stringify(req.params)}`;
-               ws.data.subscriptions.add(subId);
-
-               // Return snapshot with subscription_id and schema
-               ws.send(JSON.stringify({
-                 id: req.id,
-                 result: {
-                   subscription_id: subId,
-                   data: snapshot.data,
-                   schema: snapshot.schema
-                 }
-               }));
-             } catch (e: any) {
-               ws.send(JSON.stringify({
-                 id: req.id,
-                 error: { code: e.code || 'INTERNAL_ERROR', message: e.message }
-               }));
-             }
-          } else {
-             // Normal Function Call
-             const result = await handleRequest(this.db, req.method, req.params, userId);
-
-             // Auto-generate token for auth methods
-             if (req.method === 'login_user' || req.method === 'register_user') {
-                 const token = await signToken({ user_id: result.user_id, role: 'user' });
-                 // Update connection's userId for subsequent calls
-                 ws.data.userId = result.user_id;
-                 // Return profile + token
-                 ws.send(JSON.stringify({ id: req.id, result: { ...result, token } }));
-             } else {
-                 ws.send(JSON.stringify({ id: req.id, result }));
-             }
+        if (req.method.startsWith("subscribe_")) {
+          // Handle Subscription Registration
+          const subscribableName = req.method.replace("subscribe_", "");
+          const getFnName = `get_${subscribableName}`;
+
+          try {
+            // Call the get_ function to fetch initial data
+            const snapshot = await handleRequest(this.db, getFnName, req.params, userId);
+
+            // Register subscription
+            const subId = `${subscribableName}:${JSON.stringify(req.params)}`;
+            ws.data.subscriptions?.add(subId);
+
+            // Return snapshot with subscription_id and schema
+            ws.send(JSON.stringify({
+              id: req.id,
+              result: {
+                subscription_id: subId,
+                data: snapshot.data,
+                schema: snapshot.schema
+              }
+            }));
+
+            logWsAccess("SUB", req.method, Date.now() - start, userId);
+          } catch (e: any) {
+            ws.send(JSON.stringify({
+              id: req.id,
+              error: { code: e.code || 'INTERNAL_ERROR', message: e.message }
+            }));
+            logWsAccess("SUB", req.method, Date.now() - start, userId, e.message);
           }
+        } else {
+          // Normal Function Call
+          try {
+            const result = await handleRequest(this.db, req.method, req.params, userId);
+
+            // Auto-generate token for auth methods
+            if (req.method === 'login_user' || req.method === 'register_user') {
+              const token = await signToken({ user_id: result.user_id, role: 'user' });
+              // Update connection's userId for subsequent calls
+              ws.data.userId = result.user_id;
+              // Return profile + token
+              ws.send(JSON.stringify({ id: req.id, result: { ...result, token } }));
+              logWsAccess("CALL", req.method, Date.now() - start, result.user_id);
+            } else {
+              ws.send(JSON.stringify({ id: req.id, result }));
+              logWsAccess("CALL", req.method, Date.now() - start, userId);
+            }
+          } catch (e: any) {
+            ws.send(JSON.stringify({
+              id: req.id,
+              error: { code: e.code || 'INTERNAL_ERROR', message: e.message }
+            }));
+            logWsAccess("CALL", req.method, Date.now() - start, userId, e.message);
+          }
+        }
       }
 
     } catch (e: any) {
-      console.error(`[WS] Error processing message from ${ws.data.id}:`, e);
+      wsLogger.error(`Error processing message from ${ws.data.id}:`, e.message);
+      logWsAccess("CALL", method, Date.now() - start, ws.data.userId, e.message);
       // Try to send error back if JSON parse didn't fail
       try {
-          const reqId = JSON.parse(message).id;
-          ws.send(JSON.stringify({ id: reqId, error: { code: 'INTERNAL_ERROR', message: e.message } }));
+        const reqId = JSON.parse(message).id;
+        ws.send(JSON.stringify({ id: reqId, error: { code: 'INTERNAL_ERROR', message: e.message } }));
       } catch (ignore) {}
     }
   }
 
   private handleClose(ws: ServerWebSocket<WSContext>) {
-    this.connections.delete(ws.data.id);
-    console.log(`[WS] Client ${ws.data.id} disconnected`);
+    if (ws.data.id) {
+      this.connections.delete(ws.data.id);
+    }
+    wsLogger.info(`Client ${ws.data.id} disconnected`);
   }
 
   public broadcast(message: string) {
-      // Use Bun's native publish for efficiency
-      // 'broadcast' topic is subscribed by all on connect
-      // In V2, we might have specific topics per subscription key
-      // server.publish("broadcast", message);
-      // Since this class doesn't hold the 'server' instance directly,
-      // we iterate or need to pass server in.
-      // For now, iteration is fine for prototype.
-      for (const ws of this.connections.values()) {
-          ws.send(message);
-      }
+    // Use Bun's native publish for efficiency
+    // 'broadcast' topic is subscribed by all on connect
+    // In V2, we might have specific topics per subscription key
+    // server.publish("broadcast", message);
+    // Since this class doesn't hold the 'server' instance directly,
+    // we iterate or need to pass server in.
+    // For now, iteration is fine for prototype.
+    for (const ws of this.connections.values()) {
+      ws.send(message);
+    }
   }
 }

package/src/shared/ir.ts

@@ -12,7 +12,7 @@ export interface GraphRuleActionConfig {
   target?: string;           // Target entity for update/delete actions
   name?: string;             // Reactor name for reactor type
   function?: string;         // Function name for validate/execute
-  data?: Record<string, string>;   // Data for create/update (field -> @variable)
+  data?: Record<string, string | null>;   // Data for create/update (field -> @variable or null)
   match?: Record<string, string>;  // Match condition for update/delete
   params?: Record<string, string>; // Parameters for reactor/validate/execute
   error_message?: string;    // Error message for validate
@@ -30,6 +30,7 @@ export interface IncludeConfig {
   entity: string;
   filter?: Record<string, string>;
   includes?: Record<string, string | IncludeConfig>;
+  temporal?: boolean;  // Only include active temporal records
 }
 
 /** Many-to-many relationship configuration */
@@ -160,7 +161,7 @@ export interface GraphRuleIR {
   ruleName?: string; // The name of the rule (for comments)
   description?: string; // Human-readable description
   condition?: string; // e.g., "@before.status = 'draft' AND @after.status = 'posted'"
-  params: Record<string, string>; // Data for create, or params for reactor/validate/execute
+  params: Record<string, string | null>; // Data for create, or params for reactor/validate/execute
   match?: Record<string, string>; // WHERE clause for update/delete actions
   error_message?: string; // Error message for validate action
 }
@@ -171,6 +172,7 @@ export interface SubscribableIR {
   root: {
     entity: string;
     key: string;
+    filter?: Record<string, string | boolean | number>;
   };
   includes: Record<string, IncludeIR>;
   scopeTables: string[];