CodeSampleX

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

  1. assert sequential NewV7 calls produce strictly monotonically increasing UUIDs in byte order
  2. assert sequential NewV7 calls produce strictly monotonically increasing UUIDs in string representation
  3. assert NewV7 sets Version to 7 and Variant to RFC4122

Files

  • NOTES.md
  • csx.json
  • go.mod
  • go.sum
  • uuid_v7_test.go

Download the source artifact (tar.gz)

Source

NOTES.md
# 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.
csx.json
{"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"}
go.mod
module sample

go 1.26.5

require github.com/google/uuid v1.6.0
go.sum
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=
uuid_v7_test.go
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
	}
}

Origin Seeder

anonymous