# UUIDv7

Każdy identyfikator rekordu storh jest wartością UUIDv7: zawiera 48-bitowy znacznik czasu w milisekundach, po którym następują losowe dane, a jego format to standardowe UUID o długości 36 znaków. Ponieważ znacznik czasu znajduje się na początku, identyfikatory są sortowane według czasu utworzenia — ta właściwość umożliwia większość funkcji storh: stronicowanie kursorem (`after($id)`), odczyty zakresów czasu, pomijanie segmentów dziennika i stabilne sortowanie w całym systemie.

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

Generowanie w obrębie procesu jest monotoniczne: identyfikatory utworzone w tej samej milisekundzie zwiększają poprzednie losowe dane zamiast losować je ponownie, dzięki czemu nawet szybkie serie zapisów zachowują kolejność utworzenia.

## Dostęp według czasu

Dla zakresów czasu storh wyznacza najmniejsze i największe możliwe wartości UUIDv7 dla znacznika czasu w milisekundach i porównuje identyfikatory z tymi granicami:

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

Dlatego odczyty zakresów czasu nie wymagają pola znacznika czasu w danych rekordu: identyfikator zawiera czas utworzenia.

## Własne identyfikatory

Wszystkie silniki akceptują jawny identyfikator przy każdym zapisie (`$docs->put($data, $id)`) oraz funkcję `id_generator` przekazywaną do konstruktorów. Identyfikatory z obu źródeł są weryfikowane jako UUIDv7, więc własne generatory muszą je tworzyć; testy używają generatorów deterministycznych, aby tworzyć powtarzalne zestawy danych. `UuidV7::reset_for_tests()` czyści monotoniczny stan procesu między przypadkami testowymi.