Skip to content

UUID-V7-ESTATE-STANDARD.adoc

Latest commit

 

History

History
170 lines (141 loc) · 8.6 KB

UUID-V7-ESTATE-STANDARD.adoc

File metadata and controls

170 lines (141 loc) · 8.6 KB
Raw

Estate UUID Standard: UUID Version 7

Table of Contents
Warning

Superseded. Owner ruling D305/D305b (2026-10-06) adopted ADR-008: every estate identifier is UUID version 8 (profile T or C). Mint version 8 for new identifiers. Version 7 literals are still accepted until phase P4, and the migration-record states and register shape below stay in force for the campaign. The CI gate is now scripts/check-uuid-v8.sh.

Status: Superseded by ADR-008 (ESTATE-UUID-V8), 2026-10-06; enforced in dual-accept until P4 Applies to: the complete live hyperpolymath and metadatastician estates Authority: hyperpolymath/standards

Decision

All UUIDs created, persisted, exchanged, or exposed by an estate repository MUST be UUID version 7 as specified by RFC 9562. UUID v4, v1, v3, v5, v6, non-standard UUIDs, and random UUID-shaped strings MUST NOT be introduced for new data or new interfaces.

This is a format decision, not a request to put the organisation name into the UUID. A UUID v7 is a 128-bit identifier with a Unix epoch-millisecond timestamp in its most-significant 48 bits, version nibble 7, and the RFC 9562 variant bits 10. The remaining bits MUST be generated with an approved CSPRNG (or an implementation with equivalent security and monotonicity guarantees). The usual canonical text form is lowercase hexadecimal, 8-4-4-4-12, with no braces or prefixes.

This standard does not replace a repository’s human-readable slug, GitHub owner/name, database key type, or an externally assigned identifier. It requires UUID-valued identifiers to use v7; those other namespaces remain in their own canonical formats.

Scope

This standard covers, in both estates:

  • primary keys and foreign keys stored as UUIDs;

  • event, job, trace, correlation, request, aggregate, object, and entity IDs;

  • IDs in APIs, messages, fixtures, seeds, migrations, caches, logs, and metadata; and

  • generated repository metadata when its value is a UUID.

It does not require changing an opaque identifier that is explicitly owned by an external system, nor does it convert Git commit IDs, content hashes, ULIDs, URLs, or GitHub repository identities into UUIDs. Such values MUST be typed and labelled as their actual namespace rather than being called uuid.

Generation and representation requirements

  1. New UUIDs MUST be generated by a well-tested library’s v7 API. Hand-rolled bit manipulation and timestamp-plus-random string recipes are forbidden.

  2. Implementations MUST set version 7 and RFC variant 10, and MUST use a cryptographically secure source for the random bits.

  3. Text output MUST be lowercase canonical form. Parsers MAY accept uppercase input at a compatibility boundary, but MUST normalise it before persistence or emission.

  4. Systems generating multiple IDs in one millisecond MUST preserve uniqueness; monotonic v7 generation SHOULD be used where ordering matters.

  5. UUIDs MUST be treated as opaque identifiers. The timestamp MUST NOT be used for authorisation, secrecy, or exact event-time claims.

  6. A v7 timestamp MAY be inspected for operational ordering, subject to clock rollback and clock-skew handling. It MUST NOT be used as a substitute for an audited event timestamp.

Migration: complete estate

The migration applies to every live repository listed by the estate census for both owners, not only repositories that currently contain a UUID search hit. Archived, deleted, vendor, and unavailable repositories are recorded as excluded; unknown or unmeasured repositories are not counted as migrated. The census revision and observation time MUST accompany each migration report.

