Restrict column updates to LWW-only for server-origin rows with origin tracking and generator safety (#40)

* Initial plan

* Implement LWW column restriction with system_is_local_origin tracking

Co-authored-by: graknol <1364029+graknol@users.noreply.github.com>

* Add documentation and improve bulkLoad handling for system_is_local_origin

Co-authored-by: graknol <1364029+graknol@users.noreply.github.com>

* Improve isLocalOrigin documentation for null safety

Co-authored-by: graknol <1364029+graknol@users.noreply.github.com>

* Modify generator to only create setters for LWW columns

Co-authored-by: graknol <1364029+graknol@users.noreply.github.com>

* Update documentation to reflect LWW-only setter generation

Co-authored-by: graknol <1364029+graknol@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: graknol <1364029+graknol@users.noreply.github.com>

Author: Copilot

declarative_sqlite/lib/declarative_sqlite.dart

@@ -40,6 +40,7 @@ export 'src/streaming/query_stream_manager.dart';
 // Synchronization
 export 'src/sync/dirty_row.dart';
 export 'src/sync/dirty_row_store.dart';
+export 'src/sync/sqlite_dirty_row_store.dart';
 export 'src/scheduling/task_scheduler.dart';
 export 'src/sync/hlc.dart';
 export 'src/files/file_repository.dart';

declarative_sqlite/lib/src/builders/schema_builder.dart

@@ -103,6 +103,7 @@ class SchemaBuilder {
     builder.text('table_name').notNull('default');
     builder.guid('row_id').notNull('00000000-0000-0000-0000-000000000000');
     builder.text('hlc').notNull(Hlc.min.toString());
+    builder.integer('is_full_row').notNull(1); // 1 = full row, 0 = LWW columns only
     builder.key(['table_name', 'row_id']).primary();
     return builder.build();
   }

declarative_sqlite/lib/src/builders/table_builder.dart

@@ -86,6 +86,15 @@ class TableBuilder {
               isParent: false,
               isLww: false,
             ),
+            DbColumn(
+              name: 'system_is_local_origin',
+              logicalType: 'integer',
+              type: 'INTEGER', // Boolean as 0/1
+              isNotNull: true,
+              defaultValue: '1', // Default to local origin for new rows
+              isParent: false,
+              isLww: false,
+            ),
           ];
 
     return DbTable(

declarative_sqlite/lib/src/db_record.dart

@@ -77,6 +77,13 @@ abstract class DbRecord {
     return value != null ? Hlc.parse(value as String) : null;
   }
 
+  /// Gets whether this record was created locally (true) or came from server (false)
+  /// Returns true if system_is_local_origin is 1 or true, false otherwise (including null)
+  bool get isLocalOrigin {
+    final value = getRawValue('system_is_local_origin');
+    return value == 1 || value == true;
+  }
+
   /// Gets a raw value from the data map without type conversion
   Object? getRawValue(String columnName) {
     return _data[columnName];
@@ -129,6 +136,15 @@ abstract class DbRecord {
           'Column $columnName does not exist in update table $_updateTableName',
         );
       }
+      
+      // Restrict updates to LWW columns only for rows that came from server
+      if (!isLocalOrigin && !column.isLww && !columnName.startsWith('system_')) {
+        throw StateError(
+          'Column $columnName is not marked as LWW and cannot be updated on rows that originated from server. '
+          'Only LWW columns can be updated on existing server rows. '
+          'This row is marked as non-local origin (system_is_local_origin = ${getRawValue('system_is_local_origin')})',
+        );
+      }
     }
 
     final column = _getColumn(columnName);

declarative_sqlite/lib/src/declarative_database.dart

