RFC 0009: UUIDv7 Identifier Migration

• Related RFC: RFC 0007: Global Database
• Related technical design: Global Database
• Status: Proposed

Summary

Adopt UUIDv7 generation for newly created UUID-backed domain identifiers through the shared identifier factory abstractions. Existing persisted UUID values remain valid and unchanged unless a later, separately approved migration establishes that a full replacement is necessary.

This RFC owns identifier format, generation, and any future persisted-identifier conversion. It does not make UUIDv7 a prerequisite for the Global Database cutover.

Motivation

The project currently generates UUID-backed identifiers through shared factory abstractions. UUIDv7 would provide time-ordered generation, improving insertion ordering, temporal sorting, and operational debugging. However, existing UUID values are already persisted and referenced across features and storage boundaries.

Changing generation is therefore distinct from rewriting existing values. A persisted-identifier migration would affect account identifiers, serialized references, import/export compatibility, and any code that assumes an identifier value is stable for its lifetime. It needs its own decision, inventory, failure handling, and rollout.

Proposal

Ownership and module placement

• AccountId remains in feature:account:api.
• FolderId belongs to feature:mail:folder:api.
• MessageId, ThreadId, and AttachmentId belong to feature:mail:message:api.
• BaseIdentifier, BaseUuidIdentifier, IdentifierFactory, and BaseUuidIdentifierFactory remain in core:architecture:api.
• No core:types:api module is introduced by this RFC.

Domain identifiers are not generic database infrastructure. Generic identifier abstractions stay in core, while concrete identifier types remain with their owning feature or domain. The Global Database uses this ownership model but does not own UUID format policy.

Rollout

UUIDv7 adoption proceeds in two independent steps:

1. Add UUIDv7 generation support to BaseUuidIdentifierFactory and make it the generation policy for newly created UUID-backed identifiers.
2. Decide separately whether existing persisted identifiers require replacement for format consistency.

Factory parsing and equality must remain compatible with existing UUID values. UnifiedAccountId remains the nil UUID. It is a sentinel value and is never generated by the factory.

The Global Database cutover preserves existing AccountId values. Its identifier mappings and persistence-local keys must be correct regardless of whether UUIDv7 support lands before or after cutover. UUIDv7 does not authorize changing existing identifiers as part of that migration.

Persisted identifier consistency

The default rollout is mixed historical UUIDs and newly generated UUIDv7 values. This avoids rewriting references that are already durable. If consistent UUIDv7 values for all persisted entities become a product or operational requirement, the project must approve a follow-up implementation plan before changing any persisted identifier.

That plan must inventory every persistence boundary that stores a UUID-backed identifier, including account configuration, profile runtime storage, global-mail records, serialized queues, notifications and deep links, caches, and import/export formats. It must update all references atomically per boundary and define interruption, retry, and rollback-before-cutover behavior.

Alternatives Considered

Keep existing UUID generation

This avoids all rollout work but does not provide UUIDv7’s time-ordering properties for new identifiers.

Rewrite all persisted UUIDs during the UUIDv7 factory rollout

This would provide immediate format consistency but combines a small factory change with broad, high-risk data migrations across unrelated storage owners.

Rewrite identifiers during Global Database migration

Global Database already migrates mail data and must preserve a strict cutover boundary. Adding account and other cross-boundary UUID rewrites would expand its scope and could not cover storage outside mail. The two migrations remain separate.

Risks & Drawbacks

• Historical and newly generated identifiers are mixed until a separately approved persisted-identifier migration runs.
• UUIDv7 generation must preserve uniqueness and correct ordering behavior under concurrent generation.
• A future full replacement requires broad compatibility testing and careful handling of external or imported data that treats identifiers as immutable.

Validation

• Unit tests cover UUIDv7 generation behavior in the shared factory abstraction.
• Compatibility tests verify parsing and equality for existing UUID values, UUIDv7 values, and UnifiedAccountId.
• A future persisted-identifier migration includes migration tests for every identified persistence boundary.
• Import/export round-trip tests cover each format that contains identifier values.

Open Questions

• Is mixed historical UUIDs plus UUIDv7 for newly generated values acceptable long-term?
• Do any external or imported data formats require identifier values to remain immutable?
• If full persisted consistency is required, which persistence boundary should be migrated first and what rollback scope is acceptable?

Outcome

Pending review.

If accepted, this RFC authorizes UUIDv7 generation for new UUID-backed identifiers. Any rewrite of existing persisted identifiers requires a follow-up technical design and separate approval.