For each repository and each datastore or wire contract, migration MUST:

  1. inventory UUID columns, schemas, fixtures, APIs, messages, and generated metadata, including indirect library defaults;

  2. classify each value as v7, legacy UUID, external opaque ID, or unknown;

  3. add v7 generation and validation at every write boundary;

  4. preserve legacy values as stable aliases while rewriting internal primary identifiers with a reviewed, deterministic mapping; never derive a v7 UUID by hashing or by copying a legacy UUID;

  5. migrate foreign keys and all references transactionally (or with an equivalent dual-read/dual-write and reconciliation procedure);

  6. maintain an auditable old-to-new mapping protected like production data;

  7. validate uniqueness, referential integrity, API compatibility, and rollback before cutover; and

  8. remove legacy generation paths and mark the migration complete only after a post-cutover scan is clean.

Existing externally visible IDs MUST NOT be silently changed. Use a versioned alias or an explicit compatibility mapping and publish the deprecation and removal date. A migration MUST be reversible until its retention and rollback window has expired.

A repository is migrated only when its migration record says complete, the repository’s default branch enforces v7 at write boundaries, and its latest post-cutover scan passes. not checked, unknown, partial, and blocked are not success states. The estate is migrated only when every in-scope live repository is complete; an aggregate percentage MUST NOT be reported as full completion while any target is not checked.

Enforcement from this revision onward

The control is deliberately layered so that a new bot, a renamed repository, or a change of CI provider cannot silently remove it:

  • CI/CD: the governance reusable workflow runs scripts/check-uuid-v7.sh against every caller checkout. The standards repository also runs the local uuid-v7.yml dogfood workflow. Estate wrappers, including the workflows used by hypatia, cicd-squabbler, .git-private-farm, and gitbot-fleet, MUST consume the pinned governance workflow rather than carrying a private copy of this check.

  • Hypatia: HYP-UUID-001 is the corresponding finding rule. It MUST be enabled in the Hypatia rule set and MUST report unknown or unmeasured targets as non-compliant rather than silently dropping them.

  • Mechanisation: CI repair bots and fleet automation MUST use the checker as a preflight and MUST NOT auto-rewrite legacy IDs. Migration mappings require review, backups, referential-integrity validation, and an auditable result. A bot that cannot read a repository or its migration register MUST stop and report UNMEASURED.

  • Drift prevention: the checker, Hypatia rule, workflow, and this standard are versioned together. Consumers MUST pin the workflow by commit and update the pin when this policy changes. Removing or weakening the gate is a breaking governance change requiring review by both estate owners.

Every estate repository MUST:

  • use this document as the normative UUID policy;

  • add a v7 validation test for every UUID boundary and a regression test that rejects versions other than 7;

  • fail CI for new UUID literals or generated UUIDs that are not v7, except for explicitly typed migration fixtures and external IDs; and

  • record its status in the estate migration register used by the census job.

The portable checker scripts/check-uuid-v7.sh checks canonical UUID literals and can be run against a repository or a list of files. It is intentionally a supplement to type-aware tests: absence of a literal does not prove that a runtime generator is compliant.

Julia project files are the one typed external-identifier context the checker recognises by itself. The General registry assigns every Julia package its UUID and Julia does not let a dependant change it, so the [deps], [weakdeps] and [extras] tables of Project.toml / JuliaProject.toml, and every Manifest*.toml / JuliaManifest*.toml, are not scanned. A package’s own top-level uuid = is still checked: a new estate Julia package MUST mint it as v7 before it is first registered, because the registry fixes it from then on.

References and ownership

The specification is RFC 9562, Universally Unique IDentifiers (UUIDs), Section 5.7 (UUID Version 7). The standard is owned by the maintainers of hyperpolymath/standards; changes require an explicit revision and a migration impact assessment for both estates.

Revision history:

  • 2026-09-29 — v1.0: UUID v7 made the sole estate UUID standard; migration and enforcement requirements established.

  • 2026-10-02 — v1.1: the checker no longer scans registry-assigned Julia dependency UUIDs (Project.toml dependency tables, Manifests). Migration impact: no repository that passed before fails now; Julia repositories whose only findings were dependency UUIDs now pass. Package-own UUIDs stay governed.