# UUIDv7

Ogni id record storh è un UUIDv7: un timestamp in millisecondi a 48 bit seguito da entropia casuale, formattato come UUID standard di 36 caratteri. Poiché il timestamp è all'inizio, gli id si ordinano per orario di creazione; questa proprietà alimenta gran parte di storh: la paginazione tramite cursore (`after($id)`), le letture per intervallo temporale, il salto dei segmenti nel log e un ordinamento stabile ovunque.

```php
$id = Storh\UuidV7::generate();

Storh\UuidV7::is_valid($id);          // bool, accepts upper and lower case
Storh\UuidV7::assert_valid($id);      // throws StorageException instead
$timestampMs = Storh\UuidV7::timestamp_ms($id);
```

La generazione è monotona all'interno di un processo: gli id creati nello stesso millisecondo incrementano l'entropia precedente invece di ricalcolarla, così anche le raffiche rapide di scritture mantengono l'ordine di creazione.

## Riferimento temporale

Per gli intervalli temporali, storh ricava il valore minimo e massimo possibile di UUIDv7 per un timestamp in millisecondi e confronta gli id con questi limiti:

```php
$query = Storh\RecordQuery::all()->time_range_ms(
    1_700_000_000_000,
    1_700_000_060_000,
);

$lower = Storh\UuidV7::min_for_timestamp_ms(1_700_000_000_000);
$upper = Storh\UuidV7::max_for_timestamp_ms(1_700_000_060_000);
```

Ecco perché le letture per intervallo temporale non richiedono un campo timestamp nei dati del record: l'id contiene l'ora di creazione.

## Fornire id personalizzati

Tutti i motori accettano un id esplicito per ogni scrittura (`$docs->put($data, $id)`) e una funzione `id_generator` nei rispettivi costruttori. Gli id generati da entrambi i metodi vengono convalidati come UUIDv7, quindi i generatori personalizzati devono produrli; i generatori deterministici permettono alla suite di test di creare fixture riproducibili. `UuidV7::reset_for_tests()` azzera lo stato di monotonicità a livello di processo tra un caso di test e l'altro.