Tracking issue: spec clarifications and implementation improvements

[kpiljoong]

This issue tracks potential improvements to the OrderlyID specification and the Go reference implementation.

The items below reflect early design and implementation review. They are grouped by scope and priority to keep smaller fixes separate from larger design discussions.

Not all items listed here will necessarily be implemented. This issue serves as a place to organize and track possible future work.

Individual items may be split into separate issues as work begins.

---

Immediate fixes

Relatively small improvements or clarifications that can be addressed without significant design changes.

• Fix the duplicated checksum section in the specification.
• Clarify bit numbering, explicitly stating that flag bit 7 is the most significant bit.
• Specify tenant and shard semantics when unused (for example 0 meaning unset).
• Add fuzz tests for parsing, Base32 decoding, and checksum validation.
• Add helper APIs for inspecting ID flags.

---

Short-term investigation

These items require measurement or evaluation before deciding whether changes are needed.

• Add benchmarks for ID generation and parsing.
• Compare generation and parsing performance with other ID formats and libraries.
• Review potential mutex/global-sequence contention in the generator.
• Evaluate whether the sequence should remain global or become generator-scoped.
• Evaluate whether sequence behavior should be independent per tenant or shard.
• Review the maximum prefix length relative to the recommended SQL column width.
• Evaluate checksum delimiter ergonomics (for example - vs _) with respect to text selection and copy/paste behavior.
• Audit the README, spec, and implementation for consistency around epoch, prefix length, delimiter, privacy claims, and unused-field semantics.

---

Larger design considerations

These items involve broader design choices that may affect the specification or public API and therefore require careful discussion.

• Reconsider the timestamp epoch choice (currently 2020-01-01) and evaluate alternatives such as the Unix epoch.
• Specify behavior for timestamps earlier than the chosen epoch.
• Evaluate whether to support an alternate non-time leading field for privacy-sensitive use cases.
• Consider introducing a typed ID API instead of returning plain strings.
• Consider introducing a Generator type with reusable defaults such as tenant, shard, checksum, and bucketing.
• Allow custom clock sources for testing and specialized environments.
• Allow custom random sources for deterministic tests.
• Re-evaluate the bit allocation between sequence and random fields.
• Document the rationale for the current entropy budget if the current layout is retained.

---

Testing and developer experience

Additional improvements focused on robustness and testability.

• Improve compatibility with controlled-clock testing environments.
• Add tests covering pre-epoch timestamp behavior once defined.
• Add deterministic test paths via injectable clock and randomness sources.