Add default UUIDv7 generator with tests and docs

[leynos]

Summary

• Add a centralized default_uuid7_generator() to produce RFC 4122 compliant UUIDv7 values as lowercase 32-character hex strings (no dashes), with millisecond precision. Uses the uuid-utils library to generate UUIDv7 values (no stdlib-based fallback in the current implementation).

Changes

• New module correlation_id.py at the repo root containing:
  • def default_uuid7_generator() -> str: returning a lowercase 32-character hex UUIDv7 string (no dashes).
  • Implementation uses uuid_utils.uuid7().hex from the uuid-utils library. No Python stdlib UUIDv7 path is implemented/used.
• Updated dependencies:
  • Added uuid-utils>=0.14,<0.15 to pyproject.toml (used by the generator).
• Tests:
  • tests/test_correlation_id.py validating:
    • output length is 32 characters
    • output is lowercase hex
    • version nibble equals 7
    • variant bits are RFC 4122 compliant
    • 1,000+ calls yield unique values
• Testing scaffolding for behavior-driven tests:
  • New BDD files under tests/bdd/ (feature files and step definitions) to cover generation scenarios.
• Documentation artifacts:
  • New execution plan doc: docs/execplans/2-2-1-default-uui-dv7-generator.md detailing discovery, tests, implementation, and validation steps.
  • Update references in design/docs as needed (e.g., docs/falcon-correlation-id-middleware-design.md, docs/users-guide.md).
• Plan alignment:
  • Align with the ExecPlan stages (Discovery, Testing scaffolding, Implementation, Documentation, Validation).

How it works

• The generator returns a plain, dash-less 32-character lowercase hex string by invoking uuid_utils.uuid7().hex from the uuid-utils package.
• This repository relies on uuid-utils for UUIDv7 generation (no stdlib fallback implemented).
• The implementation is a single source of truth for UUID generation to keep correlation ID lifecycle consistent.

Quick usage

from correlation_id import default_uuid7_generator

print(default_uuid7_generator())  # e.g. 1b2e3d4f5a6b7c8d9e0f1a2b3c4d5e6f

Testing plan

• Run: make check-fmt, make typecheck, make lint, make test
• Unit tests verify format, version nibble, variant bits, and uniqueness
• BDD scenarios validate end-to-end behavior of ID generation

Documentation updates

• Add/update docs with design decisions:
  • Why stdlib vs third-party library for UUIDv7 support
  • Output format and precision guarantees
• Update user-facing docs to describe the new API and usage
• Mark ExecPlan item 2.2.1 as complete once tests pass and docs are updated

Validation and acceptance

• Unit tests cover format, version, variant, and uniqueness
• BDD scenarios verify generation behavior
• Documentation reflects the new API and design decisions
• Makefile gates (fmt, typecheck, lint, test) pass locally/CI

Notes

• If additional dependencies are introduced for Python 3.12 compatibility, keep them to a minimum and document rationale in the design doc.
• All changes should be re-runnable and isolated to the correlation ID lifecycle area.

📎 Task: https://www.terragonlabs.com/task/1e05c78b-7390-47a5-be95-b2db55ce697f

[sourcery-ai]

Reviewer's Guide

Introduces a centralized default_uuid7_generator() for correlation IDs, with accompanying unit/BDD tests and documentation, anchored by a new ExecPlan document that describes the design, implementation strategy, and validation steps for UUIDv7 generation.

Sequence diagram for correlation ID generation via default_uuid7_generator

sequenceDiagram
  actor Developer
  participant Application
  participant CorrelationIdModule
  participant StdlibUUID as StdlibUUID_or_ThirdParty

  Developer ->> Application: Request new correlation ID
  Application ->> CorrelationIdModule: default_uuid7_generator()
  CorrelationIdModule ->> StdlibUUID: generate_uuid7()
  StdlibUUID -->> CorrelationIdModule: UUIDv7 instance
  CorrelationIdModule ->> CorrelationIdModule: normalize to lowercase 32-char hex
  CorrelationIdModule -->> Application: correlation_id_string
  Application -->> Developer: correlation_id_string

Loading

Class diagram for correlation ID generator module and tests

