Message(
  id: 'msg-abc-123',           // Unique ID
  table: 'todos',              // Table name
  row: 'todo-456',             // Row ID (primary key)
  column: 'name',              // Column name
  value: 'Buy milk',           // New value (serialized)
  dataType: 'string',          // Type hint for deserialization
  localTimestamp: '00001704...',  // HLC timestamp
  serverTimestamp: 12345,      // Server-assigned order
  userId: 'user-789',          // Who made the change
  clientId: 'device-abc',      // Which device
  hasBeenSynced: false,        // Sync status
  hasBeenApplied: true,        // Applied to data table?
)

await talon.saveChange(
  table: 'todos',
  row: 'todo-1',
  column: 'name',
  value: 'Buy milk',
);

// Talon internally creates:
Message(
  id: uuid.v4(),
  table: 'todos',
  row: 'todo-1',
  column: 'name',
  value: 'Buy milk',
  dataType: 'string',
  localTimestamp: hlcState.send().toString(),
  serverTimestamp: null,
  userId: talon.userId,
  clientId: talon.clientId,
  hasBeenApplied: false,
  hasBeenSynced: false,
)

final message = Message(..., dataType: 'int', value: '42');

final count = message.typedValue as int;  // 42

await talon.saveChange(...);

// Message created with:
// - hasBeenSynced: false (needs sync)
// - hasBeenApplied: true (applied to data)

// During sync:
await serverDb.sendMessageToServer(message: message);

// On success:
// - hasBeenSynced: true

// When receiving from server:

// If newer than existing:
// - hasBeenApplied: true
// - Applied to data table

// If older than existing:
// - hasBeenApplied: false
// - Stored but not applied

// For database storage
final map = message.toMap();
await db.insert('talon_messages', map);

// From database
final rows = await db.query('talon_messages');
final messages = rows.map((r) => Message.fromMap(r)).toList();

// For network transmission
final json = message.toJson();

// From JSON
final message = Message.fromJson(jsonString);

final comparison = HLC.compareTimestamps(
  message1.localTimestamp,
  message2.localTimestamp,
);

if (comparison > 0) {
  // message1 is newer
} else if (comparison < 0) {
  // message2 is newer
}

// Good: UUIDs
createNewIdFunction: () => uuid.v4(),

// Also good: Prefixed UUIDs
createNewIdFunction: () => 'msg-${uuid.v4()}',

// Instead of storing large JSON in one message:
await talon.saveChange(
  table: 'documents',
  row: 'doc-1',
  column: 'content',
  value: largeJsonObject,  // Could be very large
);

// Consider normalizing:
for (final section in document.sections) {
  await talon.saveChange(
    table: 'sections',
    row: section.id,
    column: 'content',
    value: section.content,
  );
}

// Related changes should be batched:
await talon.saveChanges([
  TalonChangeData(table: 'todos', row: id, column: 'name', value: name),
  TalonChangeData(table: 'todos', row: id, column: 'updated_at', value: DateTime.now()),
]);