# UUIDv7

Todo id de registro storh é um UUIDv7: um timestamp em milissegundos de 48 bits seguido de entropia aleatória, formatado como um UUID padrão de 36 caracteres. Como o timestamp vem primeiro, os ids são ordenados pela hora de criação, e essa propriedade permite a maioria dos recursos de storh: paginação por cursor (`after($id)`), leituras por intervalo de tempo, saltos de segmentos no log e ordenação estável em todos os lugares.

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

A geração é monotônica dentro de um processo: ids criados no mesmo milissegundo incrementam a entropia anterior em vez de gerá-la novamente, então até gravações em sequência rápida mantêm a ordem de criação.

## Localização por horário

Para intervalos de tempo, storh deriva o menor e o maior UUIDv7 possíveis para um timestamp em milissegundos e compara os ids com esses limites:

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

Por isso, leituras por intervalo de tempo não precisam de um campo de timestamp nos dados do registro: o id contém a hora de criação.

## Fornecimento dos próprios ids

Todos os mecanismos aceitam um id explícito por gravação (`$docs->put($data, $id)`) e um callable `id_generator` em seus construtores. Os ids de qualquer um dos caminhos são validados como UUIDv7, portanto os geradores personalizados precisam produzi-los; geradores determinísticos são usados pelo conjunto de testes para criar fixtures reproduzíveis. `UuidV7::reset_for_tests()` limpa o estado monotônico do processo entre casos de teste.