classDiagram
  class CorrelationIdModule {
    +default_uuid7_generator() str
  }

  class StdlibUUIDModule {
    +uuid7() UUID
  }

  class UUIDUtilsLibrary {
    +uuid7() UUID
  }

  class TestCorrelationId {
    +test_output_length_32()
    +test_output_lowercase_hex()
    +test_version_nibble_is_7()
    +test_variant_bits_rfc4122()
    +test_many_calls_unique()
  }

  class BDDFEatureGenerateUUIDv7 {
    +Scenario_generate_default_UUIDv7_correlation_id
    +Scenario_multiple_ids_are_unique
  }

  CorrelationIdModule ..> StdlibUUIDModule : optional_dependency
  CorrelationIdModule ..> UUIDUtilsLibrary : fallback_dependency
  TestCorrelationId ..> CorrelationIdModule : uses
  BDDFEatureGenerateUUIDv7 ..> CorrelationIdModule : uses

Loading

Flow diagram for UUIDv7 source selection in default_uuid7_generator

flowchart TD
  A[Call default_uuid7_generator] --> B{Stdlib UUIDv7 available on Python runtime}
  B -->|Yes| C[Use stdlib uuid_module to generate UUIDv7]
  C --> D[Convert UUID to lowercase 32-character hex string without dashes]
  D --> E[Return correlation ID string]
  B -->|No| F[Use third-party uuid_utils_library to generate UUIDv7]
  F --> D

Loading

File-Level Changes

Change	Details	Files
Document the execution plan and lifecycle for introducing a default UUIDv7 correlation ID generator.	Add an ExecPlan document describing purpose, constraints, risks, and validation criteria for the UUIDv7 generator work Lay out staged plan (discovery, test scaffolding, implementation, documentation, validation) including concrete commands and artifacts Record initial decisions, risks, tolerances, and acceptance criteria related to UUIDv7 generation and documentation updates	docs/execplans/2-2-1-default-uui-dv7-generator.md
Add a default UUIDv7 generator API and centralize correlation ID generation.	Introduce a new correlation_id module exposing default_uuid7_generator() returning 32-character lowercase hex strings without dashes Implement UUIDv7 generation using stdlib uuid on Python 3.12+ when available, with a fallback to a third-party UUIDv7 library Ensure UUIDs are RFC 4122 compliant with version nibble 7 and correct variant bits, with millisecond timestamp precision	correlation_id.py
Add automated tests (unit and BDD) to validate UUIDv7 generator behavior and uniqueness.	Create pytest unit tests to validate string length, lowercase hex format, version nibble, variant bits, and uniqueness over many calls Add pytest-bdd feature files and step definitions to cover end-to-end UUIDv7 generation scenarios for correlation IDs Wire new tests into existing test infrastructure so they run via standard Makefile targets	tests/test_correlation_id.py tests/bdd/*.feature tests/bdd/**/steps_*.py
Update design and user-facing documentation to cover the new correlation ID generator API and decisions.	Document rationale for preferring stdlib UUIDv7 versus a third-party library and any new dependency choices Describe the output format, precision guarantees, and usage examples for default_uuid7_generator() Align existing design/user docs and roadmap/plan items with the new generator and mark the relevant ExecPlan stage as complete	docs/falcon-correlation-id-middleware-design.md docs/users-guide.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch terragon/implement-default-uuidv7-generator-9z5qqm

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[codescene-delta-analysis]

Gates Failed
Prevent hotspot decline (1 hotspot with Overall Code Complexity)
Enforce advisory code health rules (2 files with Overall Code Complexity, Excess Number of Function Arguments)

Gates Passed
4 Quality Gates Passed

See analysis details in CodeScene

Reason for failure

Prevent hotspot decline	Violations	Code Health Impact
main.py	1 rule in this hotspot	8.72 → 8.19	Suppress

Enforce advisory code health rules	Violations	Code Health Impact
main.py	1 advisory rule	8.72 → 8.19	Suppress
test_cross_install.py	1 advisory rule	9.39 → 9.10	Suppress

Quality Gate Profile: Pay Down Tech Debt
Want more control? Customize Code Health rules or catch issues early with our IDE extension and CLI tool.