docs: update README and docs for patch operation and 140-test audit

- README: add patch to features table, quick start section, API
  reference, security badge (140 tests), installation version
- architecture.md: add patch section with code example and
  Supabase implementation details
- security_audit.md: add Category 13 (patch operation, tests
  131-140), update totals to 140 tests / 13 categories
- example.dart: add Pattern C for partial update via patch

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: HassamSheikh

README.md

@@ -10,7 +10,7 @@ Built by the team at [**dynos.fit**](https://dynos.fit) to power high-concurrenc
 [![Pub.dev](https://img.shields.io/pub/v/dynos_sync)](https://pub.dev/packages/dynos_sync)
 [![Pub Points](https://img.shields.io/pub/points/dynos_sync)](https://pub.dev/packages/dynos_sync/score)
 [![MIT License](https://img.shields.io/badge/license-MIT-green.svg)](https://opensource.org/licenses/MIT)
-[![Security Audit: 130 Tests](https://img.shields.io/badge/Security_Audit-130/130_PASS-2DD4A8)](doc/security_audit.md)
+[![Security Audit: 140 Tests](https://img.shields.io/badge/Security_Audit-140/140_PASS-2DD4A8)](doc/security_audit.md)
 [![Performance: 50k+ writes/sec](https://img.shields.io/badge/Performance-50k+_writes/sec-blueviolet)](#performance)
 
 ---
@@ -41,6 +41,7 @@ Flutter App  -->  SyncEngine  -->  Local DB (Drift/SQLite)
 | **Row-Level Security** | Local RLS gate blocks writes with mismatched `user_id` |
 | **Exponential backoff** | Failed pushes retry with 2^n delays, capped at `maxBackoff` |
 | **Poison pill isolation** | Permanently failing entries are dropped after `maxRetries` |
+| **Partial updates (patch)** | `SyncOperation.patch` sends UPDATE instead of upsert — no NOT NULL failures |
 | **Batch push** | `drain()` pushes up to `batchSize` entries per cycle |
 | **Auth expiry handling** | `AuthExpiredException` emits `SyncAuthRequired` event, stops drain |
 | **Cross-user isolation** | `logout()` wipes queue, local data, and timestamps |
@@ -55,7 +56,7 @@ Flutter App  -->  SyncEngine  -->  Local DB (Drift/SQLite)
 
 ```yaml
 dependencies:
-  dynos_sync: ^0.1.2
+  dynos_sync: ^0.1.5
 ```
 
 ---
@@ -105,7 +106,17 @@ await sync.addTable('tags', pull: false);       // register only
 sync.removeTable('deprecated_table');           // stop syncing
 ```
 
-### 5. Logout
+### 5. Partial update (patch)
+
+```dart
+// Update only specific fields — no NOT NULL failures from missing columns
+await sync.push('workouts', id, {
+  'used_at': DateTime.now().toUtc().toIso8601String(),
+  'exercises_kept': 5,
+}, operation: SyncOperation.patch);
+```
+
+### 6. Logout
 
 ```dart
 await sync.logout();  // wipes queue, local data, timestamps
@@ -121,7 +132,7 @@ await sync.logout();  // wipes queue, local data, timestamps
 |---|---|
 | `write(table, id, data)` | Write locally + queue for sync |
 | `remove(table, id)` | Delete locally + queue deletion |
-| `push(table, id, data, {operation})` | Queue sync without local write (for custom DAOs) |
+| `push(table, id, data, {operation})` | Queue sync without local write. `operation`: `upsert` (default), `patch`, or `delete` |
 | `drain()` | Push all pending queue entries to remote |
 | `pullAll()` | Delta-pull changes from remote for all registered tables |
 | `syncAll()` | Full cycle: `drain()` then `pullAll()` |
@@ -217,7 +228,7 @@ Benchmarked with in-memory stores on standard hardware:
 
 ## Security
 
-The engine passes a **130-test security audit** across 12 categories:
+The engine passes a **140-test security audit** across 13 categories:
 
 - HIPAA & health data compliance (PHI masking, audit trail, session timeout)
 - Cross-user data isolation (full wipe on logout)
@@ -227,6 +238,7 @@ The engine passes a **130-test security audit** across 12 categories:
 - Flood resilience (100k parallel writes, drain lock)
 - OWASP Mobile Top 10 coverage
 - GDPR compliance (right to erasure, data minimization)
+- Patch operation safety (partial payloads, RLS, poison pill, auth expiry)
 
 See [Security Audit Report](doc/security_audit.md) for details.
 
@@ -235,7 +247,7 @@ See [Security Audit Report](doc/security_audit.md) for details.
 ## Documentation
 
 - [Architecture](doc/architecture.md) -- sync protocol, write path, pull path, security gates
-- [Security Audit](doc/security_audit.md) -- 130-test audit across 12 categories
+- [Security Audit](doc/security_audit.md) -- 140-test audit across 13 categories
 - [API example](example/example.dart) -- complete Drift + Supabase setup
 - [Security Policy](SECURITY.md) -- vulnerability reporting
 

doc/architecture.md

@@ -50,6 +50,19 @@ Key design decisions:
 
 `push(table, id, data)` queues a sync entry without writing locally. Use this when your own DAO handles the local write and you just need the remote sync.
 
+### Patch (partial update)
+
+`push(table, id, data, operation: SyncOperation.patch)` queues a partial update. On the remote, this sends an `UPDATE ... WHERE id = ?` instead of an upsert. This avoids NOT NULL constraint failures when you only need to update a few fields on an existing row:
+
+```dart
+await sync.push('workouts', id, {
+  'used_at': DateTime.now().toUtc().toIso8601String(),
+  'exercises_kept': 5,
+}, operation: SyncOperation.patch);
+```
+
+The `SupabaseRemoteStore` implements patch via `.update(data).eq('id', id)`. In batch mode, patches are sent individually since Supabase has no batch update API.
+
 ### remove()
 
 `remove(table, id)` queues a `SyncOperation.delete` entry and deletes from the local store.

doc/security_audit.md

@@ -1,6 +1,6 @@
 # Security Audit Report
 
-`dynos_sync` is subjected to a **130-test security audit** across 12 categories before every release. This document describes what is tested and why.
+`dynos_sync` is subjected to a **140-test security audit** across 13 categories before every release. This document describes what is tested and why.
 
 Test file: [`test/dynos_sync_total_audit_test.dart`](../test/dynos_sync_total_audit_test.dart)
 
@@ -22,8 +22,9 @@ Test file: [`test/dynos_sync_total_audit_test.dart`](../test/dynos_sync_total_au
 | 10. Denial of Service & Abuse | 108--114 | 1 CRITICAL, 3 HIGH, 2 MEDIUM, 1 LOW |
 | 11. OWASP Mobile Top 10 | 115--124 | Maps to OWASP M1--M10 |
 | 12. GDPR & Data Sovereignty | 125--130 | 2 CRITICAL, 2 HIGH, 1 MEDIUM, 1 LOW |
+| 13. Patch Operation | 131--140 | 4 CRITICAL, 3 HIGH, 2 MEDIUM, 1 LOW |
 
-**Total: 130 tests, 0 failures required for release.**
+**Total: 140 tests, 0 failures required for release.**
 
 ---
 
@@ -167,14 +168,29 @@ Explicit mapping to OWASP Mobile Top 10 (2024):
 - **Data residency** -- `RemoteStore` endpoint is configurable per region
 - **Transfer logging** -- event stream provides audit trail for all sync operations
 
+### 13. Patch Operation (Tests 131--140)
+
+Tests that the new `SyncOperation.patch` (partial update) is safe across all vectors:
+
+- **Partial payload integrity** -- engine sends exactly the provided fields, no extras injected
+- **Queue persistence** -- `SyncEntry` preserves the `patch` operation type through the queue
+- **Drain forwarding** -- drain correctly forwards patch operations to `RemoteStore`
+- **Mixed batch** -- upsert + patch + delete all processed correctly in a single drain cycle
+- **Payload size limits** -- `maxPayloadBytes` enforced on patch payloads
+- **RLS enforcement** -- mismatched `user_id` throws `[RLS_Bypass]` on patch, same as upsert
+- **PII masking** -- `sensitiveFields` masks values in patch payloads via `write()`
+- **Poison pill** -- patch entries dropped after `maxRetries` with `SyncPoisonPill` event
+- **Auth expiry** -- `AuthExpiredException` during patch drain stops and preserves entry
+- **SQL injection** -- injection strings in patch payloads stored as literals, not executed
+
 ---
 
 ## Pass criteria
 
 Every release must:
 
-1. Pass all 130 tests in `test/dynos_sync_total_audit_test.dart`
-2. Pass all existing tests (66 tests across 7 other test files)
+1. Pass all 140 tests in `test/dynos_sync_total_audit_test.dart`
+2. Pass all existing tests across other test files
 3. Zero `dart analyze` errors or warnings
 4. Verified compatibility with Drift and Supabase adapters
 

example/example.dart

@@ -70,7 +70,21 @@ Future<void> createTaskViaDao(
   await sync.push('tasks', task['id'] as String, task);
 }
 
-/// Pattern C: Delete a record
+/// Pattern C: Partial update (patch) — only sends changed fields
+Future<void> markTaskDone(SyncEngine sync, String id) async {
+  // Updates only these columns via UPDATE, not upsert.
+  // Avoids NOT NULL failures from missing columns.
+  await sync.push(
+      'tasks',
+      id,
+      {
+        'done': true,
+        'finished_at': DateTime.now().toUtc().toIso8601String(),
+      },
+      operation: SyncOperation.patch);
+}
+
+/// Pattern D: Delete a record
 Future<void> deleteTask(SyncEngine sync, String id) async {
   await sync.remove('tasks', id);
   // Deleted locally + queued for remote deletion.