nsa-sheets-db-builder 4.0.0

package/libs/spreadsheets_db.ts

@@ -0,0 +1,4406 @@
+// ========================================
+// System Table Definitions
+// ========================================
+
+/**
+ * Default system table configurations
+ * Only __sys__tables__ is needed - used for runtime state (counters, hashes, metadata)
+ * NOTE: __sys__rbac__ and __sys__notification_rules__ are now obsolete (defined in code)
+ */
+const SYSTEM_TABLES: { [tableName: string]: Partial<TableConfig> } = {
+  __sys__tables__: {
+    sheetName: '__sys__tables__',
+    schema: {
+      id: { type: 'string', primaryKey: true, required: true },
+      table_name: { type: 'string', required: true },
+      spreadsheet_id: { type: 'string', required: true },
+      sheet_name: { type: 'string', required: true },
+      counter: { type: 'number', defaultValue: 0 },
+      last_update: { type: 'datetime' },
+      last_update_hash: { type: 'string' },
+      __audit__: { type: 'object' },
+      __archived__: { type: 'boolean', defaultValue: false }
+    },
+    idGenerator: 'STATIC_UUID',
+    readOnly: false,
+    deleteMode: 'soft'
+  }
+};
+
+// ========================================
+// Type Definitions
+// ========================================
+
+type DELETE_MODE_V2 = 'soft' | 'hard' | 'notallowed';
+
+type ColumnType = 'string' | 'number' | 'boolean' | 'datetime' | 'timestamp' | 'object' | 'array' | 'arrayOfObjects';
+
+interface AuditData {
+  created_at?: string;
+  created_by?: string;
+  updated_at?: string;
+  updated_by?: string;
+  operation_hash?: string;
+  version?: number;
+}
+
+interface SchemaColumn {
+  type: ColumnType;
+  primaryKey?: boolean;
+  foreignKey?: string; // Format: "tableName.columnName"
+  required?: boolean;
+  defaultValue?: any;
+  prefixed?: boolean; // For values that should be prefixed with '
+  outputFormat?: string; // For datetime: format string (e.g., 'yyyy-MM-dd', 'yyyy-MM-dd HH:mm:ss')
+  timezone?: string; // For datetime: timezone (e.g., 'UTC', 'America/New_York', 'Europe/Warsaw')
+}
+
+interface TableSchema {
+  [columnName: string]: SchemaColumn;
+}
+
+interface TableConfig {
+  spreadsheetId: string;
+  sheetName: string;
+  schema: TableSchema;
+  options?: TableOptions;
+  idGenerator?: string;
+  upsertStrategy?: 'not_allowed' | 'upsert'; // Default: not_allowed
+  readOnly?: boolean;
+  deleteMode?: DELETE_MODE_V2;
+}
+
+// No longer needed - tables always have header at row 1, data starting at row 2
+// interface TableOptions {}
+
+interface TablePermissions {
+  create: boolean;
+  read: boolean;
+  update: boolean;
+  delete: boolean;
+  query: boolean;
+}
+
+interface RolePermissions {
+  tables: {
+    [tableName: string]: TablePermissions;
+  };
+}
+
+interface RelationConfig {
+  table: string; // Related table name
+  foreignKey: string; // Field in current table that references related table
+  relatedKey?: string; // Field in related table (default: 'id')
+  as: string; // Property name in result object
+  multiple?: boolean; // If true, returns array; if false, returns single object
+  fields?: string[]; // Optional: specific fields to include from related table
+}
+
+interface TableViewProfile {
+  // Query restrictions for read operations (getData, getById)
+  readQuery?: string; // SQL WHERE clause to filter records
+  // Field visibility for read operations
+  visibleFields?: string[]; // Whitelist of fields visible in reads
+  excludeFields?: string[]; // Blacklist of fields hidden in reads
+  // Field restrictions for write operations (create, update)
+  writableFields?: string[]; // Only these fields can be created/updated
+  readOnlyFields?: string[]; // These fields cannot be modified
+  // Relations to include in read operations
+  relations?: RelationConfig[]; // Related data to join
+}
+
+interface RoleViewProfile {
+  tables: {
+    [tableName: string]: TableViewProfile;
+  };
+}
+
+interface DBConfigV2 {
+  metadataSpreadsheetId: string; // Spreadsheet containing __sys__tables__ metadata (source of truth for table definitions)
+  tableCaching?: {
+    enabled: boolean;
+    refreshIntervalHours: number;
+  };
+  rolePermissions?: { [roleName: string]: RolePermissions };
+  roleViews?: { [roleName: string]: RoleViewProfile }; // Role-based view overlays (superadmin exempt)
+  systemTables?: { [tableName: string]: Omit<TableConfig, 'spreadsheetId'> }; // System tables (auto-assigned metadataSpreadsheetId)
+  tables?: { [tableName: string]: TableConfig }; // Application tables with full configs
+  triggers?: any[]; // Database triggers for CRUD operations (code-based configuration)
+  notificationConfig?: any; // DEPRECATED - kept for backward compatibility, use triggers instead
+}
+
+interface CachedUser {
+  id: string;
+  name: string;
+  email: string;
+  role: string;
+}
+
+// Runtime state cached from __sys__tables__ (minimal data only)
+interface TableRuntimeState {
+  tableName: string;
+  spreadsheetId: string;
+  sheetName: string;
+  counter: number;
+  lastUpdate: number; // Unix timestamp in milliseconds
+  lastUpdateHash: string;
+}
+
+interface TableMetadataRow {
+  table_name: string;
+  spreadsheet_id: string;
+  sheet_name: string;
+  schema: string; // JSON stringified
+  counter: number;
+  last_update: string;
+  last_update_hash: string;
+  id_generator: string;
+  read_only: boolean;
+  delete_mode: string;
+  created_at: string;
+  updated_at: string;
+  __archived__: boolean;
+}
+
+interface EntityLock {
+  tableName: string;
+  operation: 'create' | 'update' | 'delete';
+  entityId: string;
+  lockedAt: number;
+  lockedBy: string;
+}
+
+// ========================================
+// Date Formatting Helper
+// ========================================
+
+/**
+ * Formats a Date object to simple string format: "YYYY-MM-DD HH:mm:ss"
+ * @param date - Date object to format (defaults to current date/time)
+ * @returns Formatted date string
+ */
+function formatDateTime(date: Date = new Date()): string {
+  const year = date.getFullYear();
+  const month = String(date.getMonth() + 1).padStart(2, '0');
+  const day = String(date.getDate()).padStart(2, '0');
+  const hours = String(date.getHours()).padStart(2, '0');
+  const minutes = String(date.getMinutes()).padStart(2, '0');
+  const seconds = String(date.getSeconds()).padStart(2, '0');
+
+  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}`;
+}
+
+// ========================================
+// TableV2 Class
+// ========================================
+
+class TableV2 {
+  private spreadsheetId: string;
+  private sheetName: string;
+  private tableName: string;
+  private schema: TableSchema;
+  private primaryKey: string;
+  private isReadOnly: boolean;
+  private deleteMode: DELETE_MODE_V2;
+  private idGenerator: any;
+  private logger: GASLoggerV2 | null;
+
+  // Runtime state from __sys__tables__
+  private runtimeState: TableRuntimeState;
+  private metadataSpreadsheetId: string;
+
+  // Reference to DBV2 for triggering notification rules
+  private db: DBV2 | null = null;
+
+  // Cached spreadsheet and sheet objects
+  private spreadsheet: GoogleAppsScript.Spreadsheet.Spreadsheet | null = null;
+  private sheet: GoogleAppsScript.Spreadsheet.Sheet | null = null;
+
+  // Metadata cache
+  private counter: number = 0;
+  private lastTableUpdate: string = '';
+  private lastUpdateHash: string = '';
+  private tableSize: number = 0;
+  private config: any = {};
+
+  constructor(
+    tableName: string,
+    tableConfig: TableConfig,
+    runtimeState: TableRuntimeState,
+    metadataSpreadsheetId: string,
+    logger: GASLoggerV2 | null = null,
+    db: DBV2 | null = null
+  ) {
+    this.tableName = tableName;
+    this.spreadsheetId = tableConfig.spreadsheetId;
+    this.sheetName = tableConfig.sheetName;
+    this.schema = tableConfig.schema;
+    this.runtimeState = runtimeState;
+    this.metadataSpreadsheetId = metadataSpreadsheetId;
+    this.isReadOnly = tableConfig.readOnly || false;
+    this.deleteMode = tableConfig.deleteMode || 'notallowed';
+    this.logger = logger;
+    this.db = db;
+
+    // Find primary key from schema
+    this.primaryKey = '';
+    for (const [columnName, columnDef] of Object.entries(this.schema)) {
+      if (columnDef.primaryKey) {
+        this.primaryKey = columnName;
+        break;
+      }
+    }
+
+    if (!this.primaryKey) {
+      throw new GASErrorV2(
+        `No primary key defined in schema for table '${tableName}'`,
+        'TableV2.constructor',
+        { tableName, schema: this.schema },
+        [],
+        logger?.getTraceId()
+      );
+    }
+  }
+
+  private hasAuditField(): boolean {
+    return '__audit__' in this.schema;
+  }
+
+  private createAuditData(operation: 'create' | 'update', oldData?: any, newData?: any): AuditData {
+    const now = formatDateTime();
+    const user = Session.getActiveUser().getEmail();
+
+    // Create hash from the data being modified
+    const dataForHash = JSON.stringify({
+      operation,
+      timestamp: now,
+      data: newData,
+      traceId: this.logger?.getTraceId()
+    });
+    const operationHash = UUID.generate(dataForHash);
+
+    if (operation === 'create') {
+      return {
+        created_at: now,
+        created_by: user,
+        updated_at: now,
+        updated_by: user,
+        operation_hash: operationHash,
+        version: 1
+      };
+    } else {
+      // Update operation
+      const oldAudit: AuditData = oldData || {
+        version: 0
+      };
+      return {
+        ...oldAudit,
+        updated_at: now,
+        updated_by: user,
+        operation_hash: operationHash,
+        version: (oldAudit.version || 0) + 1
+      };
+    }
+  }
+
+  setIdGenerator(idGenerator: any): void {
+    this.idGenerator = idGenerator;
+  }
+
+  private getSpreadsheet(): GoogleAppsScript.Spreadsheet.Spreadsheet {
+    if (!this.spreadsheet) {
+      this.spreadsheet = SpreadsheetApp.openById(this.spreadsheetId);
+    }
+    return this.spreadsheet;
+  }
+
+  private getSheet(): GoogleAppsScript.Spreadsheet.Sheet {
+    if (!this.sheet) {
+      const ss = this.getSpreadsheet();
+      this.sheet = ss.getSheetByName(this.sheetName);
+      if (!this.sheet) {
+        throw new GASErrorV2(
+          `Sheet '${this.sheetName}' not found in spreadsheet ${this.spreadsheetId}`,
+          'TableV2.getSheet',
+          { tableName: this.tableName, sheetName: this.sheetName }, this.logger?.getTraceId()
+        );
+      }
+    }
+    return this.sheet;
+  }
+
+  private initializeTableDetails(): void {
+    try {
+      const sheet = this.getSheet();
+      const schemaSize = Object.keys(this.schema).length;
+      // New format: Row 1 is header only, no metadata rows
+      // All metadata (counter, last_update, etc.) comes from __sys__tables__ via runtime state
+      // Data always starts at row 2
+      this.tableSize = this.getLastRow() - 1;
+      this.counter = this.runtimeState.counter;
+      this.lastTableUpdate = this.runtimeState.last_update;
+      this.lastUpdateHash = this.runtimeState.last_update_hash;
+      this.config = {};  // No per-table config anymore (all in dbConfig)
+
+      this.logger?.debug('TableV2.initializeTableDetails', 'Table details initialized', {
+        tableName: this.tableName,
+        tableSize: this.tableSize,
+        counter: this.counter,
+      });
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        "Failed to initialize table details",
+        "TableV2.initializeTableDetails",
+        { tableName: this.tableName },
+        this.logger?.getTraceId()
+      );
+    }
+  }
+
+  private getLastRow(): number {
+    try {
+      const sheet = this.getSheet();
+      return sheet.getMaxRows();
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        "Failed to get last row",
+        "TableV2.getLastRow",
+        { tableName: this.tableName },
+        this.logger?.getTraceId()
+      );
+      return 0;
+    }
+  }
+
+  getTableName(): string {
+    return this.tableName;
+  }
+
+  getSchema(): TableSchema {
+    return this.schema;
+  }
+
+  getCounter(): number {
+    try {
+      this.initializeTableDetails();
+      return this.counter;
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        "Failed to get counter",
+        "TableV2.getCounter",
+        { tableName: this.tableName },
+        this.logger?.getTraceId()
+      );
+      return 0;
+    }
+  }
+
+  getLatestUpdate(): string {
+    try {
+      this.initializeTableDetails();
+      return this.lastTableUpdate;
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        "Failed to get latest update",
+        "TableV2.getLatestUpdate",
+        { tableName: this.tableName },
+        this.logger?.getTraceId()
+      );
+      return '';
+    }
+  }
+
+  getFreshness(): { lastUpdate: string; lastUpdateHash: string } {
+    try {
+      this.initializeTableDetails();
+      return {
+        lastUpdate: this.lastTableUpdate,
+        lastUpdateHash: this.lastUpdateHash
+      };
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        "Failed to get freshness",
+        "TableV2.getFreshness",
+        { tableName: this.tableName },
+        this.logger?.getTraceId()
+      );
+      return { lastUpdate: '', lastUpdateHash: '' };
+    }
+  }
+
+  getData(pageStart: number = 0, pageSize: number = 0): any {
+    const start = new Date().getTime();
+    try {
+      console.log('[TableV2.getData] START - table:', this.tableName);
+      console.log('[TableV2.getData] spreadsheetId:', JSON.stringify(this.spreadsheetId));
+      console.log('[TableV2.getData] sheetName:', JSON.stringify(this.sheetName));
+
+      this.initializeTableDetails();
+
+      console.log('[TableV2.getData] After initializeTableDetails - spreadsheetId:', JSON.stringify(this.spreadsheetId));
+      console.log('[TableV2.getData] After initializeTableDetails - sheetName:', JSON.stringify(this.sheetName));
+
+      const sheet = this.getSheet();
+      console.log('[TableV2.getData] Got sheet:', sheet ? 'SUCCESS' : 'NULL');
+      if (sheet) {
+        console.log('[TableV2.getData] Sheet name:', sheet.getName());
+      }
+
+      const lastRow = this.getLastRow();
+      console.log('[TableV2.getData] lastRow:', lastRow);
+
+      this.logger?.debug('TableV2.getData', `Fetching data for table ${this.tableName}...`, {
+        pageStart,
+        pageSize,
+        lastRow,
+      });
+
+      // Row 1 is header, data starts at row 2
+      console.log('[TableV2.getData] lastRow value:', lastRow, 'type:', typeof lastRow);
+      console.log('[TableV2.getData] pageStart:', pageStart, 'type:', typeof pageStart);
+      console.log('[TableV2.getData] pageSize:', pageSize, 'type:', typeof pageSize);
+
+      if (lastRow - 1 === 0) {
+        this.logger?.warn('TableV2.getData', `Table '${this.tableName}' is empty (no data rows)`, {});
+        return {
+          schema: this.schema,
+          data: [],
+        };
+      }
+
+      let actualPageStart = pageStart;
+      let actualPageSize =
+        pageSize === 0
+          ? lastRow - 1
+          : Math.min(pageSize, lastRow - 1);
+
+      console.log('[TableV2.getData] Calculated actualPageStart:', actualPageStart, 'type:', typeof actualPageStart);
+      console.log('[TableV2.getData] Calculated actualPageSize:', actualPageSize, 'type:', typeof actualPageSize);
+
+      if (actualPageStart < 0 || actualPageSize <= 0 || actualPageStart > lastRow) {
+        throw new GASErrorV2(
+          'Invalid page parameters',
+          'TableV2.getData',
+          { pageStart, pageSize, lastRow }, this.logger?.getTraceId()
+        );
+      }
+
+      const schemaSize = Object.keys(this.schema).length;
+
+      console.log('[TableV2.getData] Before getRange - actualPageStart:', actualPageStart, 'type:', typeof actualPageStart);
+      console.log('[TableV2.getData] Before getRange - actualPageSize:', actualPageSize, 'type:', typeof actualPageSize);
+      console.log('[TableV2.getData] Before getRange - schemaSize:', schemaSize, 'type:', typeof schemaSize);
+      console.log('[TableV2.getData] Before getRange - this.schema:', JSON.stringify(this.schema));
+
+      const rowData = sheet
+        .getRange(1 + actualPageStart + 1, 1, actualPageSize, schemaSize)  // 1 (header) + actualPageStart + 1
+        .getValues();
+
+      if (rowData.length === 0) {
+        this.logger?.warn('TableV2.getData', `Table ${this.tableName} is empty`, {});
+        return {
+          schema: this.schema,
+          data: [],
+        };
+      }
+
+      const outputData = this.toArrayOfObjects(rowData);
+      return {
+        schema: this.schema,
+        data: outputData,
+      };
+    } catch (error) {
+      console.log('[TableV2.getData] ERROR caught:', error);
+      console.log('[TableV2.getData] Error details:', JSON.stringify({
+        message: error.message,
+        stack: error.stack,
+        toString: error.toString(),
+        spreadsheetId: this.spreadsheetId,
+        sheetName: this.sheetName,
+        tableName: this.tableName
+      }));
+
+      GASErrorV2.handleError(
+        error,
+        "Failed to get data",
+        "TableV2.getData",
+        { pageStart, pageSize, tableName: this.tableName },
+        this.logger?.getTraceId()
+      );
+      return null;
+    }
+  }
+
+  getById(id: string): any {
+    try {
+      this.initializeTableDetails();
+      const rowIndex = this.getRowIndexById(id);
+      if (rowIndex === -1) {
+        this.logger?.info('TableV2.getById', `No data found for id '${id}'`, {});
+        return null;
+      }
+
+      const sheet = this.getSheet();
+      const rowData = sheet.getRange(rowIndex, 1, 1, Object.keys(this.schema).length).getValues()[0];
+      const dataAsDict = this.toArrayOfObjects([rowData])[0];
+      this.logger?.info('TableV2.getById', `Data retrieved for ID ${id}`, { data: dataAsDict });
+      return dataAsDict;
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        "Failed to get data by ID",
+        "TableV2.getById",
+        { id, tableName: this.tableName },
+        this.logger?.getTraceId()
+      );
+      return null;
+    }
+  }
+
+  create(entry: { [key: string]: any }): any {
+    console.log('[TableV2.create] START', { tableName: this.tableName, entry });
+
+    if (this.isReadOnly) {
+      throw new GASErrorV2(
+        'Table is read-only',
+        'TableV2.create',
+        { tableName: this.tableName }, this.logger?.getTraceId()
+      );
+    }
+
+    if (entry === undefined || Object.keys(entry).length === 0) {
+      throw new GASErrorV2(
+        'No new item data provided',
+        'TableV2.create',
+        {}, this.logger?.getTraceId()
+      );
+    }
+
+    try {
+      console.log('[TableV2.create] Calling initializeTableDetails()');
+      this.initializeTableDetails();
+      console.log('[TableV2.create] initializeTableDetails() completed, calling _create()');
+      const result = this._create(entry);
+      console.log('[TableV2.create] _create() returned', { result });
+      const id = result[this.primaryKey];
+
+      // Trigger database triggers after successful create
+      if (this.db) {
+        try {
+          this.db.triggerDatabaseTriggers(this.tableName, 'create', result);
+        } catch (triggerError) {
+          // Log but don't fail the create operation
+          this.logger?.warn('TableV2.create', `Database triggers failed: ${triggerError.toString()}`, { error: triggerError });
+        }
+      } else {
+        this.logger?.warn('TableV2.create', 'No DB reference available for triggers');
+      }
+
+      return { id, data: result };
+    } catch (error) {
+      console.log('[TableV2.create] ERROR caught:', error);
+      console.log('[TableV2.create] Error details:', {
+        message: error.message,
+        stack: error.stack,
+        toString: error.toString()
+      });
+      GASErrorV2.handleError(
+        error,
+        `Unexpected error during create operation`,
+        "TableV2.create",
+        { request: entry, tableName: this.tableName },
+        this.logger?.getTraceId()
+      );
+      return null;
+    }
+  }
+
+  private _create(entry: { [key: string]: any }): any {
+    try {
+      let id: any;
+      const counterState = this.updateCounter();
+
+      switch (this.idGenerator.name) {
+        case 'DEFAULT':
+          id = this.idGenerator.nextId(counterState);
+          break;
+        case 'EXTERNAL':
+          if (!entry[this.primaryKey]) {
+            throw new GASErrorV2(
+              `External ID not provided in entry`,
+              'TableV2._create',
+              {}, this.logger?.getTraceId()
+            );
+          }
+          id = entry[this.primaryKey];
+          break;
+        default:
+          if (!this.idGenerator || typeof this.idGenerator.class.generate !== 'function') {
+            throw new GASErrorV2(
+              `Invalid ID generator configuration for table`,
+              'TableV2._create',
+              {}, this.logger?.getTraceId()
+            );
+          }
+          const params = this.idGenerator.paramsFn(entry, counterState);
+          id = this.idGenerator.class.generate(...params);
+      }
+
+      const typedId = this.castPrimaryKey(id);
+      if (!typedId) {
+        throw new GASErrorV2(
+          'Failed to generate or cast primary key',
+          'TableV2._create',
+          {}, this.logger?.getTraceId()
+        );
+      }
+
+      if (!this.checkIfIdUnique(typedId)) {
+        throw new GASErrorV2(
+          `ID ${typedId} is not unique, skipping creation`,
+          'TableV2._create',
+          {}, this.logger?.getTraceId()
+        );
+      }
+
+      const hasAudit = this.hasAuditField();
+      const auditData = hasAudit ? this.createAuditData('create', null, entry) : null;
+
+      const newRow = new Array(Object.keys(this.schema).length);
+      let index = 0;
+      for (const [columnName, columnDef] of Object.entries(this.schema)) {
+        if (columnName === this.primaryKey) {
+          newRow[index] = typedId.toString();
+        } else if (columnName === '__audit__') {
+          // Inject audit data
+          newRow[index] = auditData ? JSON.stringify(auditData) : '';
+        } else if (entry.hasOwnProperty(columnName)) {
+          if (columnDef.prefixed) {
+            newRow[index] = `'${entry[columnName]}`;
+          } else {
+            // Serialize objects/arrays to JSON if type is 'object', 'array', or 'arrayOfObjects'
+            if ((columnDef.type === 'object' || columnDef.type === 'array' || columnDef.type === 'arrayOfObjects') && typeof entry[columnName] === 'object' && entry[columnName] !== null) {
+              newRow[index] = JSON.stringify(entry[columnName]);
+            } else {
+              newRow[index] = this.castValue(entry[columnName], columnDef.type);
+            }
+          }
+        } else if (columnName === '__created_at__' || columnName === '__last_updated_at__') {
+          // Legacy support for old audit fields
+          newRow[index] = formatDateTime();
+        } else if (columnName === '__last_updated_by__') {
+          newRow[index] = Session.getActiveUser().getEmail();
+        } else if (columnName === '__archived__') {
+          newRow[index] = entry[columnName] !== undefined ? entry[columnName] : false;
+        } else if (columnDef.defaultValue !== undefined) {
+          newRow[index] = columnDef.defaultValue;
+        } else {
+          newRow[index] = '';
+        }
+        index++;
+      }
+
+      const sheet = this.getSheet();
+      sheet.appendRow(newRow);
+      this.updateLastTableUpdateInfo(formatDateTime(), { entry, generatedId: typedId });
+
+      const newRowAsDict = this.toArrayOfObjects([newRow])[0];
+      this.logger?.info('TableV2._create', `Row inserted successfully with ID ${typedId}`, {});
+      return newRowAsDict;
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        `Unexpected error when executing _create on table`,
+        "TableV2._create",
+        { request: entry, tableName: this.tableName },
+        this.logger?.getTraceId()
+      );
+      return null;
+    }
+  }
+
+  update(id: any, data: { [key: string]: any }): any {
+    if (this.isReadOnly) {
+      throw new GASErrorV2(
+        'Table is read-only',
+        'TableV2.update',
+        { tableName: this.tableName }, this.logger?.getTraceId()
+      );
+    }
+
+    if (id === undefined || id === '') {
+      throw new GASErrorV2(
+        'No primary key provided for update',
+        'TableV2.update',
+        {}, this.logger?.getTraceId()
+      );
+    }
+
+    if (data === undefined || Object.keys(data).length === 0) {
+      throw new GASErrorV2(
+        'No update data provided',
+        'TableV2.update',
+        {}, this.logger?.getTraceId()
+      );
+    }
+
+    try {
+      this.initializeTableDetails();
+      const result = this._update(id, data);
+      if (result === undefined) {
+        this.logger?.warn('TableV2.update', `No data found for ID '${id}' in table ${this.tableName}`, {});
+        return undefined;
+      }
+
+      // Trigger database triggers after successful update
+      if (this.db) {
+        try {
+          this.db.triggerDatabaseTriggers(this.tableName, 'update', result);
+        } catch (triggerError) {
+          this.logger?.warn('TableV2.update', `Database triggers failed: ${triggerError.toString()}`, { error: triggerError });
+        }
+      }
+
+      return { id: result[this.primaryKey], data: result };
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        `Could not update table`,
+        "TableV2.update",
+        { id, request: data, tableName: this.tableName },
+        this.logger?.getTraceId()
+      );
+      return null;
+    }
+  }
+
+  private _update(id: any, data: { [key: string]: any }): any {
+    try {
+      const typedId = this.castPrimaryKey(id);
+
+      if (!typedId) {
+        throw new GASErrorV2(
+          `Invalid primary key value: ${id}`,
+          'TableV2._update',
+          {}, this.logger?.getTraceId()
+        );
+      }
+
+      const rowIndex = this.getRowIndexById(typedId);
+      if (rowIndex === -1) {
+        return undefined;
+      }
+
+      const sheet = this.getSheet();
+      const rowData = sheet.getRange(rowIndex, 1, 1, Object.keys(this.schema).length).getValues()[0];
+
+      // Get existing audit data before update
+      const hasAudit = this.hasAuditField();
+      let existingAuditData: AuditData | null = null;
+      if (hasAudit) {
+        const auditIndex = Object.keys(this.schema).indexOf('__audit__');
+        try {
+          existingAuditData = JSON.parse(rowData[auditIndex]) as AuditData;
+        } catch {
+          existingAuditData = null;
+        }
+      }
+
+      // Update the row with new data
+      let index = 0;
+      for (const [columnName, columnDef] of Object.entries(this.schema)) {
+        if (columnName === '__audit__') {
+          // Update audit data
+          const newAuditData = this.createAuditData('update', existingAuditData, data);
+          rowData[index] = JSON.stringify(newAuditData);
+        } else if (data.hasOwnProperty(columnName)) {
+          if (columnDef.prefixed) {
+            rowData[index] = `'${data[columnName]}`;
+          } else {
+            // Serialize objects/arrays to JSON if type is 'object', 'array', or 'arrayOfObjects'
+            if ((columnDef.type === 'object' || columnDef.type === 'array' || columnDef.type === 'arrayOfObjects') && typeof data[columnName] === 'object' && data[columnName] !== null) {
+              rowData[index] = JSON.stringify(data[columnName]);
+            } else {
+              rowData[index] = this.castValue(data[columnName], columnDef.type);
+            }
+          }
+        }
+        index++;
+      }
+
+      // Legacy support: Update old audit fields if they exist
+      if (this.schema['__last_updated_at__']) {
+        const lastUpdatedIndex = Object.keys(this.schema).indexOf('__last_updated_at__');
+        rowData[lastUpdatedIndex] = formatDateTime();
+      }
+      if (this.schema['__last_updated_by__']) {
+        const lastUpdatedByIndex = Object.keys(this.schema).indexOf('__last_updated_by__');
+        rowData[lastUpdatedByIndex] = Session.getActiveUser().getEmail();
+      }
+
+      sheet.getRange(rowIndex, 1, 1, rowData.length).setValues([rowData.map((cell: any) => cell.toString())]);
+      this.updateLastTableUpdateInfo(formatDateTime(), { id, data, rowIndexInSheet: rowIndex });
+
+      const updatedEntry = this.toArrayOfObjects([rowData])[0];
+      this.logger?.info('TableV2._update', `Entry with ID ${typedId} updated successfully`, { data: updatedEntry });
+      return updatedEntry;
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        `Unexpected error when executing _update`,
+        "TableV2._update",
+        { id, request: data, tableName: this.tableName },
+        this.logger?.getTraceId()
+      );
+      return null;
+    }
+  }
+
+  delete(id: any): any {
+    if (this.isReadOnly) {
+      throw new GASErrorV2(
+        'Table is read-only',
+        'TableV2.delete',
+        { tableName: this.tableName }, this.logger?.getTraceId()
+      );
+    }
+
+    if (id === undefined || id === '') {
+      throw new GASErrorV2(
+        `No ${this.primaryKey} value provided for delete in table`,
+        'TableV2.delete',
+        {}, this.logger?.getTraceId()
+      );
+    }
+
+    try {
+      this.initializeTableDetails();
+      const result = this._delete(id);
+      if (result === undefined) {
+        this.logger?.warn('TableV2.delete', `No data found for ID '${id}' in table ${this.tableName}`, {});
+        return undefined;
+      }
+      return { id: result };
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        `Unexpected error during delete operation`,
+        "TableV2.delete",
+        { request: id, tableName: this.tableName },
+        this.logger?.getTraceId()
+      );
+      return null;
+    }
+  }
+
+  private _delete(id: any): any {
+    try {
+      const typedId = this.castPrimaryKey(id);
+      if (this.deleteMode === 'notallowed') {
+        throw new GASErrorV2(
+          `Delete operation not allowed on the table`,
+          'TableV2._delete',
+          {}, this.logger?.getTraceId()
+        );
+      } else if (this.deleteMode === 'soft') {
+        return this.softDelete(typedId);
+      } else if (this.deleteMode === 'hard') {
+        return this.hardDelete(typedId);
+      } else {
+        throw new GASErrorV2(
+          `Invalid delete mode specified`,
+          'TableV2._delete',
+          {}, this.logger?.getTraceId()
+        );
+      }
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        `Unexpected error when executing _delete on table`,
+        "TableV2._delete",
+        { request: id, tableName: this.tableName },
+        this.logger?.getTraceId()
+      );
+      return null;
+    }
+  }
+
+  private softDelete(id: any): any {
+    try {
+      if (!this.schema.hasOwnProperty('__archived__')) {
+        throw new GASErrorV2(
+          `Soft delete not possible, "__archived__" field not found in schema`,
+          'TableV2.softDelete',
+          {}, this.logger?.getTraceId()
+        );
+      }
+      const rowIndex = this.getRowIndexById(id);
+      if (rowIndex === -1) {
+        this.logger?.warn('TableV2.softDelete', `No data found for ID '${id}' in table ${this.tableName}`, {});
+        return undefined;
+      }
+
+      const sheet = this.getSheet();
+      const archivedColumnIndex = Object.keys(this.schema).indexOf('__archived__');
+      sheet.getRange(rowIndex, archivedColumnIndex + 1).setValue(true);
+      this.updateLastTableUpdateInfo(formatDateTime(), { id, method: 'softDelete' });
+      this.logger?.info('TableV2.softDelete', `Soft deleted row with ID '${id}' in table ${this.tableName}`, {});
+      return id;
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        `Error occurred during soft deletion`,
+        "TableV2.softDelete",
+        { request: id, tableName: this.tableName },
+        this.logger?.getTraceId()
+      );
+      return null;
+    }
+  }
+
+  private hardDelete(id: any): any {
+    try {
+      const rowIndex = this.getRowIndexById(id);
+      if (rowIndex === -1) {
+        this.logger?.warn('TableV2.hardDelete', `No data found for ID '${id}' in table ${this.tableName}`, {});
+        return undefined;
+      }
+
+      const sheet = this.getSheet();
+      sheet.deleteRow(rowIndex);
+      this.updateLastTableUpdateInfo(formatDateTime(), { id, method: 'hardDelete' });
+      this.logger?.info('TableV2.hardDelete', `Hard deleted row with ID '${id}' in table ${this.tableName}`, {});
+      return id;
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        `Error occurred during hard deletion`,
+        "TableV2.hardDelete",
+        { request: id, tableName: this.tableName },
+        this.logger?.getTraceId()
+      );
+      return null;
+    }
+  }
+
+  private updateCounter(): number {
+    // Counter is stored in __sys__tables__ for lock/concurrency control
+    // Must update spreadsheet immediately to prevent race conditions
+    try {
+      const metaSs = SpreadsheetApp.openById(this.metadataSpreadsheetId);
+      const sysTablesSheet = metaSs.getSheetByName('__sys__tables__');
+
+      if (!sysTablesSheet) {
+        throw new Error('__sys__tables__ not found');
+      }
+
+      // Find the row for this table in __sys__tables__
+      const lastRow = sysTablesSheet.getLastRow();
+      const tableNames = sysTablesSheet.getRange(2, 2, lastRow - 1, 1).getValues(); // column 2 = table_name
+
+      let rowIndex = -1;
+      for (let i = 0; i < tableNames.length; i++) {
+        if (tableNames[i][0] === this.tableName) {
+          rowIndex = i + 2; // +2 because arrays are 0-indexed and we start at row 2
+          break;
+        }
+      }
+
+      if (rowIndex === -1) {
+        throw new Error(`Table '${this.tableName}' not found in __sys__tables__`);
+      }
+
+      // Column 5 is counter, read-increment-write atomically
+      const currentCounter = sysTablesSheet.getRange(rowIndex, 5).getValue();
+      this.logger?.debug('TableV2.updateCounter', 'Read current counter value', { tableName: this.tableName, currentCounter, rowIndex });
+      const newCounter = Number(currentCounter) + 1;
+      this.logger?.debug('TableV2.updateCounter', 'Calculated new counter', { tableName: this.tableName, newCounter });
+      sysTablesSheet.getRange(rowIndex, 5).setValue(newCounter);
+
+      // Update in-memory counter
+      this.counter = newCounter;
+      this.runtimeState.counter = newCounter;
+
+      this.logger?.debug('TableV2.updateCounter', 'Counter updated', { tableName: this.tableName, finalCounter: this.counter });
+      return this.counter;
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        `Failed to update counter in __sys__tables__`,
+        "TableV2.updateCounter",
+        { tableName: this.tableName },
+        this.logger?.getTraceId()
+      );
+      // Fallback to in-memory increment
+      this.counter = this.counter + 1;
+      return this.counter;
+    }
+  }
+
+  private checkIfIdUnique(id: any): boolean {
+    try {
+      return !this.idExists(id);
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        `Failed to check if ID is unique`,
+        "TableV2.checkIfIdUnique",
+        { id, tableName: this.tableName },
+        this.logger?.getTraceId()
+      );
+      return false;
+    }
+  }
+
+  private idExists(id: any): boolean {
+    try {
+      const typedId = this.castPrimaryKey(id);
+      const primaryKeyValues = this.getPrimaryKeyValues();
+      return primaryKeyValues.includes(typedId);
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        `Failed to check if ID exists`,
+        "TableV2.idExists",
+        { id, tableName: this.tableName },
+        this.logger?.getTraceId()
+      );
+      return false;
+    }
+  }
+
+  private toArrayOfObjects(data: any[][]): object[] {
+    try {
+      const transformedData: object[] = [];
+
+      data.forEach(row => {
+        const obj: { [key: string]: any } = {};
+        let index = 0;
+        for (const [columnName, columnDef] of Object.entries(this.schema)) {
+          let value = row[index];
+
+          // Deserialize JSON fields (type: 'object', 'array', 'arrayOfObjects')
+          if ((columnDef.type === 'object' || columnDef.type === 'array' || columnDef.type === 'arrayOfObjects') && typeof value === 'string' && value.trim() !== '') {
+            try {
+              value = JSON.parse(value);
+            } catch (e) {
+              // If JSON parse fails, keep as string
+              this.logger?.warn('TableV2.toArrayOfObjects', `Failed to parse JSON for field ${columnName}`, { value });
+            }
+          }
+
+          // Convert Google Sheets boolean strings ("TRUE"/"FALSE") to actual booleans
+          if (columnDef.type === 'boolean') {
+            if (typeof value === 'string') {
+              const upperValue = value.trim().toUpperCase();
+              if (upperValue === 'TRUE') {
+                value = true;
+              } else if (upperValue === 'FALSE' || upperValue === '') {
+                // Treat empty strings and "FALSE" as false
+                value = false;
+              }
+              // If value is neither "TRUE" nor "FALSE" nor empty, keep original value
+            } else if (typeof value === 'boolean') {
+              // Already a boolean, keep as-is
+              // (This handles cases where Sheets returns actual booleans)
+            } else if (value === null || value === undefined || value === '') {
+              // Treat null/undefined/empty as false
+              value = false;
+            }
+
+            // Debug logging for boolean conversion
+            if (columnName === '__archived__' && this.tableName === 'epuap_tickets') {
+              this.logger?.debug('TableV2.toArrayOfObjects', `Boolean conversion for __archived__`, {
+                originalValue: row[index],
+                originalType: typeof row[index],
+                convertedValue: value,
+                convertedType: typeof value
+              });
+            }
+          }
+
+          // Format datetime fields based on outputFormat and timezone
+          if (columnDef.type === 'datetime' && value) {
+            // Parse JSON-stringified datetime values
+            // Google Sheets sometimes stores ISO strings as JSON strings with quotes
+            if (typeof value === 'string' && value.startsWith('"') && value.endsWith('"')) {
+              try {
+                value = JSON.parse(value);
+                this.logger?.debug('TableV2.toArrayOfObjects', `Parsed JSON-stringified datetime for ${columnName}`, {
+                  original: row[index],
+                  parsed: value
+                });
+              } catch (e) {
+                // If parsing fails, use as-is
+                this.logger?.warn('TableV2.toArrayOfObjects', `Failed to parse JSON datetime for ${columnName}`, { value });
+              }
+            }
+
+            if (columnDef.outputFormat) {
+              try {
+                value = this.formatDateTime(value, columnDef.outputFormat, columnDef.timezone);
+              } catch (e) {
+                this.logger?.warn('TableV2.toArrayOfObjects', `Failed to format datetime for field ${columnName}`, { value });
+              }
+            }
+          }
+
+          obj[columnName] = value;
+          index++;
+        }
+        transformedData.push(obj);
+      });
+
+      return transformedData;
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        `Failed to transform data to array of objects`,
+        "TableV2.toArrayOfObjects",
+        { tableName: this.tableName },
+        this.logger?.getTraceId()
+      );
+      return [];
+    }
+  }
+
+  private updateLastTableUpdateInfo(lastTableUpdate: string, data: any = undefined) {
+    try {
+      const sheet = this.getSheet();
+      // last_update and last_update_hash are now stored in __sys__tables__, not in data table
+      // Update in-memory values (will be persisted to __sys__tables__ by DBV2)
+      this.lastTableUpdate = lastTableUpdate;
+
+      if (data !== undefined) {
+        data.lastTableUpdate = this.lastTableUpdate;
+      } else {
+        data = { lastTableUpdate: this.lastTableUpdate };
+      }
+
+      const newHash = UUID.generate(JSON.stringify(data));
+      this.lastUpdateHash = newHash;
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        `Failed to update last table update info`,
+        "TableV2.updateLastTableUpdateInfo",
+        { lastTableUpdate, tableName: this.tableName },
+        this.logger?.getTraceId()
+      );
+    }
+  }
+
+  private getPrimaryKeyValues(): any[] {
+    try {
+      const sheet = this.getSheet();
+      const lastRow = this.getLastRow();
+      // Row 1 is header, data starts at row 2
+      if (lastRow <= 1) {
+        return [];
+      }
+      const primaryKeyIndex = Object.keys(this.schema).indexOf(this.primaryKey);
+      const values = sheet
+        .getRange(2, primaryKeyIndex + 1, lastRow - 1, 1)  // Start at row 2, get (lastRow - 1) rows
+        .getValues()
+        .flat();
+
+      // Cast all primary key values to match schema type
+      const primaryKeyType = this.schema[this.primaryKey]?.type;
+      return values.map(value => {
+        if (primaryKeyType === 'number') {
+          return Number(value);
+        } else if (primaryKeyType === 'string') {
+          return String(value);
+        } else {
+          return String(value); // Default to string
+        }
+      });
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        `Failed to get primary key values`,
+        "TableV2.getPrimaryKeyValues",
+        { tableName: this.tableName },
+        this.logger?.getTraceId()
+      );
+      return [];
+    }
+  }
+
+  private getRowIndexById(id: any): number {
+    try {
+      const typedId = this.castPrimaryKey(id);
+      const primaryKeyValues = this.getPrimaryKeyValues();
+      const rowIndex = primaryKeyValues.indexOf(typedId);
+      if (rowIndex === -1) {
+        return -1;
+      }
+      return rowIndex + 2;  // rowIndex is 0-based, data starts at row 2
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        `Failed to get row index by ID`,
+        "TableV2.getRowIndexById",
+        { id, tableName: this.tableName },
+        this.logger?.getTraceId()
+      );
+      return -1;
+    }
+  }
+
+  private castPrimaryKey(primaryKeyValue: any): any {
+    try {
+      const primaryKeyType = this.schema[this.primaryKey].type;
+      if (primaryKeyType === 'number') {
+        return Number(primaryKeyValue);
+      } else if (primaryKeyType === 'string') {
+        return String(primaryKeyValue);
+      } else {
+        return String(primaryKeyValue);
+      }
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        `Failed to cast primary key`,
+        "TableV2.castPrimaryKey",
+        { primaryKeyValue, tableName: this.tableName },
+        this.logger?.getTraceId()
+      );
+      return null;
+    }
+  }
+
+  private castValue(value: any, type: ColumnType): any {
+    try {
+      switch (type) {
+        case 'number':
+          return Number(value);
+        case 'timestamp':
+          // Unix timestamp in milliseconds (number)
+          return typeof value === 'number' ? value : new Date(value).getTime();
+        case 'datetime':
+          return formatDateTime(new Date(value));
+        case 'boolean':
+          return Boolean(value);
+        case 'string':
+          return value.toString();
+        case 'object':
+        case 'array':
+        case 'arrayOfObjects':
+          return JSON.stringify(value);
+        default:
+          return value;
+      }
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        `Failed to cast value`,
+        "TableV2.castValue",
+        { value, type, tableName: this.tableName },
+        this.logger?.getTraceId()
+      );
+      return value;
+    }
+  }
+
+  /**
+   * Format datetime value based on outputFormat and timezone
+   * @param value ISO string or Date object
+   * @param format Output format (e.g., 'yyyy-MM-dd', 'yyyy-MM-dd HH:mm:ss')
+   * @param timezone Timezone (e.g., 'UTC', 'America/New_York', 'Europe/Warsaw')
+   */
+  private formatDateTime(value: any, format: string, timezone?: string): string {
+    try {
+      const date = new Date(value);
+
+      // If timezone specified, adjust the date
+      let dateStr: string;
+      if (timezone) {
+        // Use Utilities.formatDate for timezone support
+        dateStr = Utilities.formatDate(date, timezone, format);
+      } else {
+        // Use UTC by default
+        dateStr = Utilities.formatDate(date, 'UTC', format);
+      }
+
+      return dateStr;
+    } catch (error) {
+      this.logger?.warn('TableV2.formatDateTime', 'Failed to format datetime', { value, format, timezone });
+      return value;
+    }
+  }
+
+  batchCreate(entriesArray: { [key: string]: any }[]): any {
+    if (this.isReadOnly) {
+      throw new GASErrorV2(
+        'Table is read-only',
+        'TableV2.batchCreate',
+        { tableName: this.tableName }, this.logger?.getTraceId()
+      );
+    }
+
+    if (entriesArray.length === 0) {
+      throw new GASErrorV2(
+        'No entries to create in table',
+        'TableV2.batchCreate',
+        {}, this.logger?.getTraceId()
+      );
+    }
+
+    let _entriesArray = entriesArray;
+    if (entriesArray.length > 20) {
+      _entriesArray = entriesArray.slice(0, 20);
+    }
+
+    const success: any[] = [];
+    const errors: { [id: string]: string } = {};
+
+    try {
+      _entriesArray.forEach((entry: any) => {
+        try {
+          const response = this._create(entry);
+          success.push(response);
+        } catch (error) {
+          errors[entry[this.primaryKey]] = `Failed to create entry: ${error.message}`;
+        }
+      });
+
+      if (entriesArray.length > 20) {
+        this.logger?.warn(
+          'TableV2.batchCreate',
+          `Batch create on table ${this.tableName} truncated to the first 20 entries of request`,
+          {}
+        );
+      }
+
+      if (success.length === 0) {
+        throw new GASErrorV2(
+          'No entries were created',
+          'TableV2.batchCreate',
+          {}, this.logger?.getTraceId()
+        );
+      }
+
+      if (Object.keys(errors).length > 0) {
+        this.logger?.warn('TableV2.batchCreate', `Some entries were not created in "${this.tableName}"`, {
+          success,
+          errors,
+        });
+      }
+
+      return { success, errors };
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        `Unexpected error during batch create operation`,
+        "TableV2.batchCreate",
+        { tableName: this.tableName },
+        this.logger?.getTraceId()
+      );
+      return null;
+    }
+  }
+
+  batchUpdate(entriesDict: { [id: string]: { [key: string]: any } }): any {
+    if (this.isReadOnly) {
+      throw new GASErrorV2(
+        'Table is read-only',
+        'TableV2.batchUpdate',
+        { tableName: this.tableName }, this.logger?.getTraceId()
+      );
+    }
+
+    if (Object.keys(entriesDict).length === 0) {
+      throw new GASErrorV2(
+        'No update data provided',
+        'TableV2.batchUpdate',
+        {}, this.logger?.getTraceId()
+      );
+    }
+
+    let _entriesDict = entriesDict;
+    if (Object.keys(entriesDict).length > 20) {
+      _entriesDict = Object.fromEntries(Object.entries(entriesDict).slice(0, 20));
+    }
+
+    const success: any[] = [];
+    const errors: { [id: string]: string } = {};
+
+    try {
+      for (const [id, updateData] of Object.entries(_entriesDict)) {
+        try {
+          const response = this._update(id, updateData);
+          if (response !== undefined) {
+            success.push(response);
+          } else {
+            errors[id] = `No data found for ID '${id}' in table ${this.tableName}`;
+          }
+        } catch (error) {
+          errors[id] = `Failed to update ID ${id}: ${error.message}`;
+        }
+      }
+
+      if (Object.keys(entriesDict).length > 20) {
+        this.logger?.warn(
+          'TableV2.batchUpdate',
+          `Batch update on table ${this.tableName} truncated to the first 20 entries of request`,
+          {}
+        );
+      }
+
+      if (success.length === 0) {
+        throw new GASErrorV2(
+          'No entries were updated',
+          'TableV2.batchUpdate',
+          {}, this.logger?.getTraceId()
+        );
+      }
+
+      if (Object.keys(errors).length > 0) {
+        this.logger?.warn('TableV2.batchUpdate', `Some entries were not updated in "${this.tableName}"`, {
+          success,
+          errors,
+        });
+      }
+
+      return { success, errors };
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        `Unexpected error during batch update operation`,
+        "TableV2.batchUpdate",
+        { tableName: this.tableName },
+        this.logger?.getTraceId()
+      );
+      return null;
+    }
+  }
+
+  batchDelete(ids: any[]): any {
+    if (this.isReadOnly) {
+      throw new GASErrorV2(
+        'Table is read-only',
+        'TableV2.batchDelete',
+        { tableName: this.tableName }, this.logger?.getTraceId()
+      );
+    }
+
+    if (ids.length === 0) {
+      throw new GASErrorV2(
+        `No entries to delete from table provided`,
+        'TableV2.batchDelete',
+        {}, this.logger?.getTraceId()
+      );
+    }
+
+    let _ids = ids;
+    if (ids.length > 20) {
+      _ids = ids.slice(0, 20);
+    }
+
+    const success: any[] = [];
+    const errors: { [id: string]: string } = {};
+
+    try {
+      _ids.forEach((id: string) => {
+        try {
+          const result = this._delete(id);
+          if (result !== undefined) {
+            success.push(id);
+          } else {
+            errors[id] = `No data found for ID '${id}' in table ${this.tableName}`;
+          }
+        } catch (error) {
+          errors[id] = `Failed to delete ID ${id}: ${error.message}`;
+        }
+      });
+
+      if (ids.length > 20) {
+        this.logger?.warn(
+          'TableV2.batchDelete',
+          `Batch delete on table ${this.tableName} truncated to the first 20 entries of request`,
+          {}
+        );
+      }
+
+      if (success.length === 0) {
+        throw new GASErrorV2(
+          `Batch delete failed, no data found for any of the provided IDs`,
+          'TableV2.batchDelete',
+          { errors }, this.logger?.getTraceId()
+        );
+      }
+
+      if (Object.keys(errors).length > 0) {
+        this.logger?.warn('TableV2.batchDelete', `Some entries were not deleted from "${this.tableName}"`, {
+          success,
+          errors,
+        });
+      }
+
+      return { success, errors };
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        `Batch delete failed`,
+        "TableV2.batchDelete",
+        { tableName: this.tableName },
+        this.logger?.getTraceId()
+      );
+      return null;
+    }
+  }
+}
+
+// ========================================
+// DBV2 Class
+// ========================================
+
+class DBV2 {
+  private tables: Map<string, TableV2>;
+  private config: DBConfigV2;
+  private logger: GASLoggerV2 | null;
+  private currentUser: CachedUser | null;
+  private entityLocks: { [key: string]: EntityLock } = {}; // Cache-based entity locks
+  private lockTimeout: number = 7000; // 7 seconds lock timeout
+  private debug: boolean = false; // Debug mode for detailed logging
+
+  constructor(config: DBConfigV2, logger: GASLoggerV2 | null = null, username?: string, debug: boolean = false) {
+    this.tables = new Map();
+    this.config = config;
+    this.logger = logger;
+    this.currentUser = null; // Will be set via setUser() if needed
+    this.debug = debug;
+
+    // Merge systemTables into tables with metadataSpreadsheetId
+    if (!this.config.tables) {
+      this.config.tables = {};
+    }
+
+    if (this.config.systemTables) {
+      for (const tableName in this.config.systemTables) {
+        if (!this.config.tables[tableName]) {
+          const systemTable = this.config.systemTables[tableName];
+          this.config.tables[tableName] = {
+            spreadsheetId: this.config.metadataSpreadsheetId,
+            ...systemTable
+          };
+          this.logger?.debug('DBV2.constructor', `Merged system table into config: ${tableName}`);
+        }
+      }
+    }
+
+    // Initialize table cache if enabled (metadata-driven mode)
+    if (this.config.tableCaching?.enabled) {
+      this.logger?.info('DBV2.constructor', 'Table caching enabled, loading from metadata...');
+      this.loadTablesFromMetadata();
+    } else {
+      this.logger?.debug('DBV2.constructor', 'Using legacy mode with hardcoded table configs');
+    }
+
+    // Initialize system caches (users, rbac, notification_rules) if configured
+    this.initializeSystemCaches();
+  }
+
+  // ========================================
+  // Two-Level Locking Mechanism
+  // ========================================
+
+  /**
+   * Build lock key with format: lock:tableName:operation:entityId
+   */
+  private buildLockKey(tableName: string, operation: 'create' | 'update' | 'delete', entityId: string): string {
+    return `lock:${tableName}:${operation}:${entityId}`;
+  }
+
+  /**
+   * Clean up expired entity locks
+   */
+  private cleanupExpiredLocks(): void {
+    const now = new Date().getTime();
+    const expiredKeys: string[] = [];
+
+    for (const key in this.entityLocks) {
+      const lock = this.entityLocks[key];
+      if (now - lock.lockedAt > this.lockTimeout) {
+        expiredKeys.push(key);
+      }
+    }
+
+    for (const key of expiredKeys) {
+      delete this.entityLocks[key];
+      this.logger?.debug('DBV2.cleanupExpiredLocks', `Cleaned up expired lock: ${key}`);
+    }
+  }
+
+  /**
+   * Try to acquire entity lock (cache-based) with retry logic
+   * Waits and retries if entity is locked by another operation
+   */
+  private tryAcquireEntityLock(
+    tableName: string,
+    operation: 'create' | 'update' | 'delete',
+    entityId: string,
+    lockerId: string,
+    maxWaitMs: number = 10000
+  ): boolean {
+    const startTime = new Date().getTime();
+    const retryInterval = 500; // Check every 500ms
+
+    while (true) {
+      this.cleanupExpiredLocks();
+
+      const lockKey = this.buildLockKey(tableName, operation, entityId);
+      const existingLock = this.entityLocks[lockKey];
+
+      if (!existingLock) {
+        // No lock exists, acquire it
+        this.entityLocks[lockKey] = {
+          tableName,
+          operation,
+          entityId,
+          lockedAt: new Date().getTime(),
+          lockedBy: lockerId
+        };
+
+        this.logger?.debug('DBV2.tryAcquireEntityLock', `Acquired lock: ${lockKey} by ${lockerId}`);
+        return true;
+      }
+
+      // Lock exists, check if we've exceeded wait time
+      const elapsed = new Date().getTime() - startTime;
+      if (elapsed >= maxWaitMs) {
+        throw new Error(`Timeout waiting for ${lockKey} (locked by ${existingLock.lockedBy})`);
+      }
+
+      // Wait and retry
+      this.logger?.debug('DBV2.tryAcquireEntityLock', `${lockKey} is locked by ${existingLock.lockedBy}, waiting... (${elapsed}ms elapsed)`);
+      Utilities.sleep(retryInterval);
+    }
+  }
+
+  /**
+   * Release entity lock
+   */
+  private releaseEntityLock(tableName: string, operation: 'create' | 'update' | 'delete', entityId: string): void {
+    const lockKey = this.buildLockKey(tableName, operation, entityId);
+    if (this.entityLocks[lockKey]) {
+      delete this.entityLocks[lockKey];
+      this.logger?.debug('DBV2.releaseEntityLock', `Released lock: ${lockKey}`);
+    }
+  }
+
+  /**
+   * Invalidate lock (force remove without waiting for expiration)
+   * Called after successful mutation
+   */
+  private invalidateLock(tableName: string, operation: 'create' | 'update' | 'delete', entityId: string): void {
+    const lockKey = this.buildLockKey(tableName, operation, entityId);
+    if (this.entityLocks[lockKey]) {
+      delete this.entityLocks[lockKey];
+      this.logger?.debug('DBV2.invalidateLock', `Invalidated lock: ${lockKey}`);
+    }
+  }
+
+  /**
+   * Try to acquire table lock (for create operations - locks whole table)
+   * Uses special entityId "__TABLE__" to indicate table-level lock
+   */
+  private tryAcquireTableLock(tableName: string, operation: 'create' | 'delete', lockerId: string): boolean {
+    return this.tryAcquireEntityLock(tableName, operation, '__TABLE__', lockerId);
+  }
+
+  /**
+   * Release table lock
+   */
+  private releaseTableLock(tableName: string, operation: 'create' | 'delete'): void {
+    this.releaseEntityLock(tableName, operation, '__TABLE__');
+  }
+
+  /**
+   * Invalidate table lock
+   */
+  private invalidateTableLock(tableName: string, operation: 'create' | 'delete'): void {
+    this.invalidateLock(tableName, operation, '__TABLE__');
+  }
+
+  /**
+   * Execute mutation with two-level locking (table-level only)
+   * Level 1: Apps Script Lock (aggressive 3s timeout)
+   * Level 2: Cache-based table lock (7s expiration, 10s wait)
+   */
+  private executeMutationWithLock<T>(
+    operation: 'create' | 'update' | 'delete',
+    tableName: string,
+    entityId: string | null, // null for create operations
+    deleteMode: 'soft' | 'hard' | null, // null if not delete operation
+    lockerId: string,
+    mutationFn: () => T
+  ): T {
+    const lock = LockService.getScriptLock();
+
+    try {
+      // Level 1: Apps Script Lock - aggressive timeout (3 seconds)
+      const hasLock = lock.tryLock(3000);
+      if (!hasLock) {
+        throw new Error(`[L1] Failed to acquire Apps Script lock for ${operation} on ${tableName} within 3s`);
+      }
+      this.logger?.debug('DBV2.executeMutationWithLock', `[L1] Acquired Apps Script lock for ${operation} on ${tableName}`);
+
+      // Level 2: Cache-based table lock (all operations use table lock for simplicity)
+      this.tryAcquireTableLock(tableName, operation, lockerId);
+      this.logger?.debug('DBV2.executeMutationWithLock', `[L2] Acquired table lock: ${tableName} for ${operation}`);
+
+      // Release Apps Script lock immediately - Level 2 lock now protects the operation
+      lock.releaseLock();
+      this.logger?.debug('DBV2.executeMutationWithLock', `[L1] Released Apps Script lock - Level 2 lock active`);
+
+      try {
+        // Execute the mutation (now only protected by Level 2 table lock)
+        const result = mutationFn();
+
+        // Mutation successful - invalidate lock immediately (don't wait for expiration)
+        this.invalidateTableLock(tableName, operation);
+        this.logger?.debug('DBV2.executeMutationWithLock', `[L2] Invalidated table lock after successful ${operation}`);
+
+        return result;
+      } catch (error) {
+        // Mutation failed - release lock normally (will auto-expire in 7s anyway)
+        this.releaseTableLock(tableName, operation);
+        this.logger?.debug('DBV2.executeMutationWithLock', `[L2] Released table lock after failed ${operation}`);
+        throw error;
+      }
+    } catch (error) {
+      // If we still hold Apps Script lock, release it
+      try {
+        lock.releaseLock();
+      } catch (e) {
+        // Already released
+      }
+      throw error;
+    }
+  }
+
+  // ========================================
+  // System Tables Caching (Users only)
+  // NOTE: RBAC and notification rules are now code-based configuration
+  // ========================================
+
+  /**
+   * Initialize system caches (users table only)
+   * Called during constructor
+   * NOTE: RBAC and notification rules are now code-based configuration (not cached)
+   */
+  private initializeSystemCaches(): void {
+    if (!this.config.tableCaching?.enabled) {
+      return;
+    }
+
+    if (!this.config.tables) {
+      this.logger?.warn('DBV2.initializeSystemCaches', 'No tables defined in config');
+      return;
+    }
+
+    const scriptCache = CacheService.getScriptCache();
+
+    // Find and cache users table only (RBAC and notification rules are now in code config)
+    for (const tableName in this.config.tables) {
+      const tableConfig = this.config.tables[tableName];
+
+      // Check if table has a system contract (contracts are in config, not in __sys__tables__)
+      if (!tableConfig.systemContract) {
+        continue;
+      }
+
+      const contractType = tableConfig.systemContract.contractType;
+
+      // Only cache users table for auth/RBAC lookups
+      // Do NOT cache application data tables like options, notifications
+      if (contractType === 'users') {
+        const cacheKey = `SYSTEM_CACHE:${tableName}`;
+        const cached = scriptCache.get(cacheKey);
+
+        if (!cached) {
+          this.logger?.info('DBV2.initializeSystemCaches', `Caching users table: ${tableName}`);
+          this.cacheSystemTable(tableName, cacheKey);
+        } else {
+          this.logger?.debug('DBV2.initializeSystemCaches', `Users table ${tableName} already cached`);
+        }
+        break; // Only one users table
+      }
+    }
+  }
+
+  /**
+   * Refresh all caches (table metadata + users table)
+   *
+   * This method refreshes:
+   * 1. Table metadata cache (__sys__tables__) - runtime state (counters, hashes)
+   * 2. Users table cache (SYSTEM_CACHE:users) - for auth/RBAC lookups
+   * 3. Role-to-users mapping cache - for notification recipient resolution
+   *
+   * NOTE: RBAC and notification rules are now code-based configuration (not cached)
+   *
+   * Recommended: Run via time-driven trigger every 3-5 hours
+   * Cache TTL is 6 hours, so refresh before expiration
+   */
+  refreshAllCaches(): void {
+    this.logger?.info('DBV2.refreshAllCaches', 'Starting cache refresh...');
+
+    // Refresh table metadata cache from __sys__tables__
+    this.refreshTableCache();
+
+    // Refresh system table data caches (uses metadata from cache above)
+    this.refreshSystemCaches();
+
+    this.logger?.info('DBV2.refreshAllCaches', 'All caches refreshed');
+  }
+
+  /**
+   * Refresh all system caches (users table + role-users mapping)
+   * Call this from hourly trigger
+   * NOTE: RBAC and notification rules are now code-based configuration (not cached)
+   */
+  refreshSystemCaches(): void {
+    if (!this.config.tableCaching?.enabled) {
+      this.logger?.warn('DBV2.refreshSystemCaches', 'Table caching not enabled, skipping system cache refresh');
+      return;
+    }
+
+    this.logger?.info('DBV2.refreshSystemCaches', 'Refreshing system caches (users table + role-users mapping)...');
+
+    const scriptCache = CacheService.getScriptCache();
+    let refreshedCount = 0;
+
+    // NOTE: RBAC and notification_rules are now code-based configuration (not cached)
+    // Only cache users table for auth/RBAC lookups
+
+    // 1. Cache users table contract data (not entire table, just contract fields)
+    if (this.config.tables) {
+      for (const tableName in this.config.tables) {
+        const tableConfig = this.config.tables[tableName];
+
+        // Only cache users contract data for auth/RBAC
+        if (tableConfig.systemContract?.contractType === 'users') {
+          const cacheKey = `SYSTEM_CACHE:${tableName}`;
+          this.logger?.info('DBV2.refreshSystemCaches', `Refreshing users contract data: ${tableName}`);
+          this.cacheSystemTable(tableName, cacheKey);
+          refreshedCount++;
+          break; // Only one users table
+        }
+      }
+    }
+
+    // 2. Build and cache role-to-users mapping for fast notification lookups
+    this.logger?.info('DBV2.refreshSystemCaches', 'Building role-to-users cache...');
+    const roleUsers = this.buildRoleUsersCache();
+    const roleUsersCacheKey = 'SYSTEM_CACHE:ROLE_USERS';
+    scriptCache.put(roleUsersCacheKey, JSON.stringify(roleUsers), 21600); // 6 hours
+    this.logger?.info('DBV2.refreshSystemCaches', `Role-to-users cache built: ${Object.keys(roleUsers).length} roles`);
+
+    this.logger?.info('DBV2.refreshSystemCaches', `System cache refresh complete. Refreshed users table + role-users cache`);
+  }
+
+  /**
+   * Cache a system table data
+   */
+  private cacheSystemTable(tableName: string, cacheKey: string): void {
+    try {
+      // Check if table exists in runtime state first (skip if not created yet)
+      const runtimeState = this.getRuntimeState(tableName);
+      if (!runtimeState) {
+        this.logger?.warn('DBV2.cacheSystemTable', `Table '${tableName}' not found in __sys__tables__ runtime state - table not created yet, skipping cache`, {
+          cacheKey: cacheKey,
+          availableTables: 'Check __sys__tables__ spreadsheet'
+        });
+        return;
+      }
+
+      this.initializeTable(tableName);
+      const table = this.tables.get(tableName);
+
+      if (!table) {
+        this.logger?.warn('DBV2.cacheSystemTable', `Failed to initialize table '${tableName}' - check spreadsheet exists`, {
+          cacheKey: cacheKey,
+          runtimeState: runtimeState
+        });
+        return;
+      }
+
+      const result = table.getData(0, 0); // Get all data (pageStart=0, pageSize=0 means all)
+      const dataRecords = result.data; // Just the array of records, schema is in config
+      const scriptCache = CacheService.getScriptCache();
+
+      // Cache only data records (schema is in config already)
+      // Even empty tables are cached as [] to distinguish from "not created yet"
+      scriptCache.put(cacheKey, JSON.stringify(dataRecords), 21600); // 6 hours
+
+      if (dataRecords.length === 0) {
+        this.logger?.info('DBV2.cacheSystemTable', `Cached empty table '${tableName}' (0 records) - table exists but has no data`, {
+          cacheKey: cacheKey,
+          spreadsheetId: runtimeState.spreadsheetId,
+          sheetName: runtimeState.sheetName
+        });
+      } else {
+        this.logger?.info('DBV2.cacheSystemTable', `Cached ${dataRecords.length} records from '${tableName}'`, {
+          cacheKey: cacheKey
+        });
+      }
+    } catch (error) {
+      // Log warning but don't fail - system tables may not exist yet
+      this.logger?.warn('DBV2.cacheSystemTable', `Failed to cache system table '${tableName}': ${error.toString()}`, {
+        cacheKey: cacheKey,
+        error: error
+      });
+    }
+  }
+
+  /**
+   * Get system table data from cache
+   */
+  getSystemTableCache(tableName: string): any[] | null {
+    const cacheKey = `SYSTEM_CACHE:${tableName}`;
+    const scriptCache = CacheService.getScriptCache();
+    const cached = scriptCache.get(cacheKey);
+
+    if (!cached) {
+      this.logger?.warn('DBV2.getSystemTableCache', `Cache not found for table: ${tableName}`);
+      return null;
+    }
+
+    return JSON.parse(cached);
+  }
+
+  /**
+   * Build role-to-users mapping from users cache
+   * Returns object like: { "admin": ["user1@example.com", "user2@example.com"], "manager": [...] }
+   */
+  private buildRoleUsersCache(): Record<string, string[]> {
+    const users = this.getSystemTableCache('users');
+    const roleUsers: Record<string, string[]> = {};
+
+    if (!users || users.length === 0) {
+      this.logger?.warn('DBV2.buildRoleUsersCache', 'No users in cache, returning empty role mapping');
+      return roleUsers;
+    }
+
+    // Build mapping: role -> array of user emails
+    for (const user of users) {
+      if (user.__archived__ === false && user.active !== false && user.email) {
+        const role = user.role;
+        if (!roleUsers[role]) {
+          roleUsers[role] = [];
+        }
+        roleUsers[role].push(user.email);
+      }
+    }
+
+    this.logger?.info('DBV2.buildRoleUsersCache', `Built role-to-users cache`, {
+      roles: Object.keys(roleUsers),
+      counts: Object.entries(roleUsers).map(([role, emails]) => `${role}: ${emails.length}`).join(', ')
+    });
+
+    return roleUsers;
+  }
+
+  /**
+   * Get users by role using cached role-to-users mapping
+   */
+  private getUsersByRole(role: string): string[] {
+    const cacheKey = 'SYSTEM_CACHE:ROLE_USERS';
+    const scriptCache = CacheService.getScriptCache();
+    let cached = scriptCache.get(cacheKey);
+
+    let roleUsers: Record<string, string[]>;
+
+    // If not cached, build it from users cache
+    if (!cached) {
+      this.logger?.debug('DBV2.getUsersByRole', 'Role-users cache not found, building from users cache');
+      roleUsers = this.buildRoleUsersCache();
+      scriptCache.put(cacheKey, JSON.stringify(roleUsers), 21600); // 6 hours
+    } else {
+      roleUsers = JSON.parse(cached);
+    }
+
+    return roleUsers[role] || [];
+  }
+
+  // ========================================
+  // Trigger Condition Evaluation
+  // ========================================
+
+  /**
+   * Evaluate if data matches rule conditions
+   *
+   * Supports:
+   * - Exact match: { "status": "completed" }
+   * - Wildcard (any non-empty value): { "response_document": "*" }
+   * - OR operator: { "OR": [{"status": "completed"}, {"status": "rejected"}] }
+   * - AND operator: { "AND": [{"status": "completed"}, {"request_type": "info"}] }
+   * - NOT operator: { "NOT": {"status": "pending"} }
+   * - IN operator: { "status": {"IN": ["completed", "rejected", "closed"]} }
+   * - Empty conditions: {} (always matches)
+   * - Nested combinations supported
+   */
+  private evaluateRuleConditions(rule: any, data: any): boolean {
+    const conditions = rule.conditions || {};
+
+    // Empty conditions = always match
+    if (Object.keys(conditions).length === 0) {
+      this.logger?.debug('DBV2.evaluateRuleConditions', `Rule '${rule.rule_name}' has no conditions - always matches`);
+      return true;
+    }
+
+    return this.evaluateCondition(conditions, data, rule.rule_name);
+  }
+
+  /**
+   * Recursively evaluate a condition object
+   */
+  private evaluateCondition(condition: any, data: any, ruleName: string): boolean {
+    // Handle OR operator
+    if (condition.OR && Array.isArray(condition.OR)) {
+      const result = condition.OR.some((subCondition: any) => this.evaluateCondition(subCondition, data, ruleName));
+      this.logger?.debug('DBV2.evaluateCondition', `OR condition: ${result}`, condition.OR);
+      return result;
+    }
+
+    // Handle AND operator
+    if (condition.AND && Array.isArray(condition.AND)) {
+      const result = condition.AND.every((subCondition: any) => this.evaluateCondition(subCondition, data, ruleName));
+      this.logger?.debug('DBV2.evaluateCondition', `AND condition: ${result}`, condition.AND);
+      return result;
+    }
+
+    // Handle NOT operator
+    if (condition.NOT) {
+      const result = !this.evaluateCondition(condition.NOT, data, ruleName);
+      this.logger?.debug('DBV2.evaluateCondition', `NOT condition: ${result}`, condition.NOT);
+      return result;
+    }
+
+    // Handle field-level conditions
+    for (const [field, expectedValue] of Object.entries(condition)) {
+      // Skip operator keys already processed
+      if (field === 'OR' || field === 'AND' || field === 'NOT') {
+        continue;
+      }
+
+      // Handle IN operator for field
+      if (typeof expectedValue === 'object' && expectedValue !== null && 'IN' in expectedValue) {
+        const inArray = (expectedValue as any).IN;
+        if (!Array.isArray(inArray)) {
+          this.logger?.warn('DBV2.evaluateCondition', `IN operator requires an array for field '${field}'`);
+          return false;
+        }
+        const result = inArray.includes(data[field]);
+        this.logger?.debug('DBV2.evaluateCondition', `IN condition for '${field}': ${result} (value: ${data[field]}, array: ${JSON.stringify(inArray)})`);
+        if (!result) {
+          return false;
+        }
+        continue;
+      }
+
+      // Wildcard "*" means field must have any non-empty value
+      if (expectedValue === '*') {
+        if (!data[field] || data[field] === '' || data[field] === null || data[field] === undefined) {
+          this.logger?.debug('DBV2.evaluateCondition', `Wildcard condition not met: ${field} is empty`);
+          return false;
+        }
+        continue;
+      }
+
+      // Exact match
+      if (data[field] !== expectedValue) {
+        this.logger?.debug('DBV2.evaluateCondition', `Condition not met: ${field}=${data[field]} (expected: ${expectedValue})`);
+        return false;
+      }
+    }
+
+    this.logger?.debug('DBV2.evaluateCondition', `Condition matched`);
+    return true;
+  }
+
+  // ========================================
+  // Database Triggers Execution
+  // ========================================
+
+  /**
+   * Trigger database triggers after CRUD operations
+   * Unified trigger system for all automated database operations
+   * Called after create/update/delete operations
+   */
+  triggerDatabaseTriggers(entity: string, method: string, data: any): void {
+    try {
+      // Get triggers from config
+      const triggers = this.config.triggers || [];
+
+      if (triggers.length === 0) {
+        this.logger?.debug('DBV2.triggerDatabaseTriggers', 'No database triggers defined in config');
+        return;
+      }
+
+      this.logger?.debug('DBV2.triggerDatabaseTriggers', `Checking ${triggers.length} triggers for ${entity}.${method}`);
+
+      // Filter triggers matching entity and method
+      const matchingTriggers = triggers.filter((trigger: any) => {
+        return trigger.enabled !== false &&
+          trigger.source_entity === entity &&
+          trigger.source_method === method;
+      });
+
+      if (matchingTriggers.length === 0) {
+        this.logger?.debug('DBV2.triggerDatabaseTriggers', `No matching triggers for ${entity}.${method}`);
+        return;
+      }
+
+      this.logger?.info('DBV2.triggerDatabaseTriggers', `Found ${matchingTriggers.length} matching triggers for ${entity}.${method}`);
+
+      // Execute each trigger
+      for (const trigger of matchingTriggers) {
+        this.executeDatabaseTrigger(trigger, data);
+      }
+
+    } catch (error) {
+      this.logger?.warn('DBV2.triggerDatabaseTriggers', `Failed to trigger database triggers: ${error.toString()}`);
+    }
+  }
+
+  /**
+   * Execute a single database trigger
+   */
+  private executeDatabaseTrigger(trigger: any, sourceData: any): void {
+    try {
+      // Check conditions
+      if (!this.evaluateRuleConditions(trigger, sourceData)) {
+        this.logger?.debug('DBV2.executeDatabaseTrigger', `Trigger '${trigger.trigger_name}' conditions not met, skipping`);
+        return;
+      }
+
+      const action = trigger.action; // 'create', 'update', 'delete'
+      const targetTable = trigger.target_table;
+
+      if (!targetTable) {
+        this.logger?.warn('DBV2.executeDatabaseTrigger', `Trigger '${trigger.trigger_name}' has no target_table specified`);
+        return;
+      }
+
+      // Render data mapping with template placeholders
+      const mappedData = this.renderTemplateObject(trigger.data_mapping || {}, sourceData);
+
+      // Initialize target table if needed
+      this.initializeTable(targetTable);
+      const table = this.tables.get(targetTable);
+      if (!table) {
+        this.logger?.warn('DBV2.executeDatabaseTrigger', `Trigger '${trigger.trigger_name}' target table '${targetTable}' not found`);
+        return;
+      }
+
+      // Execute the action
+      switch (action) {
+        case 'create':
+          table.create(mappedData);
+          this.logger?.info('DBV2.executeDatabaseTrigger', `Trigger '${trigger.trigger_name}' created record in '${targetTable}'`, { data: mappedData });
+          break;
+
+        case 'update':
+          // For update, need target record ID
+          const targetIdField = trigger.target_id_field;
+          const targetIdValue = this.renderTemplate(trigger.target_id_value || '', sourceData);
+
+          if (!targetIdField || !targetIdValue) {
+            this.logger?.warn('DBV2.executeDatabaseTrigger', `Trigger '${trigger.trigger_name}' update action requires target_id_field and target_id_value`);
+            return;
+          }
+
+          // Find record by field value
+          const allRecords = table.getData();
+          const targetRecord = allRecords?.data?.find((rec: any) => rec[targetIdField] === targetIdValue);
+
+          if (targetRecord) {
+            table.update(targetRecord.id, mappedData);
+            this.logger?.info('DBV2.executeDatabaseTrigger', `Trigger '${trigger.trigger_name}' updated record in '${targetTable}'`, {
+              targetId: targetRecord.id,
+              data: mappedData
+            });
+          } else {
+            this.logger?.warn('DBV2.executeDatabaseTrigger', `Trigger '${trigger.trigger_name}' could not find record in '${targetTable}' where ${targetIdField}=${targetIdValue}`);
+          }
+          break;
+
+        case 'delete':
+          // For delete, need target record ID
+          const deleteIdField = trigger.target_id_field;
+          const deleteIdValue = this.renderTemplate(trigger.target_id_value || '', sourceData);
+
+          if (!deleteIdField || !deleteIdValue) {
+            this.logger?.warn('DBV2.executeDatabaseTrigger', `Trigger '${trigger.trigger_name}' delete action requires target_id_field and target_id_value`);
+            return;
+          }
+
+          // Find record by field value
+          const allDeleteRecords = table.getData();
+          const deleteRecord = allDeleteRecords?.data?.find((rec: any) => rec[deleteIdField] === deleteIdValue);
+
+          if (deleteRecord) {
+            table.delete(deleteRecord.id);
+            this.logger?.info('DBV2.executeDatabaseTrigger', `Trigger '${trigger.trigger_name}' deleted record from '${targetTable}'`, {
+              targetId: deleteRecord.id
+            });
+          } else {
+            this.logger?.warn('DBV2.executeDatabaseTrigger', `Trigger '${trigger.trigger_name}' could not find record in '${targetTable}' where ${deleteIdField}=${deleteIdValue}`);
+          }
+          break;
+
+        default:
+          this.logger?.warn('DBV2.executeDatabaseTrigger', `Trigger '${trigger.trigger_name}' has unknown action '${action}'`);
+      }
+
+    } catch (error) {
+      this.logger?.warn('DBV2.executeDatabaseTrigger', `Failed to execute trigger '${trigger.trigger_name}': ${error.toString()}`);
+    }
+  }
+
+  // ========================================
+  // Template Rendering
+  // ========================================
+
+  /**
+   * Render a single string template with data
+   * Supports:
+   * - {{field}} - source data field
+   * - {{__current_user__}} - current authenticated user email
+   * - {{__now__}} - current datetime (formatted)
+   */
+  private renderTemplate(template: string, data: any): string {
+    if (typeof template !== 'string') {
+      return String(template);
+    }
+
+    // Replace placeholders with values
+    return template.replace(/\{\{([^}]+)\}\}/g, (match, field) => {
+      const trimmedField = field.trim();
+
+      // Special variables
+      if (trimmedField === '__current_user__') {
+        return this.currentUser?.email || 'system';
+      }
+      if (trimmedField === '__now__') {
+        return formatDateTime();
+      }
+
+      // Regular data field
+      return data[trimmedField] !== undefined ? String(data[trimmedField]) : match;
+    });
+  }
+
+  /**
+   * Render template object with data (supports nested objects)
+   *
+   * Supports:
+   * - {{field}} - source data field value
+   * - {{__current_user__}} - current authenticated user email
+   * - {{__now__}} - current datetime (formatted)
+   * - Nested objects are rendered recursively
+   */
+  private renderTemplateObject(template: any, data: any): any {
+    if (template === null || template === undefined) {
+      return template;
+    }
+
+    // Handle string templates
+    if (typeof template === 'string') {
+      return this.renderTemplate(template, data);
+    }
+
+    // Handle arrays
+    if (Array.isArray(template)) {
+      return template.map(item => this.renderTemplateObject(item, data));
+    }
+
+    // Handle objects
+    if (typeof template === 'object') {
+      const rendered: any = {};
+      for (const [key, value] of Object.entries(template)) {
+        rendered[key] = this.renderTemplateObject(value, data);
+      }
+      return rendered;
+    }
+
+    // Return primitives as-is (numbers, booleans)
+    return template;
+  }
+
+  // ========================================
+  // Table Caching Methods (Metadata-Driven DB)
+  // ========================================
+
+  private getTableCacheKey(): string {
+    return 'SYSTEM_CACHE:__sys__tables__';
+  }
+
+  private ensureTableCacheInitialized(): void {
+    if (!this.config.tableCaching?.enabled) {
+      return;
+    }
+
+    const cacheKey = this.getTableCacheKey();
+    const scriptCache = CacheService.getScriptCache();
+    const cachedData = scriptCache.get(cacheKey);
+
+    if (!cachedData) {
+      this.logger?.info('DBV2.ensureTableCacheInitialized', 'Table cache not found, refreshing...');
+      try {
+        this.refreshTableCache();
+      } catch (error) {
+        // If refresh fails during initialization, re-throw with better context
+        throw GASErrorV2.wrapError(
+          error,
+          'Failed to initialize table cache - ensure __sys__tables__ sheet exists and has data',
+          'DBV2.ensureTableCacheInitialized',
+          { metadataSpreadsheetId: this.config.metadataSpreadsheetId },
+          this.logger?.getTraceId()
+        );
+      }
+      return;
+    }
+
+    this.logger?.debug('DBV2.ensureTableCacheInitialized', 'Table cache exists (TTL managed by CacheService)');
+  }
+
+  refreshTableCache(): void {
+    if (!this.config.tableCaching?.enabled) {
+      this.logger?.warn('DBV2.refreshTableCache', 'Table caching is not enabled');
+      return;
+    }
+
+    try {
+      this.logger?.info('DBV2.refreshTableCache', 'Starting table cache refresh...');
+
+      const metadataSpreadsheetId = this.config.metadataSpreadsheetId;
+      this.logger?.debug('DBV2.refreshTableCache', 'Opening metadata spreadsheet', { metadataSpreadsheetId });
+
+      const ss = SpreadsheetApp.openById(metadataSpreadsheetId);
+      const allSheets = ss.getSheets().map(s => s.getName());
+      this.logger?.debug('DBV2.refreshTableCache', 'Available sheets in spreadsheet', { sheets: allSheets });
+
+      const metadataSheet = ss.getSheetByName('__sys__tables__');
+
+      if (!metadataSheet) {
+        throw new GASErrorV2(
+          `__sys__tables__ metadata sheet not found in spreadsheet. Available sheets: ${allSheets.join(', ')}`,
+          'DBV2.refreshTableCache',
+          { metadataSpreadsheetId, availableSheets: allSheets },
+          this.logger?.getTraceId()
+        );
+      }
+
+      const lastRow = metadataSheet.getLastRow();
+      if (lastRow < 2) {
+        this.logger?.warn('DBV2.refreshTableCache', '__tables__ has no data');
+        return;
+      }
+
+      // Read runtime state only (9 columns: id, table_name, spreadsheet_id, sheet_name, counter, last_update, last_update_hash, __audit__, __archived__)
+      const data = metadataSheet.getRange(2, 1, lastRow - 1, 9).getValues();
+      const runtimeStates: TableRuntimeState[] = [];
+
+      for (const row of data) {
+        const archived = row[8]; // __archived__ column (9th column, index 8)
+        if (archived) {
+          continue; // Skip archived tables
+        }
+
+        const state: TableRuntimeState = {
+          tableName: row[1],         // table_name
+          spreadsheetId: row[2],     // spreadsheet_id
+          sheetName: row[3],         // sheet_name
+          counter: row[4],           // counter
+          lastUpdate: row[5],        // last_update
+          lastUpdateHash: row[6]     // last_update_hash
+        };
+
+        runtimeStates.push(state);
+      }
+
+      // Store minimal runtime state in cache
+      const cacheKey = this.getTableCacheKey();
+      const scriptCache = CacheService.getScriptCache();
+
+      scriptCache.put(cacheKey, JSON.stringify(runtimeStates), 21600); // 6 hours
+
+      this.logger?.info('DBV2.refreshTableCache', 'Table cache refresh completed', { tableCount: runtimeStates.length });
+
+    } catch (error) {
+      throw GASErrorV2.wrapError(
+        error,
+        'Failed to refresh table cache',
+        'DBV2.refreshTableCache',
+        { metadataSpreadsheetId: this.config.metadataSpreadsheetId },
+        this.logger?.getTraceId()
+      );
+    }
+  }
+
+  /**
+   * Refresh user cache from users table
+   * Loads all users and caches them for role-based access control
+   * NOTE: This is now handled by refreshSystemCaches() which auto-discovers tables with 'users' contract
+   * Kept for backward compatibility but delegates to refreshSystemCaches
+   */
+  refreshUserCache(): void {
+    this.logger?.info('DBV2.refreshUserCache', 'Delegating to refreshSystemCaches()...');
+    this.refreshSystemCaches();
+  }
+
+  private getRuntimeState(tableName: string): TableRuntimeState | null {
+    if (!this.config.tableCaching?.enabled) {
+      return null;
+    }
+
+    try {
+      const cacheKey = this.getTableCacheKey();
+      const scriptCache = CacheService.getScriptCache();
+      const cachedData = scriptCache.get(cacheKey);
+
+      if (!cachedData) {
+        this.logger?.warn('DBV2.getRuntimeState', 'Runtime state cache is empty, refreshing...');
+        this.refreshTableCache();
+        const refreshedData = scriptCache.get(cacheKey);
+        if (!refreshedData) {
+          return null;
+        }
+        const states: TableRuntimeState[] = JSON.parse(refreshedData);
+        return states.find(s => s.tableName === tableName) || null;
+      }
+
+      const runtimeStates: TableRuntimeState[] = JSON.parse(cachedData);
+      const state = runtimeStates.find(s => s.tableName === tableName);
+
+      if (state) {
+        this.logger?.debug('DBV2.getRuntimeState', `Found runtime state in cache`, { tableName, counter: state.counter });
+        return state;
+      }
+
+      this.logger?.warn('DBV2.getRuntimeState', `Table not found in runtime state cache`, { tableName });
+      return null;
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        `Failed to get runtime state from cache`,
+        "DBV2.getRuntimeState",
+        { tableName },
+        this.logger?.getTraceId()
+      );
+      return null;
+    }
+  }
+
+  /**
+   * Update runtime state in __sys__tables__ after mutation
+   * Updates: last_update, last_update_hash (counter is managed by TableV2.updateCounter)
+   */
+  private updateRuntimeState(tableName: string): void {
+    if (!this.config.tableCaching?.enabled) {
+      return; // No metadata tracking if caching disabled
+    }
+
+    try {
+      const metadataSpreadsheetId = this.config.metadataSpreadsheetId;
+      const ss = SpreadsheetApp.openById(metadataSpreadsheetId);
+      const metadataSheet = ss.getSheetByName('__sys__tables__');
+
+      if (!metadataSheet) {
+        this.logger?.warn('DBV2.updateRuntimeState', '__sys__tables__ not found, skipping runtime state update');
+        return;
+      }
+
+      // Find the row for this table
+      const lastRow = metadataSheet.getLastRow();
+      const tableNames = metadataSheet.getRange(2, 2, lastRow - 1, 1).getValues(); // Column B: table_name
+
+      let rowIndex = -1;
+      for (let i = 0; i < tableNames.length; i++) {
+        if (tableNames[i][0] === tableName) {
+          rowIndex = i + 2; // +2 because array is 0-indexed and we skip header
+          break;
+        }
+      }
+
+      if (rowIndex === -1) {
+        this.logger?.warn('DBV2.updateRuntimeState', `Table '${tableName}' not found in __sys__tables__`);
+        return;
+      }
+
+      const now = new Date().getTime(); // Unix timestamp in milliseconds
+      const currentCounter = metadataSheet.getRange(rowIndex, 5).getValue(); // Column E: counter (read only, don't modify)
+
+      // Calculate new hash
+      const runtimeState = this.getRuntimeState(tableName);
+      const newHash = Utilities.computeDigest(
+        Utilities.DigestAlgorithm.SHA_256,
+        JSON.stringify({
+          tableName: tableName,
+          spreadsheetId: runtimeState?.spreadsheetId,
+          sheetName: runtimeState?.sheetName,
+          counter: currentCounter, // Use current counter value, don't increment
+          last_update: now
+        })
+      ).map(byte => (byte < 0 ? byte + 256 : byte).toString(16).padStart(2, '0')).join('');
+
+      // Update: last_update, last_update_hash (counter updated separately by TableV2.updateCounter)
+      metadataSheet.getRange(rowIndex, 6).setValue(now); // Column F: last_update (Unix timestamp)
+      metadataSheet.getRange(rowIndex, 7).setValue(newHash); // Column G: last_update_hash
+
+      this.logger?.debug('DBV2.updateRuntimeState', `Updated runtime state for ${tableName}`, {
+        rowIndex,
+        currentCounter
+      });
+
+    } catch (error) {
+      // Log error but don't fail the mutation
+      this.logger?.error(GASErrorV2.wrapError(
+        error,
+        'Failed to update runtime state in __sys__tables__',
+        'DBV2.updateRuntimeState',
+        { tableName },
+        this.logger?.getTraceId()
+      ));
+    }
+  }
+
+  loadTablesFromMetadata(): void {
+    if (!this.config.tableCaching?.enabled) {
+      this.logger?.debug('DBV2.loadTablesFromMetadata', 'Table caching disabled, skipping metadata load');
+      return;
+    }
+
+    this.logger?.info('DBV2.loadTablesFromMetadata', 'Loading tables from metadata...');
+
+    // Ensure cache is initialized
+    this.ensureTableCacheInitialized();
+
+    const cacheKey = this.getTableCacheKey();
+    const scriptCache = CacheService.getScriptCache();
+    const cachedData = scriptCache.get(cacheKey);
+
+    if (!cachedData) {
+      throw new GASErrorV2(
+        'Table cache is empty after initialization',
+        'DBV2.loadTablesFromMetadata',
+        {},
+        this.logger?.getTraceId()
+      );
+    }
+
+    const runtimeStates: TableRuntimeState[] = JSON.parse(cachedData);
+
+    // Merge runtime state with config table specs
+    // config.tables already has full specs (schemas, generators, contracts)
+    // We just validate that runtime state matches and is available
+    if (!this.config.tables) {
+      this.logger?.warn('DBV2.loadTablesFromMetadata', 'No tables defined in config, using runtime state only');
+      this.config.tables = {};
+    }
+
+    for (const state of runtimeStates) {
+      const configTable = this.config.tables[state.tableName];
+
+      if (configTable) {
+        // Table exists in config - update with runtime location if needed
+        configTable.spreadsheetId = state.spreadsheetId;
+        configTable.sheetName = state.sheetName;
+        this.logger?.debug('DBV2.loadTablesFromMetadata', `Merged runtime state for table: ${state.tableName}`);
+      } else {
+        // Table exists in runtime but not in config - warn but don't create
+        this.logger?.warn('DBV2.loadTablesFromMetadata', `Table '${state.tableName}' found in runtime state but not in config - skipping`);
+      }
+    }
+
+    this.logger?.info('DBV2.loadTablesFromMetadata', 'Tables loaded and merged with runtime state', {
+      configTableCount: Object.keys(this.config.tables || {}).length,
+      runtimeStateCount: runtimeStates.length
+    });
+  }
+
+  // ========================================
+  // Role-Based Access Control Methods
+  // ========================================
+
+  private hasPermission(tableName: string, operation: keyof TablePermissions): boolean {
+    // Superadmin bypasses all RBAC checks
+    if (this.currentUser?.role === 'superadmin') {
+      this.logger?.debug('DBV2.hasPermission', 'Superadmin bypass', { tableName, operation });
+      return true;
+    }
+
+    // If no current user, deny access (security-first approach)
+    if (!this.currentUser) {
+      this.logger?.warn('DBV2.hasPermission', 'No current user set - denying access', { tableName, operation });
+      return false;
+    }
+
+    const userRole = this.currentUser.role;
+
+    // Get table config (check both tables and systemTables)
+    let tableConfig = this.config.tables?.[tableName];
+    if (!tableConfig && this.config.systemTables) {
+      tableConfig = this.config.systemTables[tableName] as any;
+    }
+
+    if (!tableConfig) {
+      this.logger?.warn('DBV2.hasPermission', `Table '${tableName}' not found in config`, { tableName, userRole });
+      return false;
+    }
+
+    // Get RBAC rule for this table and role
+    const rbacRule = (tableConfig as any).rbac?.[userRole];
+    if (!rbacRule) {
+      this.logger?.warn('DBV2.hasPermission', `No RBAC rule for role '${userRole}' on table '${tableName}'`, { tableName, userRole });
+      return false;
+    }
+
+    // Map operation to RBAC field
+    const methodMap: { [key: string]: string } = {
+      'create': 'create',
+      'read': 'get_all',  // getData and getById both use 'read' operation
+      'update': 'update',
+      'delete': 'delete',
+      'query': 'get_all'
+    };
+
+    const rbacMethod = methodMap[operation];
+    if (!rbacMethod) {
+      this.logger?.warn('DBV2.hasPermission', `Unknown operation '${operation}'`, { tableName, operation });
+      return false;
+    }
+
+    // Check if method is allowed (boolean field)
+    const hasPermission = rbacRule[rbacMethod] === true;
+    this.logger?.debug('DBV2.hasPermission', `Permission check result`, { tableName, operation, userRole, rbacMethod, hasPermission });
+    return hasPermission;
+  }
+
+  private checkPermission(tableName: string, operation: keyof TablePermissions): void {
+    // Skip RBAC checks if no user context (for services without RBAC like sync services)
+    if (!this.currentUser) {
+      this.logger?.debug('DBV2.checkPermission', 'No user context - skipping RBAC checks', { tableName, operation });
+      return;
+    }
+
+    if (!this.hasPermission(tableName, operation)) {
+      const userInfo = this.currentUser ? `user '${this.currentUser.name}' with role '${this.currentUser.role}'` : 'anonymous user';
+      throw new GASErrorV2(
+        `Permission denied: ${userInfo} cannot perform '${operation}' on table '${tableName}'`,
+        'DBV2.checkPermission',
+        { tableName, operation, user: this.currentUser }, this.logger?.getTraceId()
+      );
+    }
+  }
+
+  setCurrentUser(username: string, usersTableName: string = 'users', superadminsList?: string[]): void {
+    // Seed mode: superadminsList provided - bypass cache, use list directly
+    if (superadminsList && superadminsList.includes(username)) {
+      this.currentUser = {
+        id: username,
+        name: username,
+        email: username,
+        role: 'superadmin'
+      };
+      this.logger?.info('DBV2.setCurrentUser', `User set from superadmins list (seed mode)`, { username, role: 'superadmin' });
+      return;
+    }
+
+    // Normal mode: Try to get user from system cache first
+    let usersCache = this.getSystemTableCache(usersTableName);
+
+    // If cache is empty or user not found, try to refresh cache
+    if (!usersCache || usersCache.length === 0) {
+      this.logger?.debug('DBV2.setCurrentUser', 'Users cache empty, refreshing...', { username });
+      this.refreshUserCache();
+      usersCache = this.getSystemTableCache(usersTableName);
+    }
+
+    if (usersCache && usersCache.length > 0) {
+      // Users table has data - use it as source of truth
+      let user = usersCache.find((u: any) => u.name === username || u.email === username);
+
+      // If user not found in cache, try refreshing once more
+      if (!user) {
+        this.logger?.debug('DBV2.setCurrentUser', 'User not in cache, refreshing once...', { username });
+        this.refreshUserCache();
+        usersCache = this.getSystemTableCache(usersTableName);
+        user = usersCache.find((u: any) => u.name === username || u.email === username);
+      }
+
+      if (user) {
+        this.currentUser = {
+          id: user.id,
+          name: user.name,
+          email: user.email,
+          role: user.role
+        };
+        this.logger?.info('DBV2.setCurrentUser', `User set from cache`, { username, role: user.role });
+        return;
+      }
+
+      // User not found in populated users table - authentication failed
+      this.logger?.warn('DBV2.setCurrentUser', 'User not found in users table', { username });
+      this.currentUser = null;
+      return;
+    }
+
+    // Users table is empty and no superadmins list provided - authentication failed
+    this.logger?.warn('DBV2.setCurrentUser', 'User not found - users table empty and no seed mode', { username });
+    this.currentUser = null;
+  }
+
+  getCurrentUser(): CachedUser | null {
+    return this.currentUser;
+  }
+
+  /**
+   * Apply field-level view filtering for read operations based on user's role
+   * Superadmin always sees all fields (no filtering)
+   * Other roles follow roleViews configuration overlay
+   */
+  private applyFieldView<T extends Record<string, any>>(
+    data: T | T[],
+    tableName: string
+  ): T | T[] {
+    this.logger?.info('DBV2.applyFieldView', 'Starting field view filtering', {
+      tableName,
+      dataType: typeof data,
+      isArray: Array.isArray(data),
+      dataLength: Array.isArray(data) ? data.length : 'N/A',
+      currentUserRole: this.currentUser?.role
+    });
+
+    // Superadmin bypasses all view restrictions
+    if (this.currentUser?.role === 'superadmin') {
+      this.logger?.info('DBV2.applyFieldView', 'Superadmin - no field filtering');
+      return data;
+    }
+
+    // Get readFields from RBAC configuration
+    const tableConfig = this.config.tables?.[tableName];
+    const roleConfig = tableConfig?.rbac?.[this.currentUser?.role];
+    const readFields = roleConfig?.readFields;
+
+    this.logger?.info('DBV2.applyFieldView', 'Field filtering config', {
+      tableName,
+      role: this.currentUser?.role,
+      hasTableConfig: !!tableConfig,
+      hasRoleConfig: !!roleConfig,
+      hasReadFields: !!readFields,
+      readFields: readFields
+    });
+
+    // Helper to filter a single record
+    const filterRecord = (record: T): T => {
+      if (!record || typeof record !== 'object') {
+        this.logger?.info('DBV2.applyFieldView.filterRecord', 'Invalid record - skipping', {
+          recordType: typeof record
+        });
+        return record;
+      }
+
+      const filtered: any = {};
+
+      // If readFields is specified, only include those fields (whitelist)
+      if (readFields && Array.isArray(readFields) && readFields.length > 0) {
+        for (const field of readFields) {
+          if (field in record) {
+            filtered[field] = record[field];
+          }
+        }
+        this.logger?.info('DBV2.applyFieldView.filterRecord', 'Applied readFields whitelist', {
+          tableName,
+          role: this.currentUser?.role,
+          readFieldsCount: readFields.length,
+          originalFields: Object.keys(record).length,
+          filteredFields: Object.keys(filtered).length,
+          originalFieldsList: Object.keys(record),
+          filteredFieldsList: Object.keys(filtered)
+        });
+        return filtered as T;
+      }
+
+      // Fallback: exclude __audit__ and __archived__ for non-superadmin if no readFields specified
+      const defaultExclude = ['__audit__', '__archived__'];
+      for (const key in record) {
+        if (!defaultExclude.includes(key)) {
+          filtered[key] = record[key];
+        }
+      }
+      this.logger?.info('DBV2.applyFieldView.filterRecord', 'Applied default field filtering', {
+        tableName,
+        role: this.currentUser?.role,
+        excludedFields: defaultExclude,
+        originalFields: Object.keys(record).length,
+        filteredFields: Object.keys(filtered).length
+      });
+      return filtered as T;
+    };
+
+    // Apply filtering to array or single record
+    if (Array.isArray(data)) {
+      this.logger?.info('DBV2.applyFieldView', 'Filtering array of records', {
+        recordCount: data.length
+      });
+      const result = data.map(filterRecord) as T[];
+      this.logger?.info('DBV2.applyFieldView', 'Array filtering completed', {
+        inputCount: data.length,
+        outputCount: result.length,
+        outputType: typeof result,
+        isOutputArray: Array.isArray(result)
+      });
+      return result;
+    } else {
+      this.logger?.info('DBV2.applyFieldView', 'Filtering single record');
+      const result = filterRecord(data);
+      this.logger?.info('DBV2.applyFieldView', 'Single record filtering completed', {
+        outputType: typeof result
+      });
+      return result;
+    }
+  }
+
+  /**
+   * Get role-based query filter for read operations (getData)
+   * Returns null for superadmin or if no query restrictions defined
+   * Uses get_all_query from table RBAC config with {{USER}} template substitution
+   */
+  /**
+   * Extract all table names from SQL query (including JOINs, subqueries, etc.)
+   * Excludes temp tables from WITH statements (CTEs)
+   * Returns array of unique real table names that need to be loaded
+   */
+  private extractTableNames(sqlQuery: string): string[] {
+    const tableNames: string[] = [];
+    const seenTables = new Set<string>();
+    const tempTables = new Set<string>();
+
+    // Normalize query: collapse all whitespace (including newlines) to single spaces
+    // This helps with parsing multiline queries with indentation
+    const normalizedQuery = sqlQuery.replace(/\s+/g, ' ').trim();
+
+    // First, find all temp tables defined in WITH statements (CTEs)
+    // Pattern: WITH temp_name AS (...), another_temp AS (...)
+    const withPattern = /\bWITH\s+([a-zA-Z_][a-zA-Z0-9_]*)\s+AS\s*\(/gi;
+    let withMatch;
+    while ((withMatch = withPattern.exec(normalizedQuery)) !== null) {
+      tempTables.add(withMatch[1]);
+    }
+
+    // Also handle comma-separated CTEs: WITH a AS (...), b AS (...)
+    const ctePattern = /,\s*([a-zA-Z_][a-zA-Z0-9_]*)\s+AS\s*\(/gi;
+    let cteMatch;
+    while ((cteMatch = ctePattern.exec(normalizedQuery)) !== null) {
+      tempTables.add(cteMatch[1]);
+    }
+
+    this.logger?.info('DBV2.extractTableNames', 'Found temp tables from WITH statements', {
+      tempTables: Array.from(tempTables)
+    });
+
+    // Pattern to match table names after FROM, JOIN, etc.
+    // Matches: FROM tablename, JOIN tablename, LEFT JOIN tablename, etc.
+    const patterns = [
+      /\bFROM\s+([a-zA-Z_][a-zA-Z0-9_]*)/gi,
+      /\bJOIN\s+([a-zA-Z_][a-zA-Z0-9_]*)/gi,
+      /\bLEFT\s+JOIN\s+([a-zA-Z_][a-zA-Z0-9_]*)/gi,
+      /\bRIGHT\s+JOIN\s+([a-zA-Z_][a-zA-Z0-9_]*)/gi,
+      /\bINNER\s+JOIN\s+([a-zA-Z_][a-zA-Z0-9_]*)/gi,
+      /\bOUTER\s+JOIN\s+([a-zA-Z_][a-zA-Z0-9_]*)/gi
+    ];
+
+    for (const pattern of patterns) {
+      let match;
+      while ((match = pattern.exec(normalizedQuery)) !== null) {
+        const tableName = match[1];
+        // Only add if it's not a temp table from WITH statement and not already seen
+        if (!tempTables.has(tableName) && !seenTables.has(tableName)) {
+          seenTables.add(tableName);
+          tableNames.push(tableName);
+        }
+      }
+    }
+
+    this.logger?.info('DBV2.extractTableNames', 'Extracted real table names from query', {
+      normalizedQuery,
+      tempTables: Array.from(tempTables),
+      realTables: tableNames,
+      count: tableNames.length
+    });
+
+    return tableNames;
+  }
+
+
+  /**
+   * Map our schema types to AlaSQL types
+   */
+  private mapToAlaSqlType(schemaType: string): string {
+    const typeMap: Record<string, string> = {
+      'string': 'STRING',
+      'number': 'NUMBER',
+      'datetime': 'STRING',  // Store dates as strings for easier comparison
+      'boolean': 'BOOLEAN',
+      'object': 'STRING',    // JSON stringified
+      'arrayOfObjects': 'STRING'  // JSON stringified
+    };
+    return typeMap[schemaType] || 'STRING';  // Default to STRING
+  }
+
+  /**
+   * Execute SQL query using AlaSQL temporary database
+   * Creates temp tables, populates them, executes query, and cleans up
+   * Supports full SQL: WITH, CTEs, subqueries, JOINs, etc.
+   */
+  private executeAlaSqlQuery(sqlQuery: string, tableNames: string[]): any[] {
+    const tempDbName = `temp_db_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+    const self = this;  // Preserve 'this' context for use in loops
+
+    try {
+      self.logger?.info('DBV2.executeAlaSqlQuery', 'Creating temporary AlaSQL database', {
+        tempDbName,
+        tableNames,
+        sqlQuery
+      });
+
+      // Create alasql instance by calling alasql() - returns a function we can use
+      // This instance will maintain the database context throughout
+      const db = alasql();
+
+      // Create temporary database and switch to it
+      db(`CREATE DATABASE ${tempDbName}`);
+      db(`USE ${tempDbName}`);
+
+      // Load and populate each table
+      for (const tableName of tableNames) {
+        try {
+          self.logger?.info('DBV2.executeAlaSqlQuery', `Loading table ${tableName}`);
+
+          // Get schema for proper table creation
+          const schema = self.getTableSchema(tableName);
+
+          // Load table data without RBAC filtering (we'll filter in the main query)
+          // Initialize table and get raw data directly from TableV2
+          self.initializeTable(tableName);
+          const table = self.tables.get(tableName);
+          if (!table) {
+            throw new GASErrorV2(
+              `Table ${tableName} not found`,
+              'DBV2.executeAlaSqlQuery',
+              { tableName },
+              self.logger?.getTraceId()
+            );
+          }
+          const data = table.getData();
+
+          // Create table with schema-based column definitions using proper type mapping
+          const columnDefs = Object.keys(schema)
+            .map(colName => {
+              const colType = schema[colName]?.type || 'string';
+              const alaSqlType = self.mapToAlaSqlType(colType);
+              return `${colName} ${alaSqlType}`;
+            })
+            .join(', ');
+
+          self.logger?.info('DBV2.executeAlaSqlQuery', `Creating table ${tableName}`, {
+            columnDefs,
+            columnCount: Object.keys(schema).length
+          });
+
+          db(`CREATE TABLE ${tableName} (${columnDefs})`);
+
+          // Insert data if available
+          if (data && data.data && data.data.length > 0) {
+            // Method 1: Bulk insert via direct assignment (fastest and simplest)
+            // Data is already properly typed from toArrayOfObjects() - booleans are boolean,
+            // datetimes are clean strings, etc. Let AlaSQL handle it natively.
+            db.tables[tableName].data = data.data;
+
+            self.logger?.info('DBV2.executeAlaSqlQuery', `Populated table ${tableName}`, {
+              recordCount: data.data.length
+            });
+          } else {
+            self.logger?.warn('DBV2.executeAlaSqlQuery', `Created empty table ${tableName}`);
+          }
+        } catch (tableError) {
+          self.logger?.warn('DBV2.executeAlaSqlQuery', `Failed to load table ${tableName}`, {
+            error: tableError.toString()
+          });
+          // Try to create empty table on error
+          try {
+            db(`CREATE TABLE ${tableName} (id STRING)`);
+          } catch (e) {
+            // Ignore if table creation fails
+          }
+        }
+      }
+
+      // Execute the original query AS-IS (no conversion needed!)
+      // Execute directly in the current temp database context (already set with USE)
+      // Use the db instance we created
+      self.logger?.info('DBV2.executeAlaSqlQuery', 'Executing query on temp database', {
+        sqlQuery
+      });
+
+      const result = db(sqlQuery);
+
+      self.logger?.info('DBV2.executeAlaSqlQuery', 'Query executed successfully', {
+        resultType: typeof result,
+        isArray: Array.isArray(result),
+        resultLength: Array.isArray(result) ? result.length : 'N/A'
+      });
+
+      return result;
+
+    } catch (error) {
+      const wrappedError = GASErrorV2.wrapError(
+        error,
+        'Failed to execute query',
+        'DBV2.executeAlaSqlQuery',
+        { sqlQuery },
+        self.logger?.getTraceId()
+      );
+      self.logger?.error(wrappedError);
+      throw wrappedError;
+    } finally {
+      // Cleanup: drop database
+      try {
+        alasql()(`USE alasql`); // Switch back to default database
+        alasql()(`DROP DATABASE IF EXISTS ${tempDbName}`);
+        self.logger?.info('DBV2.executeAlaSqlQuery', 'Cleaned up temporary database', {
+          tempDbName
+        });
+      } catch (cleanupError) {
+        self.logger?.warn('DBV2.executeAlaSqlQuery', 'Failed to cleanup temp database', {
+          tempDbName,
+          error: cleanupError.toString()
+        });
+      }
+    }
+  }
+
+  private getRoleQueryFilter(tableName: string): string | null {
+    this.logger?.info('DBV2.getRoleQueryFilter', 'Starting role query filter lookup', {
+      tableName,
+      currentUserRole: this.currentUser?.role,
+      currentUserEmail: this.currentUser?.email
+    });
+
+    if (this.currentUser?.role === 'superadmin') {
+      this.logger?.info('DBV2.getRoleQueryFilter', 'Superadmin detected - no query filter');
+      return null;
+    }
+
+    if (!this.currentUser?.role) {
+      this.logger?.info('DBV2.getRoleQueryFilter', 'No user role - no query filter');
+      return null;
+    }
+
+    const userRole = this.currentUser.role;
+    const userEmail = this.currentUser.email;
+
+    // Get table config
+    let tableConfig = this.config.tables?.[tableName];
+    if (!tableConfig && this.config.systemTables) {
+      tableConfig = this.config.systemTables[tableName] as any;
+    }
+
+    this.logger?.info('DBV2.getRoleQueryFilter', 'Table config lookup', {
+      tableName,
+      hasTableConfig: !!tableConfig,
+      configKeys: tableConfig ? Object.keys(tableConfig) : []
+    });
+
+    if (!tableConfig) {
+      this.logger?.info('DBV2.getRoleQueryFilter', 'No table config found');
+      return null;
+    }
+
+    // Get RBAC rule for this table and role
+    const rbacRule = (tableConfig as any).rbac?.[userRole];
+
+    this.logger?.info('DBV2.getRoleQueryFilter', 'RBAC rule lookup', {
+      userRole,
+      hasRbacRule: !!rbacRule,
+      rbacRuleKeys: rbacRule ? Object.keys(rbacRule) : [],
+      get_all_query: rbacRule?.get_all_query
+    });
+
+    if (!rbacRule) {
+      this.logger?.info('DBV2.getRoleQueryFilter', 'No RBAC rule for role');
+      return null;
+    }
+
+    // Get get_all_query and substitute {{USER}} with current user email
+    let query = rbacRule.get_all_query;
+    if (!query || query === '') {
+      this.logger?.info('DBV2.getRoleQueryFilter', 'No get_all_query defined');
+      return null; // No query = method not supported
+    }
+
+    this.logger?.info('DBV2.getRoleQueryFilter', 'Original query before substitution', {
+      query,
+      userEmail,
+      hasUserPlaceholder: query.includes('{{USER}}')
+    });
+
+    // Replace {{USER}} template with actual email (no extra quotes - template already has them)
+    query = query.replace(/\{\{USER\}\}/g, userEmail);
+
+    this.logger?.info('DBV2.getRoleQueryFilter', 'Query after substitution', {
+      tableName,
+      userRole,
+      userEmail,
+      query,
+      queryLength: query.length
+    });
+
+    return query;
+  }
+
+  /**
+   * Get role-based query filter for getById operations
+   * Returns null for superadmin or if no query restrictions defined
+   * Uses get_by_id_query from table RBAC config with {{USER}} and {{ID}} template substitution
+   */
+  private getRoleGetByIdFilter(tableName: string, id: string): string | null {
+    if (this.currentUser?.role === 'superadmin') {
+      return null;
+    }
+
+    if (!this.currentUser?.role) {
+      return null;
+    }
+
+    const userRole = this.currentUser.role;
+    const userEmail = this.currentUser.email;
+
+    // Get table config
+    let tableConfig = this.config.tables?.[tableName];
+    if (!tableConfig && this.config.systemTables) {
+      tableConfig = this.config.systemTables[tableName] as any;
+    }
+
+    if (!tableConfig) {
+      return null;
+    }
+
+    // Get RBAC rule for this table and role
+    const rbacRule = (tableConfig as any).rbac?.[userRole];
+    if (!rbacRule) {
+      return null;
+    }
+
+    // Get get_by_id_query and substitute {{USER}} and {{ID}}
+    let query = rbacRule.get_by_id_query;
+    if (!query || query === '') {
+      return null; // No query = method not supported
+    }
+
+    // Replace templates with actual values (no extra quotes - template already has them)
+    query = query.replace(/\{\{USER\}\}/g, userEmail);
+    query = query.replace(/\{\{ID\}\}/g, id);
+
+    this.logger?.debug('DBV2.getRoleGetByIdFilter', 'Applied RBAC getById filter', { tableName, userRole, id, query });
+    return query;
+  }
+
+  /**
+   * Filter writable fields for mutations based on role restrictions
+   * Superadmin can write all fields
+   * Other roles are restricted by writableFields/readOnlyFields
+   */
+  private filterWritableData(data: any, tableName: string): any {
+    // Superadmin bypasses all write restrictions
+    if (this.currentUser?.role === 'superadmin') {
+      return data;
+    }
+
+    if (!this.config.roleViews || !this.currentUser?.role) {
+      return data; // No restrictions
+    }
+
+    const roleProfile = this.config.roleViews[this.currentUser.role];
+    if (!roleProfile || !roleProfile.tables[tableName]) {
+      return data; // No restrictions for this role/table
+    }
+
+    const tableView = roleProfile.tables[tableName];
+    const filtered: any = {};
+
+    // If writableFields is specified, only allow those fields (whitelist)
+    if (tableView.writableFields && tableView.writableFields.length > 0) {
+      for (const field of tableView.writableFields) {
+        if (field in data) {
+          filtered[field] = data[field];
+        }
+      }
+      return filtered;
+    }
+
+    // If readOnlyFields is specified, exclude those fields (blacklist)
+    if (tableView.readOnlyFields && tableView.readOnlyFields.length > 0) {
+      for (const key in data) {
+        if (!tableView.readOnlyFields.includes(key)) {
+          filtered[key] = data[key];
+        }
+      }
+      return filtered;
+    }
+
+    // No write restrictions, return as-is
+    return data;
+  }
+
+  /**
+   * Apply relations to data based on view configuration
+   * Joins related table data into the result
+   */
+  private applyRelations<T extends Record<string, any>>(
+    data: T | T[],
+    tableName: string
+  ): T | T[] {
+    if (!this.config.roleViews || !this.currentUser?.role) {
+      return data;
+    }
+
+    const roleProfile = this.config.roleViews[this.currentUser.role];
+    if (!roleProfile || !roleProfile.tables[tableName]) {
+      return data;
+    }
+
+    const tableView = roleProfile.tables[tableName];
+    if (!tableView.relations || tableView.relations.length === 0) {
+      return data;
+    }
+
+    // Helper to apply relations to a single record
+    const applyToRecord = (record: T): T => {
+      const enriched = { ...record };
+
+      for (const relation of tableView.relations!) {
+        const foreignKeyValue = record[relation.foreignKey];
+        if (!foreignKeyValue) {
+          enriched[relation.as] = relation.multiple ? [] : null;
+          continue;
+        }
+
+        // Initialize and get related table
+        this.initializeTable(relation.table);
+        const relatedTable = this.tables.get(relation.table);
+        if (!relatedTable) {
+          this.logger?.warn('DBV2.applyRelations', `Related table not found`, { relation: relation.table });
+          enriched[relation.as] = relation.multiple ? [] : null;
+          continue;
+        }
+
+        const relatedKey = relation.relatedKey || 'id';
+
+        if (relation.multiple) {
+          // One-to-many: get all matching records
+          const allData = relatedTable.getData();
+          const matched = (allData.data || []).filter((item: any) => item[relatedKey] === foreignKeyValue);
+
+          // Apply field filtering if specified
+          if (relation.fields && relation.fields.length > 0) {
+            enriched[relation.as] = matched.map((item: any) => {
+              const filtered: any = {};
+              for (const field of relation.fields!) {
+                if (field in item) {
+                  filtered[field] = item[field];
+                }
+              }
+              return filtered;
+            });
+          } else {
+            enriched[relation.as] = matched;
+          }
+        } else {
+          // One-to-one or many-to-one: get single record
+          const allData = relatedTable.getData();
+          const matched = (allData.data || []).find((item: any) => item[relatedKey] === foreignKeyValue);
+
+          if (matched) {
+            // Apply field filtering if specified
+            if (relation.fields && relation.fields.length > 0) {
+              const filtered: any = {};
+              for (const field of relation.fields!) {
+                if (field in matched) {
+                  filtered[field] = matched[field];
+                }
+              }
+              enriched[relation.as] = filtered;
+            } else {
+              enriched[relation.as] = matched;
+            }
+          } else {
+            enriched[relation.as] = null;
+          }
+        }
+      }
+
+      return enriched;
+    };
+
+    // Apply to array or single record
+    if (Array.isArray(data)) {
+      return data.map(applyToRecord) as T[];
+    } else {
+      return applyToRecord(data);
+    }
+  }
+
+  private initializeTable(tableName: string): void {
+    if (this.tables.has(tableName)) {
+      return; // Already initialized
+    }
+
+    const tableConfig = this.config.tables[tableName];
+    if (!tableConfig) {
+      throw new GASErrorV2(
+        `No table configuration found for table name '${tableName}'`,
+        'DBV2.initializeTable',
+        { tableName }, this.logger?.getTraceId()
+      );
+    }
+
+    // Get runtime state (counter, last_update) from cache if caching enabled
+    const runtimeState = this.getRuntimeState(tableName);
+    if (this.config.tableCaching?.enabled && runtimeState) {
+      // Sync counter from runtime state
+      this.logger?.debug('DBV2.initializeTable', `Initializing table with runtime state`, {
+        tableName,
+        counter: runtimeState.counter,
+        spreadsheetId: runtimeState.spreadsheetId
+      });
+    }
+
+    const table = new TableV2(
+      tableName,
+      tableConfig,
+      runtimeState,
+      this.config.metadataSpreadsheetId,
+      this.logger,
+      this  // Pass DBV2 instance for notification rules
+    );
+    const idGenerator = this.getTableIdGenerator(table, tableConfig.idGenerator);
+    table.setIdGenerator(idGenerator);
+
+    this.tables.set(tableName, table);
+  }
+
+  private getTableIdGenerator(table: TableV2, generator: string = 'EXTERNAL') {
+    // Parse generator if it's JSON (from metadata)
+    let generatorConfig: any = generator;
+    if (typeof generator === 'string' && generator.startsWith('{')) {
+      try {
+        generatorConfig = JSON.parse(generator);
+      } catch (e) {
+        // If parsing fails, treat as simple string
+        generatorConfig = { type: 'system', name: generator };
+      }
+    } else if (typeof generator === 'string') {
+      generatorConfig = { type: 'system', name: generator };
+    }
+
+    const generatorType = generatorConfig.type || 'system';
+    const generatorName = generatorConfig.name || 'EXTERNAL';
+
+    // EXTERNAL - ID provided by caller
+    if (generatorName === 'EXTERNAL' || generatorName === '') {
+      return {
+        name: 'EXTERNAL',
+      };
+    }
+
+    // DEFAULT - Simple counter-based ID
+    if (generatorName === 'DEFAULT') {
+      return {
+        name: 'DEFAULT',
+        nextId: (counter: number) => counter,
+      };
+    }
+
+    // UUID - Dynamic UUID based on timestamp + counter (changes each run)
+    if (generatorName === 'UUID') {
+      return {
+        name: 'UUID',
+        class: UUID,
+        paramsFn: (data: any, counter: number) => {
+          return [Utilities.base64Encode(JSON.stringify({
+            tableName: table.getTableName(),
+            timestamp: new Date().getTime(),
+            counter: counter
+          }))];
+        }
+      };
+    }
+
+    // STATIC_UUID - Static UUID based on data + counter (deterministic, same data = same ID)
+    if (generatorName === 'STATIC_UUID') {
+      return {
+        name: 'STATIC_UUID',
+        class: pdUUIDStatic,
+        paramsFn: (data: any, counter: number) => {
+          return [Utilities.base64Encode(JSON.stringify({
+            tableName: table.getTableName(),
+            data: data,
+            counter: counter
+          }))];
+        }
+      };
+    }
+
+    // CUSTOM - Custom generator with function specification
+    if (generatorName === 'CUSTOM' || generatorType === 'custom') {
+      const customConfig = generatorConfig.config || {};
+
+      // Custom generator requires a function specification
+      if (!customConfig.function) {
+        throw new GASErrorV2(
+          `CUSTOM generator requires a 'function' specification in config`,
+          'DBV2.getTableIdGenerator',
+          { generator: generatorConfig },
+          this.logger?.getTraceId()
+        );
+      }
+
+      // The custom function should return an ID given (data, counter)
+      // Example config: { type: "custom", name: "CUSTOM", config: { function: "(data, counter) => data.email + '_' + counter" } }
+      let customFn: Function;
+      try {
+        customFn = eval(`(${customConfig.function})`);
+      } catch (error) {
+        throw new GASErrorV2(
+          `Failed to evaluate CUSTOM generator function`,
+          'DBV2.getTableIdGenerator',
+          { generator: generatorConfig, error: error },
+          this.logger?.getTraceId()
+        );
+      }
+
+      return {
+        name: 'CUSTOM',
+        class: {
+          generate: customFn
+        },
+        paramsFn: (data: any, counter: number) => {
+          return [data, counter];
+        }
+      };
+    }
+
+    // Legacy support for old generator names
+    if (generatorName === "pdUUID") {
+      return {
+        name: 'UUID',
+        class: pdUUID,
+        paramsFn: (data: any, counter: number) => {
+          return [Utilities.base64Encode(JSON.stringify({ tableName: table.getTableName(), data: data, counter: counter }))];
+        }
+      };
+    }
+
+    if (generatorName === "pdUUIDStatic") {
+      return {
+        name: 'STATIC_UUID',
+        class: pdUUIDStatic,
+        paramsFn: (data: any, counter: number) => {
+          return [Utilities.base64Encode(JSON.stringify({ tableName: table.getTableName(), counter: counter }))];
+        }
+      };
+    }
+
+    // Default to EXTERNAL if unknown
+    this.logger?.warn('DBV2.getTableIdGenerator', `Unknown generator: ${generatorName}, defaulting to EXTERNAL`);
+    return {
+      name: 'EXTERNAL',
+    };
+  }
+
+  listTables(): string[] {
+    try {
+      const tables = Object.keys(this.config.tables);
+      this.logger?.info('DBV2.listTables', 'Listing tables', { tables });
+      return tables;
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        "Failed to list tables",
+        "DBV2.listTables",
+        {},
+        this.logger?.getTraceId()
+      );
+      return [];
+    }
+  }
+
+  getTableSchema(tableName: string): TableSchema {
+    try {
+      this.initializeTable(tableName);
+      const table = this.tables.get(tableName);
+      if (!table) {
+        throw new GASErrorV2(
+          `No table registered with name '${tableName}'`,
+          'DBV2.getTableSchema',
+          { tableName }, this.logger?.getTraceId()
+        );
+      }
+      const schema = table.getSchema();
+      this.logger?.info('DBV2.getTableSchema', `Table schema retrieved for '${tableName}'`, { schema });
+      return schema;
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        "Failed to get table schema",
+        "DBV2.getTableSchema",
+        { tableName },
+        this.logger?.getTraceId()
+      );
+      return {};
+    }
+  }
+
+  getAllTablesFreshness(): { [tableName: string]: { lastUpdate: number; lastUpdateHash: string } } {
+    try {
+      // Get freshness from cached runtime states
+      const scriptCache = CacheService.getScriptCache();
+      const cacheKey = this.getTableCacheKey();
+      const cachedData = scriptCache.get(cacheKey);
+
+      if (!cachedData) {
+        this.logger?.warn('DBV2.getAllTablesFreshness', 'Runtime state cache is empty');
+        return {};
+      }
+
+      const runtimeStates: TableRuntimeState[] = JSON.parse(cachedData);
+      const freshness: any = {};
+
+      // Extract freshness data from each runtime state (skip __sys__tables__)
+      for (const state of runtimeStates) {
+        if (state.tableName === '__sys__tables__') {
+          continue; // Skip system table
+        }
+        freshness[state.tableName] = {
+          lastUpdate: state.lastUpdate || 0, // Unix timestamp (milliseconds)
+          lastUpdateHash: state.lastUpdateHash || ''
+        };
+      }
+
+      this.logger?.info('DBV2.getAllTablesFreshness', 'Freshness data retrieved from runtime states', { tableCount: Object.keys(freshness).length });
+      return freshness;
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        "Failed to get freshness data",
+        "DBV2.getAllTablesFreshness",
+        {},
+        this.logger?.getTraceId()
+      );
+      return {};
+    }
+  }
+
+  getTableConfig(tableName: string): TableConfigV2 | null {
+    try {
+      if (!this.config.tables || !this.config.tables[tableName]) {
+        this.logger?.warn('DBV2.getTableConfig', `Table config not found for: ${tableName}`);
+        return null;
+      }
+
+      return this.config.tables[tableName];
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        "Failed to get table config",
+        "DBV2.getTableConfig",
+        { tableName },
+        this.logger?.getTraceId()
+      );
+      return null;
+    }
+  }
+
+  /**
+   * Get raw data from table without RBAC filtering
+   * Used internally for loading tables referenced in JOIN queries
+   */
+  private getDataRaw(tableName: string, checkPermissions: boolean = true): any {
+    try {
+      if (checkPermissions) {
+        this.checkPermission(tableName, 'read');
+      }
+      this.logger?.debug('DBV2.getDataRaw', `Fetching raw data from table ${tableName}...`, { tableName });
+      this.initializeTable(tableName);
+      const table = this.tables.get(tableName);
+      if (!table) {
+        throw new GASErrorV2(
+          `No table registered with name '${tableName}'`,
+          'DBV2.getDataRaw',
+          { tableName }, this.logger?.getTraceId()
+        );
+      }
+
+      // Get data from cache or spreadsheet
+      const cacheKey = `table_${tableName}`;
+      if (this.enableCaching && this.cache.has(cacheKey)) {
+        const cachedData = this.cache.get(cacheKey);
+        this.logger?.debug('DBV2.getDataRaw', `Returning cached data for table ${tableName}`, { size: cachedData?.data?.length || 0 });
+        return cachedData;
+      }
+
+      // Load from spreadsheet
+      const sheet = this.getSheet(tableName);
+      const data = this.readSheetData(sheet, tableName);
+
+      // Cache the result
+      if (this.enableCaching && data) {
+        this.cache.set(cacheKey, {
+          data: data,
+          timestamp: new Date()
+        });
+      }
+
+      return { data, total: data.length };
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        "Failed to get raw data",
+        "DBV2.getDataRaw",
+        { tableName },
+        this.logger?.getTraceId()
+      );
+      throw error;
+    }
+  }
+
+  getData(tableName: string, pageStart: number = 0, pageSize: number = 0, applyView: boolean = false): any[] {
+    try {
+      this.checkPermission(tableName, 'read');
+      this.logger?.debug('DBV2.getData', `Fetching data from table ${tableName}...`, { tableName, pageStart, pageSize, applyView });
+      this.initializeTable(tableName);
+      const table = this.tables.get(tableName);
+      if (!table) {
+        throw new GASErrorV2(
+          `No table registered with name '${tableName}'`,
+          'DBV2.getData',
+          { tableName }, this.logger?.getTraceId()
+        );
+      }
+
+      // Check cache first
+      const cacheKey = `${tableName}_${pageStart}_${pageSize}`;
+      if (this.enableCaching) {
+        const cachedEntry = this.cache.get(cacheKey);
+        if (cachedEntry && (new Date().getTime() - cachedEntry.timestamp) < this.cacheTTL) {
+          this.logger?.debug('DBV2.getData', 'Returning cached data', { cacheKey });
+          return cachedEntry.data;
+        }
+      }
+
+      let data = table.getData(pageStart, pageSize);
+
+      // Apply query-based filtering for non-superadmin roles
+      const roleQuery = this.getRoleQueryFilter(tableName);
+      this.logger?.info('DBV2.getData', 'RBAC Query Check', {
+        tableName,
+        hasRoleQuery: !!roleQuery,
+        roleQuery,
+        hasData: !!data,
+        dataLength: data?.data?.length,
+        currentUser: this.currentUser
+      });
+
+      if (roleQuery && data && data.data && data.data.length > 0) {
+        try {
+          // Extract all table names from query (supports JOINs, WITH, subqueries, etc.)
+          const tableNames = this.extractTableNames(roleQuery);
+
+          this.logger?.info('DBV2.getData', 'Executing RBAC query with temp database', {
+            roleQuery,
+            tableNames,
+            tableCount: tableNames.length,
+            inputDataCount: data.data.length
+          });
+
+          const originalCount = data.data.length;
+
+          // Execute query using temporary AlaSQL database
+          // This supports full SQL: WITH, CTEs, subqueries, JOINs, UNION, etc.
+          const filtered = this.executeAlaSqlQuery(roleQuery, tableNames);
+
+          this.logger?.info('DBV2.getData', 'AlaSQL execution result', {
+            filteredType: typeof filtered,
+            isArray: Array.isArray(filtered),
+            filteredLength: Array.isArray(filtered) ? filtered.length : 'N/A'
+          });
+
+          // CRITICAL: Validate filtering worked correctly (fail closed, not open)
+          if (!Array.isArray(filtered)) {
+            const error = new GASErrorV2(
+              'RBAC filtering failed - AlaSQL did not return an array',
+              'DBV2.getData',
+              {
+                tableName,
+                resultType: typeof filtered,
+                resultConstructor: filtered?.constructor?.name,
+                roleQuery,
+                userRole: this.currentUser?.role,
+                userEmail: this.currentUser?.email
+              },
+              this.logger?.getTraceId()
+            );
+            this.logger?.error(error);
+            throw error;
+          }
+
+          // CRITICAL: If filtering returned same count as original, this might indicate filtering failed
+          // But only if the query has WHERE clause (actual filtering conditions)
+          // Queries like "SELECT * FROM table" legitimately return all records
+          const hasWhereClause = /\bWHERE\b/i.test(roleQuery);
+
+          if (filtered.length === originalCount && originalCount > 0 && hasWhereClause) {
+            this.logger?.warn('DBV2.getData', 'RBAC filtering may have failed - same record count before/after filter with WHERE clause', {
+              roleQuery,
+              originalCount,
+              filteredCount: filtered.length,
+              userRole: this.currentUser?.role,
+              userEmail: this.currentUser?.email,
+              tableName,
+              hasWhereClause
+            });
+
+            // For non-superadmin roles with WHERE clause, if count didn't change, this is suspicious
+            if (this.currentUser?.role !== 'superadmin') {
+              const error = new GASErrorV2(
+                'RBAC filtering suspicious - non-superadmin got all records despite WHERE clause',
+                'DBV2.getData',
+                {
+                  tableName,
+                  roleQuery,
+                  originalCount,
+                  filteredCount: filtered.length,
+                  userRole: this.currentUser?.role,
+                  userEmail: this.currentUser?.email,
+                  hasWhereClause
+                },
+                this.logger?.getTraceId()
+              );
+              this.logger?.error(error);
+              // Fail closed: don't return potentially unfiltered data
+              throw error;
+            }
+          }
+
+          data.data = filtered;
+          this.logger?.info('DBV2.getData', 'Applied role query filter successfully', {
+            roleQuery,
+            originalCount,
+            filteredCount: filtered.length,
+            userRole: this.currentUser?.role,
+            userEmail: this.currentUser?.email,
+            filteringWorked: filtered.length < originalCount || originalCount === 0
+          });
+        } catch (queryError) {
+          const wrappedError = GASErrorV2.wrapError(
+            queryError,
+            'Failed to apply role query filter - FAIL CLOSED',
+            'DBV2.getData',
+            {
+              tableName,
+              roleQuery,
+              userRole: this.currentUser?.role,
+              userEmail: this.currentUser?.email
+            },
+            this.logger?.getTraceId()
+          );
+          this.logger?.error(wrappedError);
+          // CRITICAL: Fail closed - re-throw error to prevent returning unfiltered data
+          throw wrappedError;
+        }
+      }
+
+      // Apply field-level view filtering based on role (only if applyView is true)
+      if (applyView && data && data.data) {
+        this.logger?.info('DBV2.getData', 'Before applyFieldView', {
+          dataType: typeof data.data,
+          isArray: Array.isArray(data.data),
+          length: data.data?.length
+        });
+
+        data.data = this.applyFieldView(data.data, tableName);
+
+        this.logger?.info('DBV2.getData', 'After applyFieldView', {
+          dataType: typeof data.data,
+          isArray: Array.isArray(data.data),
+          length: data.data?.length
+        });
+      }
+
+      this.logger?.info('DBV2.getData', `Data retrieved for table ${tableName}`, { size: data.data?.length || 0, viewApplied: applyView });
+
+      // Cache the result
+      if (this.enableCaching && data) {
+        this.cache.set(cacheKey, {
+          data: data,
+          timestamp: new Date().getTime(),
+          hash: data.lastUpdateHash || ''
+        });
+      }
+
+      return data;
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        "Failed to get data",
+        "DBV2.getData",
+        { tableName, pageStart, pageSize },
+        this.logger?.getTraceId()
+      );
+      // Return proper structure even on error
+      const table = this.tables.get(tableName);
+      return {
+        schema: table ? table.getSchema() : {},
+        data: []
+      };
+    }
+  }
+
+  getById(tableName: string, id: string, applyRelations: boolean = false): any {
+    try {
+      this.checkPermission(tableName, 'read');
+      this.logger?.debug('DBV2.getById', `Fetching item from table ${tableName}...`, { tableName, id, applyRelations });
+      this.initializeTable(tableName);
+      const table = this.tables.get(tableName);
+      if (!table) {
+        throw new GASErrorV2(
+          `No table registered with name '${tableName}'`,
+          'DBV2.getById',
+          { tableName }, this.logger?.getTraceId()
+        );
+      }
+      let data = table.getById(id);
+
+      // Apply getById query-based filtering for non-superadmin roles
+      const roleQuery = this.getRoleGetByIdFilter(tableName, id);
+      if (roleQuery && data) {
+        try {
+          // Extract table names from query
+          const tableNames = this.extractTableNames(roleQuery);
+
+          this.logger?.info('DBV2.getById', 'Executing RBAC getById query with temp database', {
+            roleQuery,
+            tableNames,
+            id
+          });
+
+          // Execute query using temporary AlaSQL database
+          const filtered = this.executeAlaSqlQuery(roleQuery, tableNames);
+
+          if (!filtered || filtered.length === 0) {
+            this.logger?.warn('DBV2.getById', 'Record filtered out by RBAC getById query', {
+              id,
+              roleQuery,
+              userRole: this.currentUser?.role,
+              userEmail: this.currentUser?.email
+            });
+            return null; // User doesn't have access to this record
+          }
+          data = filtered[0];
+        } catch (queryError) {
+          const wrappedError = GASErrorV2.wrapError(
+            queryError,
+            'Failed to apply RBAC getById filter - FAIL CLOSED',
+            'DBV2.getById',
+            {
+              tableName,
+              id,
+              roleQuery,
+              userRole: this.currentUser?.role,
+              userEmail: this.currentUser?.email
+            },
+            this.logger?.getTraceId()
+          );
+          this.logger?.error(wrappedError);
+          // Fail closed - deny access on error
+          return null;
+        }
+      }
+
+      // Apply field-level view filtering based on role
+      if (data) {
+        data = this.applyFieldView(data, tableName);
+      }
+
+      // Apply relations to enrich data (only if explicitly requested)
+      if (applyRelations && data) {
+        data = this.applyRelations(data, tableName);
+      }
+
+      this.logger?.info('DBV2.getById', `Data retrieved for ID ${id} in table ${tableName}`, { hasData: !!data, relationsApplied: applyRelations });
+      return data;
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        "Failed to get data by ID",
+        "DBV2.getById",
+        { tableName, id },
+        this.logger?.getTraceId()
+      );
+      return null;
+    }
+  }
+
+  /**
+   * Create a new record
+   * @param strategy - 'not_allowed' (default) throws error if ID exists, 'upsert' updates if exists
+   */
+  create(tableName: string, data: any, strategy: 'not_allowed' | 'upsert' = 'not_allowed'): any {
+    try {
+      console.log('[DBV2.create] START', {
+        tableName,
+        dataKeys: Object.keys(data),
+        strategy
+      });
+
+      if (this.debug) {
+        console.log('[DBV2.create] DEBUG - DBV2.create() received parameters:');
+        console.log('[DBV2.create] DEBUG - tableName =', tableName);
+        console.log('[DBV2.create] DEBUG - data =', data);
+        console.log('[DBV2.create] DEBUG - strategy =', strategy);
+      }
+
+      this.checkPermission(tableName, 'create');
+      if (strategy === 'upsert') {
+        this.checkPermission(tableName, 'update'); // Need update permission for upsert
+      }
+
+      console.log('[DBV2.create] Permissions checked');
+
+      // Filter writable fields based on role restrictions
+      const filteredData = this.filterWritableData(data, tableName);
+
+      console.log('[DBV2.create] Data filtered', {
+        originalKeys: Object.keys(data),
+        filteredKeys: Object.keys(filteredData)
+      });
+
+      this.logger?.debug('DBV2.create', `Creating item in table ${tableName}...`, { tableName, request: filteredData, strategy });
+
+      console.log('[DBV2.create] Initializing table');
+      this.initializeTable(tableName);
+      console.log('[DBV2.create] Table initialized');
+
+      const table = this.tables.get(tableName);
+      if (!table) {
+        console.log('[DBV2.create] ERROR: Table not found', { tableName });
+        throw new GASErrorV2(
+          `No table registered with name '${tableName}'`,
+          'DBV2.create',
+          { tableName }, this.logger?.getTraceId()
+        );
+      }
+
+      console.log('[DBV2.create] Table found');
+
+      const idGenerator = (table as any).idGenerator;
+
+      console.log('[DBV2.create] ID Generator', {
+        generatorName: idGenerator?.name,
+        hasClass: !!idGenerator?.class,
+        hasParamsFn: !!idGenerator?.paramsFn
+      });
+
+      // System-level validation: enforce generator-specific upsert rules
+      if (strategy === 'upsert') {
+        if (idGenerator.name === 'UUID' || idGenerator.name === 'CUSTOM' || idGenerator.name === 'DEFAULT') {
+          throw new GASErrorV2(
+            `Upsert strategy not allowed for ${idGenerator.name} generator (system-level restriction)`,
+            'DBV2.create',
+            { tableName, generatorName: idGenerator.name, strategy },
+            this.logger?.getTraceId()
+          );
+        }
+        // Only STATIC_UUID and EXTERNAL support upsert
+        if (idGenerator.name !== 'STATIC_UUID' && idGenerator.name !== 'EXTERNAL') {
+          throw new GASErrorV2(
+            `Upsert strategy only supported for STATIC_UUID and EXTERNAL generators`,
+            'DBV2.create',
+            { tableName, generatorName: idGenerator.name, strategy },
+            this.logger?.getTraceId()
+          );
+        }
+      }
+
+      // For upsert strategy, check if record exists first
+      if (strategy === 'upsert') {
+        const schema = table.getSchema();
+        const primaryKey = Object.keys(schema).find(key => schema[key].primaryKey) || 'id';
+        let id: any = null;
+
+        // Determine ID based on generator type
+        if (idGenerator.name === 'EXTERNAL') {
+          id = filteredData[primaryKey];
+          if (!id) {
+            throw new GASErrorV2(
+              `EXTERNAL generator with upsert requires ID in data field '${primaryKey}'`,
+              'DBV2.create',
+              { tableName, data: filteredData },
+              this.logger?.getTraceId()
+            );
+          }
+        } else if (idGenerator.name === 'STATIC_UUID') {
+          const counterState = (table as any).getCounter();
+          const params = idGenerator.paramsFn(filteredData, counterState);
+          id = idGenerator.class.generate(...params);
+        }
+
+        // Check if record exists
+        const existing = table.getById(id);
+
+        if (existing.data) {
+          // Record exists - update instead
+          const lockerId = `upsert_update_${tableName}_${id}_${new Date().getTime()}`;
+          return this.executeMutationWithLock(
+            'update',
+            tableName,
+            id,
+            null,
+            lockerId,
+            () => {
+              const result = table.update(id, filteredData);
+
+              // Update runtime state in __sys__tables__ (update timestamp/hash)
+              this.updateRuntimeState(tableName);
+
+              // Refresh cache
+              this.refreshTableCache();
+
+              this.logger?.info('DBV2.create', `Item updated via upsert in table ${tableName}`, { id, result });
+              return { action: 'updated', data: result };
+            }
+          );
+        }
+        // If not exists, fall through to create
+      }
+
+      // Create new record (not_allowed strategy or upsert when record doesn't exist)
+      console.log('[DBV2.create] About to create record', {
+        tableName,
+        filteredData: JSON.stringify(filteredData)
+      });
+
+      if (this.debug) {
+        console.log('[DBV2.create] DEBUG - Calling table.create() with', {
+          tableName,
+          filteredData: JSON.stringify(filteredData),
+          filteredDataType: typeof filteredData,
+          filteredDataConstructor: filteredData?.constructor?.name,
+          filteredDataKeys: Object.keys(filteredData)
+        });
+      }
+
+      const lockerId = `create_${tableName}_${new Date().getTime()}`;
+      return this.executeMutationWithLock(
+        'create',
+        tableName,
+        null,
+        null,
+        lockerId,
+        () => {
+          console.log('[DBV2.create] Inside executeMutationWithLock, calling table.create()');
+          if (this.debug) {
+            console.log('[DBV2.create] DEBUG - About to call: table.create(filteredData)');
+            console.log('[DBV2.create] DEBUG - table =', table);
+            console.log('[DBV2.create] DEBUG - filteredData parameter =', filteredData);
+          }
+          const result = table.create(filteredData);
+          console.log('[DBV2.create] table.create() returned', { result });
+
+          // Update runtime state in __sys__tables__ (update timestamp/hash, counter already incremented by TableV2.updateCounter)
+          this.updateRuntimeState(tableName);
+
+          // Refresh cache to get updated counter
+          this.refreshTableCache();
+
+          const action = strategy === 'upsert' ? { action: 'created', data: result } : result;
+          this.logger?.info('DBV2.create', `Item created in table ${tableName}`, { result, strategy });
+          return action;
+        }
+      );
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        "Failed to create item",
+        "DBV2.create",
+        { tableName, data },
+        this.logger?.getTraceId()
+      );
+      return null;
+    }
+  }
+
+  batchCreate(tableName: string, data: any[]): any {
+    try {
+      this.checkPermission(tableName, 'create');
+      this.logger?.debug('DBV2.batchCreate', `Batch creating items in table ${tableName}...`, { tableName });
+      this.initializeTable(tableName);
+      const table = this.tables.get(tableName);
+      if (!table) {
+        throw new GASErrorV2(
+          `No table registered with name '${tableName}'`,
+          'DBV2.batchCreate',
+          { tableName }, this.logger?.getTraceId()
+        );
+      }
+      const result = table.batchCreate(data);
+      this.logger?.info('DBV2.batchCreate', `Batch items created in table ${tableName}`, { result });
+      return result;
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        "Failed to batch create items",
+        "DBV2.batchCreate",
+        { tableName, data },
+        this.logger?.getTraceId()
+      );
+      return null;
+    }
+  }
+
+  update(tableName: string, id: any, data: any): any {
+    try {
+      this.checkPermission(tableName, 'update');
+
+      // Filter writable fields based on role restrictions
+      const filteredData = this.filterWritableData(data, tableName);
+
+      this.logger?.debug('DBV2.update', `Updating item in table ${tableName}...`, { tableName, id, data: filteredData });
+
+      // Wrap with two-level locking
+      const lockerId = `update_${tableName}_${id}_${new Date().getTime()}`;
+      return this.executeMutationWithLock(
+        'update',
+        tableName,
+        id,
+        null, // no deleteMode for update
+        lockerId,
+        () => {
+          this.initializeTable(tableName);
+          const table = this.tables.get(tableName);
+          if (!table) {
+            throw new GASErrorV2(
+              `No table registered with name '${tableName}'`,
+              'DBV2.update',
+              { tableName }, this.logger?.getTraceId()
+            );
+          }
+          const result = table.update(id, filteredData);
+
+          // Update runtime state in __sys__tables__ (update timestamp/hash)
+          this.updateRuntimeState(tableName);
+
+          // Refresh cache
+          this.refreshTableCache();
+
+          this.logger?.info('DBV2.update', `Item updated in table ${tableName}`, { result });
+          return result;
+        }
+      );
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        "Failed to update item",
+        "DBV2.update",
+        { tableName, id, data },
+        this.logger?.getTraceId()
+      );
+      return null;
+    }
+  }
+
+  batchUpdate(tableName: string, updates: { [id: string]: any }): any {
+    try {
+      this.logger?.debug('DBV2.batchUpdate', `Batch updating items in table ${tableName}...`, { tableName });
+      this.initializeTable(tableName);
+      const table = this.tables.get(tableName);
+      if (!table) {
+        throw new GASErrorV2(
+          `No table registered with name '${tableName}'`,
+          'DBV2.batchUpdate',
+          { tableName }, this.logger?.getTraceId()
+        );
+      }
+      const result = table.batchUpdate(updates);
+      this.logger?.info('DBV2.batchUpdate', `Batch items updated in table ${tableName}`, { result });
+      return result;
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        "Failed to batch update items",
+        "DBV2.batchUpdate",
+        { tableName, updates },
+        this.logger?.getTraceId()
+      );
+      return null;
+    }
+  }
+
+  delete(tableName: string, id: string): any {
+    try {
+      this.checkPermission(tableName, 'delete');
+      this.logger?.debug('DBV2.delete', `Deleting item in table ${tableName}...`, { tableName, id });
+
+      // Get table config to determine delete mode
+      this.initializeTable(tableName);
+      const table = this.tables.get(tableName);
+      if (!table) {
+        throw new GASErrorV2(
+          `No table registered with name '${tableName}'`,
+          'DBV2.delete',
+          { tableName }, this.logger?.getTraceId()
+        );
+      }
+
+      const tableConfig = this.config.tables[tableName];
+      const deleteMode = (tableConfig?.deleteMode || 'soft') as 'soft' | 'hard';
+
+      // Wrap with two-level locking
+      const lockerId = `delete_${tableName}_${id}_${new Date().getTime()}`;
+      return this.executeMutationWithLock(
+        'delete',
+        tableName,
+        id,
+        deleteMode,
+        lockerId,
+        () => {
+          const result = table.delete(id);
+
+          // Trigger database triggers after successful delete
+          try {
+            this.triggerDatabaseTriggers(tableName, 'delete', result);
+          } catch (triggerError) {
+            this.logger?.warn('DBV2.delete', `Database triggers failed: ${triggerError.toString()}`, { error: triggerError });
+          }
+
+          // Update runtime state in __sys__tables__ (update timestamp/hash)
+          this.updateRuntimeState(tableName);
+
+          // Refresh cache
+          this.refreshTableCache();
+
+          this.logger?.info('DBV2.delete', `Item with ID ${id} deleted from table ${tableName}`, { result });
+          return result;
+        }
+      );
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        "Failed to delete item",
+        "DBV2.delete",
+        { tableName, id },
+        this.logger?.getTraceId()
+      );
+      return null;
+    }
+  }
+
+  batchDelete(tableName: string, ids: string[]): any {
+    try {
+      this.logger?.debug('DBV2.batchDelete', `Batch deleting items in table ${tableName}...`, { tableName, request: ids });
+      this.initializeTable(tableName);
+      const table = this.tables.get(tableName);
+      if (!table) {
+        throw new GASErrorV2(
+          `No table registered with name '${tableName}'`,
+          'DBV2.batchDelete',
+          { tableName }, this.logger?.getTraceId()
+        );
+      }
+      const result = table.batchDelete(ids);
+      this.logger?.info('DBV2.batchDelete', `Batch items deleted from table ${tableName}`, { result });
+      return result;
+    } catch (error) {
+      GASErrorV2.handleError(
+        error,
+        "Failed to batch delete items",
+        "DBV2.batchDelete",
+        { tableName, ids },
+        this.logger?.getTraceId()
+      );
+      return null;
+    }
+  }
+
+  // Query method using AlaSQL for cross-table queries
+  query(sqlExpression: string): any {
+    try {
+      this.logger?.debug('DBV2.query', `Executing SQL query`, { sqlExpression });
+
+      // Use new method to extract table names (handles CTEs, JOINs, subqueries)
+      const tableNames = this.extractTableNames(sqlExpression);
+
+      this.logger?.info('DBV2.query', `Extracted tables from query`, {
+        tableNames,
+        tableCount: tableNames.length
+      });
+
+      // Check permissions for all tables in query
+      for (const tableName of tableNames) {
+        this.checkPermission(tableName, 'query');
+      }
+
+      // Execute query using new temp database method
+      // This supports WITH statements, CTEs, complex JOINs, etc.
+      const result = this.executeAlaSqlQuery(sqlExpression, tableNames);
+
+      this.logger?.info('DBV2.query', `Query executed successfully`, {
+        resultSize: result.length
+      });
+
+      return {
+        data: result,
+        resultSize: result.length,
+      };
+    } catch (error) {
+      // Log detailed error information for debugging
+      console.log('[DBV2.query] ERROR - Query failed');
+      console.log('[DBV2.query] SQL:', sqlExpression);
+      console.log('[DBV2.query] Error message:', (error as Error).message);
+      console.log('[DBV2.query] Error name:', (error as Error).name);
+      console.log('[DBV2.query] Error stack:', (error as Error).stack);
+      console.log('[DBV2.query] Full error:', JSON.stringify(error, null, 2));
+
+      GASErrorV2.handleError(
+        error,
+        "Failed to execute query",
+        "DBV2.query",
+        {
+          sqlExpression,
+          errorMessage: (error as Error).message,
+          errorName: (error as Error).name
+        },
+        this.logger?.getTraceId()
+      );
+      return {
+        data: [],
+        resultSize: 0,
+      };
+    }
+  }
+
+}
+
+export { DBV2, TableV2, DBConfigV2, TableConfig, TableSchema, SchemaColumn };
+export default DBV2;