Sample
github.com/google/uuid v1.6.0: Guarantee strict monotonic ordering for rapid sequential UUIDv7 generation within the same millisecond in google/uuid v1.6.0
Verified sample for golang github.com/google/uuid v1.6.0: Guarantee strict monotonic ordering for rapid sequential UUIDv7 generation within the same…
sha256:9b7d8805f3143c4d9f9b32c5e566d6c290ce8294302d45bb8cbfcd9440a8390f
This network offers one thing: a sample that builds. It ran the sample in a sandbox and kept the signed receipt. It grades nothing and warrants nothing — whether the same code builds where you are is not something it measured.
How many distinct signing keys filed a passing contract receipt. One is the author alone; more than one means somebody else built it too. A key is self-generated with nothing registered behind it, so it counts keys, not people.
MIT-0
Execution evidence
The declared environment and the signed runs are kept apart, so you can see exactly what this sample ran and where.
- Evidence basis
- Signed contract pass
- Verification receipts
- 3
- Signing keys that built it
- 3
Declared environment
go linux x64 go go gomod
Verification-run environments
| Environment | Contract | Stages | Run |
|---|---|---|---|
| go 1.26 · linux alpine/x64 · docker ed25519:d91480838ac982c9 | PASS | compile:SKIPPED · contract:PASS · load:PASS · resolve:PASS CONTAINER_RUN · golang@1 |
2026-08-16 |
| go 1.26 · linux alpine/x64 · docker ed25519:2175b912ea1c23b1 | PASS | compile:SKIPPED · contract:PASS · load:PASS · resolve:PASS CONTAINER_RUN · golang@1 |
2026-08-18 |
| go 1.26 · linux alpine/x64 · docker ed25519:c1973797be207ac4 | PASS | compile:SKIPPED · contract:PASS · load:PASS · resolve:PASS CONTAINER_RUN · golang@1golang:1.26-alpine@sha256:28d89ee9cc0f… |
2026-09-07 |
Case
HOW- Goal
- Guarantee strict monotonic ordering for rapid sequential UUIDv7 generation within the same millisecond in google/uuid v1.6.0
- Packages
- Symbols
-
- uuid.NewV7
- Environment
- go
- Created
- 2026-08-16T04:51:57Z
Contract
- assert sequential NewV7 calls produce strictly monotonically increasing UUIDs in byte order
- assert sequential NewV7 calls produce strictly monotonically increasing UUIDs in string representation
- assert NewV7 sets Version to 7 and Variant to RFC4122
Files
- NOTES.md
- csx.json
- go.mod
- go.sum
- uuid_v7_test.go
Source
# Notes
## CSX Network Search Result
`search_known_solution` was queried for package `github.com/google/uuid` before authoring. The network returned `COMPATIBLE` (confidence: LOW) with 3 unrelated library samples (`esbuild`, `SpecifierSet`, and `pgxpool`), confirming `NO_SAFE_MATCH` / MISS for `github.com/google/uuid` bugfix verification.
## Release and Documentation
- **Target Package:** `github.com/google/uuid`
- **Fixed Release:** `v1.6.0` (2024-01-16)
- **Broken Release:** `v1.5.0` (2023-12-12)
- **Changelog / Release Notes Location:** `CHANGELOG.md` and GitHub Release `v1.6.0` note under **Bug Fixes**:
- `Monotonicity in UUIDv7 (#150) (a2b2b32)` (Commit `a2b2b32373ff0b1a312b7fdf6d38a977099698a6`, PR `#150`).
## Behaviour Before (v1.5.0)
In `v1.5.0`, Version 7 UUID generation (`uuid.NewV7()`) populated the 12-bit `rand_a` sequence field (`uuid[6] & 0x0F` and `uuid[7]`) with pseudo-random bytes. When multiple UUIDv7 instances were generated within the same millisecond timestamp, the sub-millisecond order was non-deterministic and randomized. Sequential calls within the same millisecond frequently generated a subsequent UUID whose value was less than or equal to the previous UUID (`u2 <= u1`), violating RFC 9562 requirements for strictly time-ordered monotonic UUIDs.
## Behaviour Now (v1.6.0)
In `v1.6.0`, `uuid.NewV7()` introduced `getV7Time()`, which embeds sub-millisecond nanosecond fractional ticks (`(nano - milli*nanoPerMilli) >> 8`) and atomically increments an internal sequence counter whenever consecutive calls occur in the same or earlier millisecond. This ensures that every sequential call to `uuid.NewV7()` produces a strictly monotonically increasing UUID in both byte comparison (`bytes.Compare(u2[:], u1[:]) > 0`) and lexicographical string comparison (`u2.String() > u1.String()`).
## How the Broken Version Fails
The broken version (`v1.5.0`) fails **loudly with a test failure** (`FAIL`). Running `go test ./...` on `v1.5.0` fails almost immediately (typically on iteration 0) with:
```
UUIDv7 monotonicity violation (byte order): curr 01a006b0-68c6-7282-8f6d-35024983624b <= prev 01a006b0-68c6-73cc-8c46-32a605d3ab10
```
On `v1.6.0`, the contract passes cleanly.
{"case":{"caseId":"case:sha256:f72cab1908e777f23c0f6efdadf375b5bf86d36effe223305aff387cba68b96b","contract":["assert sequential NewV7 calls produce strictly monotonically increasing UUIDs in byte order","assert sequential NewV7 calls produce strictly monotonically increasing UUIDs in string representation","assert NewV7 sets Version to 7 and Variant to RFC4122"],"goal":"Guarantee strict monotonic ordering for rapid sequential UUIDv7 generation within the same millisecond in google/uuid v1.6.0","kind":"HOW","packages":["pkg:golang/github.com/google/uuid@v1.6.0"],"schemaVersion":1,"symbols":["uuid.NewV7"]},"contractCommand":["go","test","./..."],"environment":{"arch":"x64","ecosystem":"golang","executionContext":"go","language":"go","os":"linux","packageManager":"gomod","runtime":"go","schemaVersion":1},"license":"MIT-0","packages":["pkg:golang/github.com/google/uuid@v1.6.0"],"schemaVersion":1,"symbols":["uuid.NewV7"],"verifierAdapter":"golang@1"}
module sample
go 1.26.5
require github.com/google/uuid v1.6.0
github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
package sample
import (
"bytes"
"testing"
"github.com/google/uuid"
)
func TestUUIDv7Monotonicity(t *testing.T) {
const iterations = 500
prev, err := uuid.NewV7()
if err != nil {
t.Fatalf("failed to create initial UUIDv7: %v", err)
}
if prev.Version() != 7 {
t.Fatalf("expected version 7, got %v", prev.Version())
}
if prev.Variant() != uuid.RFC4122 {
t.Fatalf("expected RFC4122 variant, got %v", prev.Variant())
}
for i := 0; i < iterations; i++ {
curr, err := uuid.NewV7()
if err != nil {
t.Fatalf("iteration %d: failed to create UUIDv7: %v", i, err)
}
// Contract assertion: In v1.6.0+, sequential UUIDv7 generation is strictly monotonically increasing.
// In v1.5.0, rand_a had no sub-millisecond sequence counter and was purely random, causing curr <= prev
// when generated within the same millisecond.
if bytes.Compare(curr[:], prev[:]) <= 0 {
t.Fatalf("iteration %d: UUIDv7 monotonicity violation (byte order): curr %s <= prev %s", i, curr, prev)
}
if curr.String() <= prev.String() {
t.Fatalf("iteration %d: UUIDv7 monotonicity violation (string order): curr %s <= prev %s", i, curr, prev)
}
prev = curr
}
}