@@ -739,7 +739,7 @@ class DeclarativeDatabase {
       final serializedValues = _serializeValuesForTable(tableName, values);
 
       final systemId = await _insert(tableName, serializedValues, now);
-      await dirtyRowStore?.add(tableName, systemId, now);
+      await dirtyRowStore?.add(tableName, systemId, now, true); // Full row for new inserts
 
       // Notify streaming queries of the change
       await _streamManager.notifyTableChanged(tableName);
@@ -766,6 +766,44 @@ class DeclarativeDatabase {
     if (valuesToInsert['system_created_at'] == null) {
       valuesToInsert['system_created_at'] = hlc.toString();
     }
+    // Mark as local origin (created by client)
+    if (valuesToInsert['system_is_local_origin'] == null) {
+      valuesToInsert['system_is_local_origin'] = 1;
+    }
+
+    for (final col in tableDef.columns) {
+      if (col.isLww) {
+        valuesToInsert['${col.name}__hlc'] = hlc.toString();
+      }
+    }
+
+    await _db.insert(tableName, valuesToInsert);
+
+    return valuesToInsert['system_id']! as String;
+  }
+
+  /// Internal method for inserting rows from server during bulkLoad
+  /// Marks the row as non-local origin (came from server)
+  Future<String> _insertFromServer(
+      String tableName, Map<String, Object?> values, Hlc hlc) async {
+    final tableDef = _getTableDefinition(tableName);
+
+    // Convert FilesetField values to database strings
+    final convertedValues = _convertFilesetFieldsToValues(tableName, values);
+
+    // Apply default values for missing columns
+    final valuesToInsert = _applyDefaultValues(tableName, convertedValues);
+    
+    // Add system columns
+    valuesToInsert['system_version'] = hlc.toString();
+    if (valuesToInsert['system_id'] == null) {
+      valuesToInsert['system_id'] = Uuid().v4();
+    }
+    if (valuesToInsert['system_created_at'] == null) {
+      valuesToInsert['system_created_at'] = hlc.toString();
+    }
+    // Mark as server origin (not created locally)
+    valuesToInsert['system_is_local_origin'] = 0;
 
     for (final col in tableDef.columns) {
       if (col.isLww) {
@@ -793,7 +831,7 @@ class DeclarativeDatabase {
     return await DbExceptionWrapper.wrapUpdate(() async {
       final rowsToUpdate = await query(
         (q) {
-          q.from(tableName).select('system_id');
+          q.from(tableName).select('system_id, system_is_local_origin');
           if (where != null) {
             q.where(RawSqlWhereClause(where, whereArgs));
           }
@@ -814,8 +852,9 @@ class DeclarativeDatabase {
 
       if (result > 0) {
         for (final row in rowsToUpdate) {
+          final isLocalOrigin = row.getValue<int>('system_is_local_origin') == 1;
           await dirtyRowStore?.add(
-              tableName, row.getValue<String>('system_id')!, now);
+              tableName, row.getValue<String>('system_id')!, now, isLocalOrigin);
         }
         // Notify streaming queries of the change
         await _streamManager.notifyTableChanged(tableName);
@@ -906,7 +945,7 @@ class DeclarativeDatabase {
 
       final rowsToDelete = await query(
         (q) {
-          q.from(tableName).select('system_id');
+          q.from(tableName).select('system_id, system_is_local_origin');
           if (where != null) {
             q.where(RawSqlWhereClause(where, whereArgs));
           }
@@ -922,8 +961,9 @@ class DeclarativeDatabase {
       if (result > 0) {
         final now = hlcClock.now();
         for (final row in rowsToDelete) {
+          final isLocalOrigin = row.getValue<int>('system_is_local_origin') == 1;
           await dirtyRowStore?.add(
-              tableName, row.getValue<String>('system_id')!, now);
+              tableName, row.getValue<String>('system_id')!, now, isLocalOrigin);
         }
         // Notify streaming queries of the change
         await _streamManager.notifyTableChanged(tableName);
@@ -1040,9 +1080,11 @@ class DeclarativeDatabase {
   /// - If a local row with the same `system_id` exists, it's an UPDATE.
   ///   - LWW columns are only updated if the incoming HLC is newer.
   ///   - Regular columns are always updated.
-  /// - If no local row exists, it's an INSERT.
+  ///   - The `system_is_local_origin` flag is preserved (not overwritten).
+  /// - If no local row exists, it's an INSERT marked as server origin.
   ///
-  /// Rows processed by this method are NOT marked as dirty.
+  /// Rows processed by this method are NOT marked as dirty, as they represent
+  /// data coming from the server rather than local changes to be synchronized.
   Future<void> bulkLoad(
       String tableName, List<Map<String, Object?>> rows) async {
     final tableDef = _getTableDefinition(tableName);
@@ -1071,7 +1113,7 @@ class DeclarativeDatabase {
 
         for (final entry in row.entries) {
           final colName = entry.key;
-          if (pkColumns.contains(colName) || colName.endsWith('__hlc')) {
+          if (pkColumns.contains(colName) || colName.endsWith('__hlc') || colName == 'system_is_local_origin') {
             continue;
           }
 
@@ -1111,8 +1153,8 @@ class DeclarativeDatabase {
           );
         }
       } else {
-        // INSERT logic
-        await _insert(tableName, row, hlcClock.now());
+        // INSERT logic - mark as server origin
+        await _insertFromServer(tableName, row, hlcClock.now());
       }
     }
 

declarative_sqlite/lib/src/sync/dirty_row.dart

@@ -5,13 +5,15 @@ class DirtyRow extends Equatable {
   final String tableName;
   final String rowId;
   final Hlc hlc;
+  final bool isFullRow; // true if full row should be sent, false if only LWW columns
 
   @override
-  List<Object?> get props => [tableName, rowId, hlc];
+  List<Object?> get props => [tableName, rowId, hlc, isFullRow];
 
   const DirtyRow({
     required this.tableName,
     required this.rowId,
     required this.hlc,
+    required this.isFullRow,
   });
 }

declarative_sqlite/lib/src/sync/dirty_row_store.dart

@@ -8,7 +8,7 @@ abstract class DirtyRowStore {
   Future<void> init(DatabaseExecutor db);
 
   /// Adds an operation to the store.
-  Future<void> add(String tableName, String rowId, Hlc hlc);
+  Future<void> add(String tableName, String rowId, Hlc hlc, bool isFullRow);
 
   /// Retrieves all pending operations from the store.
   Future<List<DirtyRow>> getAll();

declarative_sqlite/lib/src/sync/sqlite_dirty_row_store.dart

@@ -16,24 +16,25 @@ class SqliteDirtyRowStore implements DirtyRowStore {
   }
 
   @override
-  Future<void> add(String tableName, String rowId, Hlc hlc) async {
+  Future<void> add(String tableName, String rowId, Hlc hlc, bool isFullRow) async {
     await _db.rawInsert('''
-      INSERT OR REPLACE INTO $_tableName (table_name, row_id, hlc)
-      VALUES (?, ?, ?)
-    ''', [tableName, rowId, hlc.toString()]);
+      INSERT OR REPLACE INTO $_tableName (table_name, row_id, hlc, is_full_row)
+      VALUES (?, ?, ?, ?)
+    ''', [tableName, rowId, hlc.toString(), isFullRow ? 1 : 0]);
   }
 
   @override
   Future<List<DirtyRow>> getAll() async {
     final results = await _db.query(
       _tableName,
-      columns: ['table_name', 'row_id', 'hlc'],
+      columns: ['table_name', 'row_id', 'hlc', 'is_full_row'],
     );
     return results.map((row) {
       return DirtyRow(
         tableName: row['table_name'] as String,
         rowId: row['row_id'] as String,
         hlc: Hlc.parse(row['hlc'] as String),
+        isFullRow: (row['is_full_row'] as int) == 1,
       );
     }).toList();
   }
@@ -48,11 +49,12 @@ class SqliteDirtyRowStore implements DirtyRowStore {
     for (final operation in operations) {
       await _db.delete(
         _tableName,
-        where: 'table_name = ? AND row_id = ? AND hlc = ?',
+        where: 'table_name = ? AND row_id = ? AND hlc = ? AND is_full_row = ?',
         whereArgs: [
           operation.tableName,
           operation.rowId,
-          operation.hlc.toString()
+          operation.hlc.toString(),
+          operation.isFullRow ? 1 : 0,
         ],
       );
     }