Summary

  • RFC 9562 gives UUIDv7 a 48-bit Unix-epoch millisecond field followed by version, variant, and 74 usable bits of random or optional monotonicity material. It makes identifiers efficient to sort; it does not make them an authoritative event timeline.
  • The RFC permits altered timestamps, supplies no guarantee that the value is close to actual time, and leaves clock rollback, counters, and batch ordering to the implementation. True global uniqueness also needs shared knowledge that UUIDs do not require.
  • An audit claim needs separate evidence for generator and clock policy, durable state transition, actor and authorization, any external time assertion, and observed result. A UUID can link those records; it cannot replace them.

A key can be ordered without becoming a clock

RFC 9562 is careful about the problem UUIDv7 solves. In bits 0 through 47 it stores a big-endian count of Unix-epoch milliseconds. The following space holds the version and variant markers plus rand_a and rand_b: 74 usable bits that are random by default. An implementation may instead devote part of that space to an optional fraction of a millisecond, a carefully seeded counter, and then remaining random data. The construction lets applications that sort UUID bytes place recent values near each other in a B-tree or similar index without parsing each key.

That is already a substantial benefit. Random UUIDv4 insertions tend to scatter across an index. A UUIDv7-shaped stream can cluster new rows and make a range scan cheaper. RFC 9562 expressly describes bytewise and lexical sorting as a design purpose. But a value that helps a database choose page placement is not thereby a statement from a trusted clock or an append-only record of work.

The distinction is easiest to see in the word created. A generator can allocate an ID before validation. A transaction can roll back after allocation. A message can be committed later by an outbox. A consumer can process that message more than once. A service can report success before a downstream dependency makes the corresponding state visible. Every one of those acts can retain the original UUID as a correlation handle. None is encoded in its first 48 bits.

The millisecond field has an explicit accuracy boundary

RFC 9562 does not conceal this. Its timestamp guidance says implementations obtain a timestamp from a reliable source when they need continuously increasing, time-ordered values. It then warns that a system clock may move backwards through manual adjustment or time-synchronization correction and says the implementation must decide how to handle that environment.

More importantly, the specification says an implementation may alter the actual timestamp. It gives correcting inaccurate clocks, leap-second treatment, and performance-oriented transformations as examples, and makes no requirement or guarantee about how close the stored clock value must be to actual time. That is not a defect in UUIDv7. It is the right boundary for a portable identifier format. A common 128-bit layout cannot determine a host's time source, synchronization health, policy for clock smear, or risk tolerance for a backward adjustment.

The same discipline applies inside a single millisecond. UUIDv7 normally has a millisecond field. An implementation that wants predictable ordering for many values in that interval may choose a sub-millisecond fraction or a counter. RFC 9562 calls these additional monotonicity techniques; it does not smuggle them into every generator. Counter rollover must be handled by the application. The RFC recommends error checking when a newly generated time-based UUID is not greater than the prior one, because clock rollback, leap handling, and counter rollover can all break the desired pattern.

So a lexical comparison supports a narrow statement: under the chosen generator's policy, these two representations sort this way. It does not support the larger statement that one external event necessarily preceded another. The difference becomes material when teams investigate a financial reversal, an access change, a production deployment, or a regulatory deadline. A visually satisfying order is not enough evidence to close a dispute.

Independent writers do not acquire a shared history by using the same format

The distributed boundary is equally direct. RFC 9562 says true global uniqueness is impossible to guarantee without a shared-knowledge scheme. It permits local uniqueness to be sufficient for many applications and does not require a global registry. This is the trade: UUIDs are cheap and portable precisely because every generator does not have to wait for a central sequencer.

That trade should be preserved rather than denied. Two hosts can produce useful identifiers without a coordination round trip. But they may use different time sources, different counter choices, different restart behavior, and different persistence of generator state. Their sorted keys are not proof that they saw the same world in the same sequence. Even a collision-resistant identifier is not a quorum record, a consensus log position, or a cross-host causality proof.

RFC 9562 also recommends treating UUIDs as opaque when parsing is unnecessary. That advice protects interoperability: a consumer normally needs a stable identifier, not an invented story about its interior bits. The danger begins when an audit interface promotes an optional timestamp field from a useful hint into a decisive fact while discarding the records that could test it.

What a defensible event record actually needs

A UUIDv7 belongs in an audit design, but as a link among evidence rather than as the evidence itself.

  1. Generator evidence identifies the generator version, host or service context, time source, precision policy, counter behavior, restart state, and exception handling.
  2. State-transition evidence records the transaction boundary, durable commit or failure, message publication, retry, reconciliation, and any idempotency decision.
  3. Authority evidence records the actor, delegated service principal, approval or policy that allowed the consequential operation, and the scope of that permission.
  4. Time evidence is separate when an external time claim matters. RFC 3161 describes a different process: a Time-Stamp Authority signs a token for a data imprint under an identified policy, and the requester verifies the imprint, signature, certificate, nonce or timeliness, and policy suitability. That is bounded evidence that a datum existed before a stated time under that policy—not proof of who authored it, who was entitled to act, or what later occurred.
  5. Effect evidence comes from the receiver or system whose state matters: settlement, applied configuration, access decision, customer-visible result, or compensating rollback.

These records need not be a central bureaucracy. They are the minimal fields required to keep one narrow artifact from becoming a fictional institution. Heng Lu's running-code principle is relevant as editorial discipline: the system that actually generated, committed, received, and applied the change is allowed to correct the story implied by a sortable key. A portable format should remain portable; the locally accountable decision should remain visible.

Sources