Skip to content

fix(events): separate opaque ids from cursor ordinals - #35

Merged
zhanghanduo merged 1 commit into
mainfrom
codex/fix-event-id-ordinal-collision
Sep 8, 2026
Merged

fix(events): separate opaque ids from cursor ordinals#35
zhanghanduo merged 1 commit into
mainfrom
codex/fix-event-id-ordinal-collision

Conversation

@zhanghanduo

Copy link
Copy Markdown
Collaborator

Summary

  • guarantee new_event_id() has an alphabetic hex namespace marker, preventing opaque IDs from overlapping decimal cursor ordinals
  • preserve the existing 16-character lowercase-hex shape and 60 random bits by replacing the fixed UUID4 version nibble
  • add a deterministic regression for an all-decimal UUID source and remove the probabilistic contract-test failure
  • document the AgentComm store contract and bump the package to 0.9.1

Root cause

event_ordinal() accepts decimal event IDs as a compatibility fallback. The previous new_event_id() returned uuid4().hex[:16]; because the UUID4 version nibble is always 4, the complete ID was decimal with probability (10/16)^15, about 1 in 1,153. On those events, AgentComm.consume() accepted the opaque ID as an ordinal and advanced its in-process cursor to a huge non-monotonic value.

Compatibility

The generated ID remains exactly 16 lowercase hexadecimal characters. The explicit e marker replaces the non-random UUID version nibble, so collision entropy remains 60 bits. Decimal IDs assigned by legacy stores remain accepted by event_ordinal().

Validation

  • uv run pytest -q: 1510 passed, 1 skipped
  • uv run ruff check .: passed
  • uv run pyright: 0 errors
  • uv build: wheel and sdist built successfully
  • git diff --check: passed
  • version-bump check: passed

@zhanghanduo
zhanghanduo merged commit 276ddb6 into main Sep 8, 2026
5 checks passed
@zhanghanduo
zhanghanduo deleted the codex/fix-event-id-ordinal-collision branch September 8, 2026 10:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant