pikaid 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b56920541de19dfaf3c786b32ecbe641e0cd861905187632871bc6610ed8c9c4
+  data.tar.gz: 766fcbcf2f053c8bd2d1da9ec47249baf1b62c325ec6cd336ce5ee805194d5a5
+SHA512:
+  metadata.gz: 66a63d685fbbc25b160e1c48ebde07c7d10ab42d7375ee5da6977cdac144977ff5fad141ba16dfc342b065fb18473e05b423b11e2a1525563fed756b235ca9f8
+  data.tar.gz: da008d152fd8e36423ccba3b0d706d401b2da1c95e9f6ae007049d19d160404063daee4deaf64d38459466c9847919af4b39e38ca6580cf4d5faf847ce2c0d07

data/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to the official Ruby implementation of pikaid are
+documented in this file.
+
+The pikaid **identifier format** is immutable and unversioned. Entries here
+version the Ruby library only.
+
+## [1.0.0] - 2026-11-07
+
+First stable release of the Ruby implementation. The release is prepared in the
+repository; the gem has **not** been published to RubyGems yet.
+
+### Added
+
+- `Pikaid::Id`, an immutable value object with `timestamp`, `randomness`,
+  `entropy`, `randomness_hex`, `to_s`, and `to_binary`.
+- Module API: `generate`, `generate_binary`, `parse`, `from_binary`, `valid?`,
+  `valid_binary?`, `well_formed?`, `timestamp`, `randomness`, `entropy`,
+  `decode`, `to_binary`, and `compare`.
+- Strict validation that rejects malformed, non-canonical, and overflowing
+  input instead of coercing, truncating, or wrapping it.
+- `Pikaid::InvalidIdError`, `Pikaid::InvalidTimestampError`, and
+  `Pikaid::RandomnessError`, all inheriting from `Pikaid::Error`.
+- Vendored official PHP v1.2.0 conformance vectors, byte-for-byte pinned by
+  SHA-256, plus an independent reference oracle for conversion tests.
+- Installed-gem consumer smoke test and packaged-file inventory check in CI.
+- `SECURITY.md`, a reviewer packet mapping every generation path to the CSPRNG
+  source and the fail-closed error path for the two mandatory manual audits.
+
+### Fixed
+
+- `Pikaid::Id#hash` now derives from the canonical value only. It previously
+  included `self.class`, so a subclass instance that compares equal to a
+  `Pikaid::Id` hashed differently and broke `Hash` lookups.
+- Vector fixtures are forced to LF in the working tree, so their recorded
+  SHA-256 digests hold on Windows checkouts with `core.autocrlf`.
+- The CI matrix now tracks Ruby 2.6 through 4.0 on Ubuntu, Ruby 4.0 on macOS,
+  and Ruby 4.0 on Windows. Ruby 3.5 was never released, so it was replaced by
+  the current stable line rather than being tested as a preview.
+- No `Gemfile.lock` is committed (it is intentionally ignored). A local
+  lockfile pinned to Bundler 1.17.2 and rake 12.3.3 cannot run on Ruby 3.2 or
+  newer, so each Ruby line resolves development dependencies on its own; the
+  verified ranges are minitest 5.25.4 + rake 13.4.2 on Ruby 2.6 and minitest
+  5.27.0 + rake 13.4.2 on Ruby 4.0.
+
+### Security
+
+- Generation fails closed when `SecureRandom.random_bytes(12)` raises or
+  returns the wrong number of bytes. There is no fallback entropy source.
+- pikaid is an identifier, not an authentication token or capability.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 larananas (Lara G.)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,282 @@
+<p align="center">
+  <a href="https://github.com/pikaid/pikaid-specs">
+    <img src="https://raw.githubusercontent.com/pikaid/pikaid-specs/v1.0.4/logo.png" alt="pikaid" width="300">
+  </a>
+</p>
+
+<p align="center">
+  <strong>Small · Sortable · Secure ID generator</strong>
+</p>
+
+<div align="center">
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Ruby](https://img.shields.io/badge/language-Ruby-CC342D.svg)](https://github.com/pikaid/pikaid-ruby)
+[![CI](https://github.com/pikaid/pikaid-ruby/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/pikaid/pikaid-ruby/actions/workflows/ci.yml)
+[![Official implementation](https://img.shields.io/badge/official-implementation-2e7d32.svg)](https://github.com/pikaid/pikaid-specs)
+[![Specification 1.0.4](https://img.shields.io/badge/spec-1.0.4-4b56a6.svg)](https://github.com/pikaid/pikaid-specs/tree/v1.0.4)
+
+</div>
+
+**pikaid** is the **official Ruby implementation** of a compact, chronologically sortable, collision-resistant identifier format for databases, APIs, and distributed systems.
+
+This is the immutable, unversioned [pikaid format](https://github.com/pikaid/pikaid-specs/tree/v1.0.4), documented in specification revision **1.0.4**.
+
+## ✨ Why pikaid?
+
+- **Short:** Compact, readable IDs for URLs, logs, and API resources.
+- **Sortable:** Lexicographically ordered by timestamp, with **one-second precision**.
+- **Collision-resistant:** 96 bits of cryptographic randomness make collisions extremely unlikely, never impossible.
+- **Storage-friendly:** Use `BINARY(17)` or readable `CHAR(26)`.
+- **Distributed-friendly:** No central sequence generator or coordination required.
+
+## 🧬 Identifier format
+
+A pikaid contains **26 lowercase Base36 characters**: a **7-character Unix-seconds timestamp** followed by **19 characters encoding 96 bits of cryptographic randomness**. Its binary form is **17 bytes**: 5 unsigned big-endian timestamp bytes followed by 12 randomness bytes.
+
+![Identifier structure](https://raw.githubusercontent.com/pikaid/pikaid-specs/v1.0.4/structure.svg)
+
+> **Ordering:** Different seconds sort chronologically. Within the same second, randomness—not issuance order—decides the order.
+
+> **Security:** These are identifiers, **not secrets**, session credentials, authentication tokens, or API keys.
+
+## ⚙️ Requirements
+
+- Ruby **2.6 or newer** (`required_ruby_version >= 2.6.0`).
+- No runtime dependencies beyond the Ruby standard library
+  (`securerandom` is the only cryptographic dependency).
+
+### Support policy
+
+Version `1.0.0` declares MRI/YARV **2.6 through 4.0** and is verified on every
+minor line from 2.6 to 4.0. Ruby 2.6 and 2.7 are end-of-life upstream: they
+remain in the declared range, in CI, and in the verification matrix because the
+gemspec still accepts them, but they are **compatibility-only** and no newer
+language features are used. Ruby 4.0 is the newest stable line; preview and RC
+releases are not supported.
+
+The full native suite and the pinned official adapter were executed on Linux
+containers for Ruby 2.6.10, 2.7.8, 3.0.7, 3.1.7, 3.2.11, 3.3.13, 3.4.12, and
+4.0.9; the host macOS run used Ruby 2.6.10. The push-triggered GitHub Actions
+workflow is configured to test Ruby 2.6 on `ubuntu-22.04`, Ruby 2.7 through 4.0
+on `ubuntu-latest`, and Ruby 4.0 on `macos-latest` and `windows-latest`. A
+separate job installs the built gem into an isolated `GEM_HOME` and exercises
+it from a consumer script, and verifies the packaged file inventory, so
+packaging regressions are caught outside the checkout.
+
+## 📦 Installation
+
+Version `1.0.0` is prepared but the gem is **not published** to RubyGems yet, so
+`gem install pikaid` does not apply. Install it from source:
+
+```sh
+git clone https://github.com/pikaid/pikaid-ruby.git
+cd pikaid-ruby
+bundle install
+bundle exec rake test
+```
+
+To build and install a local gem:
+
+```sh
+gem build pikaid.gemspec
+gem install ./pikaid-1.0.0.gem
+```
+
+The built package contains only `lib/**/*.rb`, `README.md`, `LICENSE`, and
+`CHANGELOG.md`. Local `.ai/` workspace artifacts, tests, CI configuration, and
+build leftovers are never packaged.
+
+## 🚀 Basic Usage
+
+After installing the local gem, save the following as `demo.rb` and execute `ruby demo.rb`:
+
+```ruby
+require "pikaid"
+
+id = Pikaid.generate
+parsed = Pikaid.parse(id)
+bytes = parsed.to_binary
+raise "Invalid identifier" unless Pikaid.valid?(id)
+raise "Binary round-trip failed" unless Pikaid.from_binary(bytes) == parsed
+puts "#{id} @ #{parsed.timestamp}"
+```
+
+## 💡 Example Use Case
+
+Use pikaid to identify **users, orders, invoices, uploads, events, and API resources**. Independent services can generate compact IDs without a shared counter, while timestamp-based ordering helps with indexing, sorting, and logs.
+
+## 📚 Canonical specification
+
+- [Canonical specification](https://github.com/pikaid/pikaid-specs)
+- [Revision 1.0.4](https://github.com/pikaid/pikaid-specs/tree/v1.0.4)
+
+Specification revisions describe the format; they do not change the encoded identifiers.
+
+## 🧩 API Reference
+
+```ruby
+require "pikaid"
+
+# Generate using the current whole second.
+id = Pikaid.generate            #=> "0s44we8..." (26 characters)
+id.class                        #=> String
+id.bytesize                     #=> 26
+
+# Generate with an explicit Unix timestamp (whole seconds).
+Pikaid.generate(timestamp: 1_700_000_000)   #=> 26-character String
+
+# Generate the 17-byte binary form directly.
+Pikaid.generate_binary(timestamp: 1_700_000_000).bytesize  #=> 17
+
+# Parse and decode.
+parsed = Pikaid.parse("0s44we8002loz3po6mcf6vsn23")
+parsed.timestamp        #=> 1700000000
+parsed.randomness       #=> "\x00\x11\"3DUfw\x88\x99\xAA\xBB"
+parsed.randomness_hex   #=> "00112233445566778899aabb"
+parsed.entropy          #=> same bytes as #randomness
+parsed.to_s             #=> "0s44we8002loz3po6mcf6vsn23"
+parsed.to_binary.bytesize  #=> 17
+parsed.to_binary.unpack("H*")[0]
+#=> "006553f10000112233445566778899aabb"
+
+# Pikaid stores whole Unix seconds, not a timezone. Time.at(...).utc is the
+# explicit UTC conversion; no timezone is implied by the identifier itself.
+Time.at(parsed.timestamp).utc.strftime("%Y-%m-%dT%H:%M:%SZ")
+#=> "2023-11-14T22:13:20Z"
+
+# Binary round trip.
+Pikaid.from_binary(parsed.to_binary) == parsed   #=> true
+
+# Strict validation.
+Pikaid.valid?("0s44we8002loz3po6mcf6vsn23")      #=> true
+Pikaid.valid_binary?(parsed.to_binary)           #=> true
+Pikaid.well_formed?("0000000zzzzzzzzzzzzzzzzzzz") #=> true (shape only)
+Pikaid.valid?("0000000zzzzzzzzzzzzzzzzzzz")       #=> false (96-bit overflow)
+
+# Helper functions accept either a String or a Pikaid::Id.
+Pikaid.timestamp(parsed)                 #=> 1700000000
+Pikaid.randomness(parsed)          #=> 12-byte String
+Pikaid.decode(parsed)                    #=> [1700000000, "..."]
+Pikaid.to_binary(parsed)                 #=> 17-byte String
+Pikaid.compare(parsed, parsed)       #=> -1, 0, or 1
+```
+
+### Errors
+
+All errors inherit from `Pikaid::Error`:
+
+```ruby
+begin
+  Pikaid.parse("not-a-pikaid")
+rescue Pikaid::InvalidIdError => error
+  error.reason  #=> :invalid_string_length or :invalid_character, ...
+  error.value   #=> the rejected input
+end
+```
+
+- `Pikaid::InvalidIdError` — text or binary input is not a valid pikaid.
+- `Pikaid::InvalidTimestampError` — a supplied timestamp is negative, out of
+  range, or not an Integer.
+- `Pikaid::RandomnessError` — the cryptographic source failed or returned the
+  wrong number of bytes. Generation fails closed; there is no fallback.
+
+## 🔄 Order Guarantee
+
+- Canonical bytewise/ASCII lexicographic order is chronological **across
+  different seconds**.
+- Identifiers generated within the **same second are not monotonic**. Their
+  order is determined by their random suffix, not by generation time.
+- The timestamp has **whole-second precision only**; there is no sub-second
+  ordering guarantee.
+- Randomness comes from `SecureRandom.random_bytes(12)`. pikaid is **not** an
+  authentication token, does not provide secrecy, and does not guarantee
+  uniqueness. Treat it as a compact, sortable identifier, not as a capability
+  or a security credential.
+
+## 🛢 Storage Recommendations
+
+| Representation | Size | Recommended for |
+| --- | ---: | --- |
+| **BINARY(17)** | 17 bytes | Compact primary keys and indexes |
+| **CHAR(26)** | 26 characters | Readable SQL, debugging, URLs, and logs |
+
+Use an **ASCII bytewise/binary collation** for text columns (for example, `ascii_bin` on MariaDB/MySQL). Case-insensitive or locale-aware sorting is not a substitute for canonical bytewise comparison.
+
+## ✅ Verification and release status
+
+The [CI workflow](https://github.com/pikaid/pikaid-ruby/actions/workflows/ci.yml) runs native tests, pinned automated conformance checks, and language-specific quality gates. To run the native checks locally from a checkout, use `bundle exec rake test`.
+
+**Automated passing tests are not a security certification.** The independent CSPRNG source and failure-path audits (`P-GENERATE-RNG-SOURCE` and `P-GENERATE-RNG-FAILURE`) still require separate human evidence.
+
+<details>
+<summary>Platform, tooling, and conformance details</summary>
+
+```sh
+bundle exec rake syntax    # ruby -c over lib, test, Rakefile, gemspec
+bundle exec rake test      # Minitest suite
+bundle exec rake coverage  # stdlib line coverage; fails below 90%
+gem build pikaid.gemspec   # build the gem
+```
+
+The test suite covers every official PHP v1.2.0 vector, specification
+known-answer cases, malformed and overflow inputs, boundary values, randomized
+round trips against an independent oracle, generated-ID sanity checks, and
+cryptographic failure paths.
+
+The official cross-language suite is
+[pikaid-specs `1.0.0`](https://github.com/pikaid/pikaid-specs/tree/059780cc0e5b113443812720d95c630649bf3aa3/conformance),
+pinned to the immutable commit `059780cc0e5b113443812720d95c630649bf3aa3`
+(specification revision `1.0.4`). `test/support/official_adapter.rb` is a
+test-only JSON-Lines bridge: every operation calls the real public `Pikaid`
+API, the file is not packaged in the gem, and it advertises only capabilities
+the library genuinely provides. `parse_datetime` is omitted because the Ruby
+API exposes whole-second timestamps rather than a datetime accessor.
+
+```sh
+# Run from the pinned suite's conformance/ directory.
+python tools/run_adapter.py --automated-only \
+  -- ruby -I/path/to/pikaid-ruby/lib /path/to/pikaid-ruby/test/support/official_adapter.rb
+```
+
+An `--automated-only` run exiting `0` means the automated checks passed. It is
+**not** a conformance or security certification. A default run (without
+`--automated-only`) exits `3` while the two manual CSPRNG review obligations,
+`P-GENERATE-RNG-SOURCE` and `P-GENERATE-RNG-FAILURE`, remain outstanding.
+Those require independent human review of the entropy source and of the
+failure path, and no automated run can satisfy them. The
+`Official conformance (pinned suite)` CI job executes the automated subset
+only.
+
+</details>
+
+Registry publication is not implied by a green CI: use the installation method documented above.
+
+## 🤝 Contributing
+
+Contributions are always welcome! 💙
+
+Whether you're fixing a typo, improving documentation, adding tests, or making pikaid even better, every contribution is appreciated.
+
+**Want to help? Here's how:**
+
+- 🐛 **Found a bug?** [Open an issue](https://github.com/pikaid/pikaid-ruby/issues) with clear reproduction steps.
+- 💡 **Have an idea?** Start with an issue before making major changes.
+- 🛠️ **Ready to contribute?** Open a pull request explaining your changes.
+- 🧪 **Keep it tested.** Add meaningful regression tests for behavior changes and follow the existing conventions.
+- ✅ **Make sure CI passes.** All required checks must be green before a pull request is merged. No shortcuts!
+
+**One important rule:** pikaid's identifier format is immutable. Contributions must preserve the [canonical specification (revision 1.0.4)](https://github.com/pikaid/pikaid-specs/tree/v1.0.4).
+
+🔐 **Found a security vulnerability?** Report it privately using GitHub's security reporting (when available), or [contact the maintainer](mailto:larananas.dev@proton.me)—not through a public issue.
+
+**Every improvement matters, big or small. Thanks for helping make pikaid better!** 🐇
+
+## 📄 License
+
+The implementation is available under the [MIT License](LICENSE).
+
+## ✉️ Contact
+
+For licensing or project-related questions: [larananas.dev@proton.me](mailto:larananas.dev@proton.me).
+

data/lib/pikaid/codec.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Pikaid
+  # Internal Base36 and big-endian byte helpers.
+  #
+  # This module is not part of the stable public API; use the methods on
+  # {Pikaid} and {Pikaid::Id} instead.
+  module Codec
+    module_function
+
+    # Encode a non-negative Integer as fixed-width lowercase Base36.
+    def encode_base36(value, width)
+      unless value.is_a?(Integer) && value >= 0
+        raise ArgumentError, "value must be a non-negative Integer"
+      end
+
+      encoded = value.to_s(36)
+      if encoded.length > width
+        raise RangeError, "#{value} does not fit in #{width} Base36 characters"
+      end
+
+      encoded.rjust(width, "0")
+    end
+
+    # Decode a Base36 string. Callers must validate the alphabet first.
+    def decode_base36(value)
+      value.to_i(36)
+    end
+
+    # Encode an unsigned Integer as +width+ big-endian bytes.
+    def int_to_bytes(value, width)
+      unless value.is_a?(Integer) && value >= 0 && value < (1 << (8 * width))
+        raise RangeError, "#{value.inspect} does not fit in #{width} bytes"
+      end
+
+      bytes = Array.new(width)
+      (width - 1).downto(0) do |index|
+        bytes[index] = value & 0xff
+        value >>= 8
+      end
+      bytes.pack("C*")
+    end
+
+    # Decode big-endian bytes as an unsigned Integer.
+    def bytes_to_int(bytes)
+      bytes.each_byte.inject(0) { |value, byte| (value << 8) | byte }
+    end
+  end
+end

data/lib/pikaid/constants.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Pikaid
+  # Total length of the canonical text representation, in ASCII characters.
+  STRING_LENGTH = 26
+
+  # Total length of the canonical binary representation, in bytes.
+  BINARY_LENGTH = 17
+
+  # Width of the timestamp prefix in the text representation.
+  TIMESTAMP_LENGTH = 7
+
+  # Width of the randomness suffix in the text representation.
+  RANDOMNESS_LENGTH = 19
+
+  # Width of the timestamp field in the binary representation.
+  TIMESTAMP_BYTES = 5
+
+  # Width of the randomness field in the binary representation.
+  RANDOMNESS_BYTES = 12
+
+  # Largest valid timestamp: 36^7 - 1 (4453-04-05 15:21:35 UTC).
+  MAX_TIMESTAMP = 78_364_164_095
+
+  # Largest valid randomness value: 2^96 - 1.
+  MAX_RANDOMNESS = 79_228_162_514_264_337_593_543_950_335
+
+  # Permitted alphabet, in ascending digit order.
+  ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyz".freeze
+end

data/lib/pikaid/errors.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Pikaid
+  # Base class for every error raised by pikaid.
+  class Error < StandardError; end
+
+  # Raised when a text or binary value is not a valid pikaid.
+  #
+  # +reason+ is a stable machine-readable symbol describing the first failed
+  # check. +value+ is the rejected input (not included in the message).
+  class InvalidIdError < Error
+    attr_reader :value, :reason
+
+    def initialize(message = "invalid pikaid", value: nil, reason: nil)
+      @value = value
+      @reason = reason
+      super(message)
+    end
+  end
+
+  # Raised when a timestamp cannot be generated or represented.
+  class InvalidTimestampError < Error
+    attr_reader :timestamp, :reason
+
+    def initialize(message = "invalid pikaid timestamp", timestamp: nil, reason: nil)
+      @timestamp = timestamp
+      @reason = reason
+      super(message)
+    end
+  end
+
+  # Raised when secure randomness cannot be obtained or has the wrong size.
+  #
+  # Generation fails closed: this error is never replaced by a non-cryptographic
+  # fallback.
+  class RandomnessError < Error; end
+end

data/lib/pikaid/id.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Pikaid
+  # Immutable value object for a decoded pikaid.
+  #
+  # The canonical text and binary representations are computed once at
+  # construction. Use {Pikaid.parse} or {Pikaid.from_binary} to decode an
+  # existing value; use {Pikaid.generate} for new identifiers.
+  #
+  #   id = Pikaid.parse("0s44we8002loz3po6mcf6vsn23")
+  #   id.timestamp        #=> 1700000000
+  #   id.randomness       #=> "\x00\x11\"3DUfw\x88\x99\xAA\xBB"
+  #   id.randomness_hex   #=> "00112233445566778899aabb"
+  #   id.to_binary.bytesize #=> 17
+  class Id
+    include Comparable
+
+    # Unix timestamp in whole seconds.
+    attr_reader :timestamp
+
+    # Exactly 12 bytes of randomness, as an ASCII-8BIT String.
+    attr_reader :randomness
+
+    # Compatibility alias for the canonical conceptual name +randomness+.
+    alias entropy randomness
+
+    # Build an identifier from decoded components.
+    #
+    # This constructor validates its inputs but does not generate randomness.
+    # Prefer {Pikaid.generate} for creating new identifiers.
+    #
+    # @param timestamp [Integer] whole Unix seconds in 0..MAX_TIMESTAMP
+    # @param randomness [String] exactly 12 bytes
+    # @raise [InvalidTimestampError] if the timestamp is out of range
+    # @raise [InvalidIdError] if the randomness is not exactly 12 bytes
+    def initialize(timestamp, randomness)
+      @timestamp = Validation.timestamp!(timestamp)
+      @randomness = Validation.randomness!(randomness).b.freeze
+
+      @string = (
+        Codec.encode_base36(@timestamp, TIMESTAMP_LENGTH) +
+        Codec.encode_base36(Codec.bytes_to_int(@randomness), RANDOMNESS_LENGTH)
+      ).freeze
+
+      @binary = (
+        Codec.int_to_bytes(@timestamp, TIMESTAMP_BYTES) + @randomness
+      ).freeze
+
+      freeze
+    end
+
+    # The canonical 26-character lowercase Base36 identifier.
+    #
+    # @return [String] a frozen String
+    def to_s
+      @string
+    end
+
+    # The canonical 17-byte binary representation.
+    #
+    # Layout: five big-endian timestamp bytes followed by the original twelve
+    # randomness bytes.
+    #
+    # @return [String] a frozen ASCII-8BIT String
+    def to_binary
+      @binary
+    end
+
+    # The randomness field as 24 lowercase hexadecimal characters.
+    #
+    # @return [String]
+    def randomness_hex
+      @randomness.unpack("H*")[0]
+    end
+
+    # Compatibility alias for {#randomness_hex}.
+    alias entropy_hex randomness_hex
+
+    # Compare two identifiers by canonical bytewise order.
+    #
+    # Identifiers with different timestamps sort chronologically. Identifiers
+    # generated within the same second sort by their random suffix, not by
+    # generation order.
+    #
+    # @param other [Object]
+    # @return [Integer, nil] -1, 0, 1, or nil when +other+ is not an Id
+    def <=>(other)
+      return nil unless other.is_a?(Id)
+
+      @string.b <=> other.to_s.b
+    end
+
+    # Value equality for identifiers.
+    def ==(other)
+      other.is_a?(Id) && @string.b == other.to_s.b
+    end
+
+    alias eql? ==
+
+    # Hash consistent with {#==} and {#eql?}.
+    #
+    # Equality is defined by the canonical value, not by the concrete class, so
+    # the hash must be derived from the value alone. Including +self.class+
+    # would let a subclass instance compare equal to a base instance while
+    # hashing differently, breaking Hash lookup for equal values.
+    def hash
+      @string.hash
+    end
+
+    def inspect
+      "#<#{self.class} #{@string.inspect}>"
+    end
+  end
+end

data/lib/pikaid/validation.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Pikaid
+  # Internal strict validation shared by generation and value objects.
+  module Validation
+    module_function
+
+    # Ensure +timestamp+ is an Integer in 0..MAX_TIMESTAMP.
+    def timestamp!(timestamp)
+      unless timestamp.is_a?(Integer)
+        raise InvalidTimestampError.new(
+          "timestamp must be an Integer, got #{timestamp.class}",
+          timestamp: timestamp,
+          reason: :not_an_integer
+        )
+      end
+
+      if timestamp < 0
+        raise InvalidTimestampError.new(
+          "timestamp must not be negative, got #{timestamp}",
+          timestamp: timestamp,
+          reason: :negative
+        )
+      end
+
+      return timestamp if timestamp <= MAX_TIMESTAMP
+
+      raise InvalidTimestampError.new(
+        "timestamp #{timestamp} exceeds the maximum #{MAX_TIMESTAMP}",
+        timestamp: timestamp,
+        reason: :overflow
+      )
+    end
+
+    # Ensure +randomness+ is exactly 12 bytes.
+    def randomness!(randomness)
+      unless randomness.is_a?(String)
+        raise InvalidIdError.new(
+          "randomness must be a 12-byte String, got #{randomness.class}",
+          value: randomness,
+          reason: :not_a_string
+        )
+      end
+
+      return randomness if randomness.bytesize == RANDOMNESS_BYTES
+
+      raise InvalidIdError.new(
+        "randomness must be exactly #{RANDOMNESS_BYTES} bytes, got #{randomness.bytesize}",
+        value: randomness,
+        reason: :invalid_randomness_length
+      )
+    end
+  end
+end

data/lib/pikaid/version.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Pikaid
+  # Version of the official Ruby implementation.
+  #
+  # The pikaid identifier format itself is immutable and unversioned; this
+  # constant versions the Ruby library only.
+  VERSION = "1.0.0"
+end

data/lib/pikaid.rb

@@ -0,0 +1,260 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+require_relative "pikaid/version"
+require_relative "pikaid/constants"
+require_relative "pikaid/errors"
+require_relative "pikaid/codec"
+require_relative "pikaid/validation"
+require_relative "pikaid/id"
+
+# Official Ruby implementation of pikaid.
+#
+# A pikaid is exactly 26 lowercase ASCII Base36 characters: a seven-character
+# whole-second Unix timestamp followed by nineteen characters encoding 96 bits
+# of cryptographic randomness. Its binary representation is exactly 17 bytes:
+# five big-endian timestamp bytes followed by the same twelve randomness bytes.
+#
+# The format is immutable and unversioned. See the canonical specification:
+# https://github.com/pikaid/pikaid-specs/tree/v1.0.4
+module Pikaid
+  class << self
+    # Generate a new pikaid as a 26-character String.
+    #
+    # Entropy comes from +SecureRandom.random_bytes(12)+. If the cryptographic
+    # source fails, {RandomnessError} is raised; there is no fallback.
+    #
+    # @param timestamp [Integer, nil] whole Unix seconds, or nil for Time.now
+    # @return [String] the canonical text form
+    # @raise [InvalidTimestampError] if the timestamp is out of range
+    # @raise [RandomnessError] if secure randomness cannot be obtained
+    def generate(timestamp: nil)
+      build_id(timestamp).to_s
+    end
+
+    # Generate a new pikaid as a 17-byte binary String.
+    #
+    # @param timestamp [Integer, nil] whole Unix seconds, or nil for Time.now
+    # @return [String] the canonical binary form
+    # @raise [InvalidTimestampError] if the timestamp is out of range
+    # @raise [RandomnessError] if secure randomness cannot be obtained
+    def generate_binary(timestamp: nil)
+      build_id(timestamp).to_binary
+    end
+
+    # Strictly parse a text pikaid.
+    #
+    # Rejects non-String values, non-ASCII bytes, uppercase characters,
+    # invalid characters, wrong lengths, and randomness values above 2^96 - 1.
+    #
+    # @param value [String]
+    # @return [Id]
+    # @raise [InvalidIdError] if +value+ is not a valid pikaid
+    def parse(value)
+      unless value.is_a?(String)
+        raise InvalidIdError.new(
+          "pikaid must be a String, got #{value.class}",
+          value: value,
+          reason: :not_a_string
+        )
+      end
+
+      bytes = value.b
+      if bytes.bytesize != STRING_LENGTH
+        raise InvalidIdError.new(
+          "pikaid must be exactly #{STRING_LENGTH} bytes, got #{bytes.bytesize}",
+          value: value,
+          reason: :invalid_string_length
+        )
+      end
+
+      unless bytes.match?(/\A[0-9a-z]{26}\z/n)
+        raise InvalidIdError.new(
+          "pikaid must contain only lowercase ASCII Base36 characters",
+          value: value,
+          reason: :invalid_character
+        )
+      end
+
+      timestamp = Codec.decode_base36(bytes.byteslice(0, TIMESTAMP_LENGTH))
+      randomness_value = Codec.decode_base36(
+        bytes.byteslice(TIMESTAMP_LENGTH, RANDOMNESS_LENGTH)
+      )
+
+      if randomness_value > MAX_RANDOMNESS
+        raise InvalidIdError.new(
+          "pikaid randomness exceeds the 96-bit maximum",
+          value: value,
+          reason: :randomness_overflow
+        )
+      end
+
+      Id.new(timestamp, Codec.int_to_bytes(randomness_value, RANDOMNESS_BYTES))
+    end
+
+    # Strictly decode a 17-byte binary pikaid.
+    #
+    # @param value [String] exactly 17 bytes
+    # @return [Id]
+    # @raise [InvalidIdError] if the length or timestamp is invalid
+    def from_binary(value)
+      unless value.is_a?(String)
+        raise InvalidIdError.new(
+          "binary pikaid must be a String, got #{value.class}",
+          value: value,
+          reason: :not_a_string
+        )
+      end
+
+      bytes = value.b
+      if bytes.bytesize != BINARY_LENGTH
+        raise InvalidIdError.new(
+          "binary pikaid must be exactly #{BINARY_LENGTH} bytes, got #{bytes.bytesize}",
+          value: value,
+          reason: :invalid_binary_length
+        )
+      end
+
+      timestamp = Codec.bytes_to_int(bytes.byteslice(0, TIMESTAMP_BYTES))
+      if timestamp > MAX_TIMESTAMP
+        raise InvalidIdError.new(
+          "binary pikaid timestamp #{timestamp} exceeds the maximum #{MAX_TIMESTAMP}",
+          value: value,
+          reason: :timestamp_overflow
+        )
+      end
+
+      Id.new(timestamp, bytes.byteslice(TIMESTAMP_BYTES, RANDOMNESS_BYTES))
+    end
+
+    # Full semantic validation of a text pikaid.
+    #
+    # Unlike {well_formed?}, this also rejects randomness above 2^96 - 1.
+    # Returns false for non-String values instead of raising.
+    #
+    # @param value [Object]
+    # @return [Boolean]
+    def valid?(value)
+      parse(value)
+      true
+    rescue InvalidIdError
+      false
+    end
+
+    # Full semantic validation of a binary pikaid.
+    #
+    # @param value [Object]
+    # @return [Boolean]
+    def valid_binary?(value)
+      from_binary(value)
+      true
+    rescue InvalidIdError
+      false
+    end
+
+    # Shape-only check: exactly 26 bytes of [0-9a-z].
+    #
+    # This deliberately does not check the 96-bit randomness limit. A value can
+    # be well formed but not valid; use {valid?} for full validation.
+    #
+    # @param value [Object]
+    # @return [Boolean]
+    def well_formed?(value)
+      return false unless value.is_a?(String)
+
+      bytes = value.b
+      bytes.bytesize == STRING_LENGTH && bytes.match?(/\A[0-9a-z]{26}\z/n)
+    end
+
+    # Extract the timestamp from a text id or {Id}.
+    #
+    # @param value [String, Id]
+    # @return [Integer]
+    # @raise [InvalidIdError]
+    def timestamp(value)
+      coerce_id(value).timestamp
+    end
+
+    # Extract the 12 randomness bytes from a text id or {Id}.
+    #
+    # @param value [String, Id]
+    # @return [String] ASCII-8BIT String
+    # @raise [InvalidIdError]
+    def randomness(value)
+      coerce_id(value).randomness
+    end
+
+    # Compatibility alias for {randomness}.
+    def entropy(value)
+      randomness(value)
+    end
+
+    # Decode a text id or {Id} into [timestamp, randomness bytes].
+    #
+    # @param value [String, Id]
+    # @return [Array(Integer, String)]
+    # @raise [InvalidIdError]
+    def decode(value)
+      id = coerce_id(value)
+      [id.timestamp, id.randomness]
+    end
+
+    # Convert a text id or {Id} to its 17-byte binary representation.
+    #
+    # @param value [String, Id]
+    # @return [String]
+    # @raise [InvalidIdError]
+    def to_binary(value)
+      coerce_id(value).to_binary
+    end
+
+    # Compare two text ids or {Id}s by canonical bytewise order.
+    #
+    # @param left [String, Id]
+    # @param right [String, Id]
+    # @return [Integer] -1, 0, or 1
+    # @raise [InvalidIdError]
+    def compare(left, right)
+      coerce_id(left) <=> coerce_id(right)
+    end
+
+    private
+
+    def build_id(timestamp)
+      value = timestamp.nil? ? Time.now.to_i : timestamp
+      Validation.timestamp!(value)
+      Id.new(value, secure_random_bytes(RANDOMNESS_BYTES))
+    end
+
+    def secure_random_bytes(count)
+      bytes = SecureRandom.random_bytes(count)
+      unless bytes.is_a?(String) && bytes.bytesize == count
+        raise RandomnessError,
+              "secure random source returned #{bytes.inspect} instead of #{count} bytes"
+      end
+
+      bytes.b
+    rescue RandomnessError
+      raise
+    rescue StandardError, SecurityError => error
+      raise RandomnessError,
+            "secure randomness unavailable (#{error.class}: #{error.message})"
+    end
+
+    def coerce_id(value)
+      case value
+      when Id
+        value
+      when String
+        parse(value)
+      else
+        raise InvalidIdError.new(
+          "expected a pikaid String or Pikaid::Id, got #{value.class}",
+          value: value,
+          reason: :not_a_string
+        )
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,93 @@
+--- !ruby/object:Gem::Specification
+name: pikaid
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- larananas (Lara G.)
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.11'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.11'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '12.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '14.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '12.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '14.0'
+description: Compact 26-character sortable Base36 identifiers with 96-bit cryptographic
+  randomness and a 17-byte binary representation.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/pikaid.rb
+- lib/pikaid/codec.rb
+- lib/pikaid/constants.rb
+- lib/pikaid/errors.rb
+- lib/pikaid/id.rb
+- lib/pikaid/validation.rb
+- lib/pikaid/version.rb
+homepage: https://github.com/pikaid/pikaid-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/pikaid/pikaid-ruby
+  source_code_uri: https://github.com/pikaid/pikaid-ruby
+  changelog_uri: https://github.com/pikaid/pikaid-ruby/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.6.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Official Ruby implementation of pikaid
+test_files: []