docs: add entries schema documentation with UUID handling

Document entries collection fields, sysTime+type dedup behavior,
and identifier normalization for Trio/xDrip+ UUID _id uploads.

Refs: DOC-API-002, REQ-SYNC-072, GAP-SYNC-045

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

docs/data-schemas/entries-schema.md

@@ -0,0 +1,138 @@
+# Entries Schema Documentation
+
+**Document Version:** 1.0  
+**Last Updated:** March 2026  
+**Status:** Active (2025 Standard)  
+**Source:** Code analysis (`lib/server/entries.js`)
+
+---
+
+## Overview
+
+The `entries` collection stores CGM (Continuous Glucose Monitor) sensor readings and related data. This includes SGV (sensor glucose values), MBG (meter blood glucose), and calibration data.
+
+**Collection Name:** `entries`  
+**Primary Key:** `sysTime` + `type` (composite)  
+**Primary Timestamp Field:** `sysTime` (ISO 8601, derived from `dateString` or `date`)
+
+---
+
+## Core Fields
+
+| Field | Type | Required | Constraints | Description |
+|-------|------|----------|-------------|-------------|
+| `_id` | ObjectId | Yes (auto) | MongoDB ObjectId | Primary key, auto-generated by server |
+| `type` | String | Yes | `sgv`, `mbg`, `cal`, etc. | Type of entry |
+| `date` | Number | Yes | Epoch milliseconds | When the reading was taken |
+| `dateString` | String | Yes | ISO 8601 | Same as `date` in string format |
+| `sysTime` | String | Computed | ISO 8601 | Normalized timestamp (computed from `dateString` or `date`) |
+| `utcOffset` | Number | Computed | Minutes | UTC offset parsed from `dateString` |
+
+---
+
+## SGV Fields (type: "sgv")
+
+| Field | Type | Constraints | Description |
+|-------|------|-------------|-------------|
+| `sgv` | Number | mg/dL or mmol/L | Sensor glucose value |
+| `direction` | String | Trend arrows | Glucose trend direction |
+| `noise` | Number | 0-4 | Signal noise level |
+| `filtered` | Number | Raw value | Filtered sensor signal |
+| `unfiltered` | Number | Raw value | Unfiltered sensor signal |
+| `rssi` | Number | dBm | Signal strength (Dexcom) |
+
+---
+
+## Sync Identity Fields
+
+| Field | Type | Source | Description |
+|-------|------|--------|-------------|
+| `identifier` | String | Server-normalized | **Unified client sync identity** (see below) |
+| `device` | String | CGM app | Device/app identifier (e.g., `"xDrip-DexcomG6"`) |
+
+### Identifier Field Normalization (REQ-SYNC-072)
+
+As of v15.0.7, the server **automatically normalizes** client sync identities into the `identifier` field:
+
+| Client | Sends | Server Action |
+|--------|-------|---------------|
+| **Trio** | UUID in `_id` | Extract to `identifier`, assign server ObjectId |
+| **xDrip+** | `uuid` or `identifier` | Copy to `identifier` if present |
+| **Loop** | ObjectId (from cache) | Normal ObjectId behavior |
+
+**Important**: For entries, `sysTime + type` is ALWAYS the primary deduplication key. The `identifier` field is for client sync tracking only - it does NOT override the dedup logic.
+
+---
+
+## Deduplication Behavior
+
+Entries use **sysTime + type** as the composite unique key:
+
+```javascript
+// Upsert query for entries (lib/server/entries.js)
+{ sysTime: doc.sysTime, type: doc.type }
+```
+
+This means:
+- Two SGV readings at the same `sysTime` will be deduplicated (one overwrites the other)
+- Different entry types (SGV vs MBG) at the same time are allowed
+- Re-uploading the same reading updates the existing document
+
+### UUID _id Handling
+
+When a client sends a UUID as `_id`:
+
+1. **Extract**: UUID is copied to `identifier` field
+2. **Strip**: Non-ObjectId `_id` is removed before database operation
+3. **Upsert**: Server uses `sysTime + type` for matching
+4. **Assign**: Server-generated ObjectId becomes final `_id`
+
+This prevents the MongoDB "immutable field '_id'" error while preserving client sync identity.
+
+---
+
+## UUID_HANDLING Feature Flag
+
+When `UUID_HANDLING=true` environment variable is set:
+
+| Operation | Behavior |
+|-----------|----------|
+| GET by UUID | Searches by `identifier` field |
+| DELETE by UUID | Deletes by `identifier` field |
+
+When `UUID_HANDLING=false` (default):
+
+| Operation | Behavior |
+|-----------|----------|
+| GET by UUID | Returns empty (no crash) |
+| DELETE by UUID | Deletes nothing (no crash) |
+
+See [uuid-identifier-lookup specification](../../docs/backlogs/uuid-identifier-lookup.md) for details.
+
+---
+
+## Example Entry Document
+
+```json
+{
+  "_id": {"$oid": "507f1f77bcf86cd799439011"},
+  "type": "sgv",
+  "sgv": 120,
+  "direction": "Flat",
+  "date": 1704067200000,
+  "dateString": "2024-01-01T00:00:00.000Z",
+  "sysTime": "2024-01-01T00:00:00.000Z",
+  "utcOffset": 0,
+  "identifier": "550e8400-e29b-41d4-a716-446655440000",
+  "device": "xDrip-DexcomG6",
+  "noise": 1
+}
+```
+
+---
+
+## Related Documents
+
+- [Treatments Schema](treatments-schema.md) - Similar identifier normalization
+- [GAP-SYNC-045](../../../traceability/sync-identity-gaps.md#gap-sync-045) - Trio entries UUID issue
+- [REQ-SYNC-072](../../../traceability/sync-identity-requirements.md#req-sync-072) - Identifier normalization requirement