# UUIDv7

Chaque identifiant d’enregistrement storh est un UUIDv7 : un horodatage en millisecondes sur 48 bits suivi d’entropie aléatoire, au format standard UUID de 36 caractères. Comme l’horodatage vient en premier, les identifiants se trient par heure de création ; cette seule propriété permet la plupart des usages de storh : pagination par curseur (`after($id)`), lectures par plage horaire, saut de segments dans le journal et ordre stable partout.

```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 génération est monotone au sein d’un processus : les identifiants créés dans la même milliseconde incrémentent l’entropie précédente au lieu d’en générer une nouvelle ; même les rafales d’écritures rapides restent donc triées dans leur ordre de création.

## Accès par date

Pour définir des fenêtres temporelles, storh dérive les valeurs minimale et maximale possibles de UUIDv7 pour un horodatage en millisecondes, puis compare les identifiants à ces bornes :

```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);
```

C’est pourquoi les lectures par plage horaire n’ont pas besoin de champ d’horodatage dans les données de l’enregistrement : l’identifiant contient l’heure de création.

## Fournir vos propres identifiants

Tous les moteurs acceptent un identifiant explicite pour chaque écriture (`$docs->put($data, $id)`) ainsi qu’un appelable `id_generator` dans leurs constructeurs. Les identifiants générés par l’une ou l’autre méthode sont validés en tant que UUIDv7 ; vos générateurs personnalisés doivent donc en produire. Les générateurs déterministes permettent à la suite de tests de créer des données de test reproductibles. `UuidV7::reset_for_tests()` efface l’état de monotonie au niveau du processus entre les cas de test.