UID 6.0 hardening, Runwire integration, and release readiness

.github/workflows/release-acceptance.yml

@@ -0,0 +1,50 @@
+name: UID 6 Release Acceptance
+
+on:
+  workflow_dispatch:
+  push:
+    branches: ["main", "master"]
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "composer.json"
+      - ".github/workflows/release-acceptance.yml"
+  pull_request:
+    branches: ["main", "master"]
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "composer.json"
+      - ".github/workflows/release-acceptance.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  production-smoke:
+    name: Production smoke (PHP ${{ matrix.php }})
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      fail-fast: false
+      matrix:
+        php: ["8.4", "8.5"]
+    steps:
+      - name: Checkout exact candidate
+        uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event.pull_request.head.sha || github.sha }}
+
+      - name: Setup PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          tools: composer:v2
+          extensions: ctype
+          coverage: none
+
+      - name: Install production dependencies
+        run: composer install --no-dev --no-interaction --prefer-dist --no-progress --classmap-authoritative
+
+      - name: Check every generator and format in one 100-cycle pass
+        run: php tests/smoke.php

.github/workflows/security-standards.yml

@@ -5,19 +5,29 @@ on:
     - cron: "0 0 * * 0"
   push:
     branches: [ "main", "master" ]
+    tags: [ "v*", "[0-9]*" ]
   pull_request:
     branches: [ "main", "master", "develop", "development" ]
 
 jobs:
   phpforge:
+    if: github.event_name != 'push' || !startsWith(github.ref, 'refs/tags/')
     uses: infocyph/phpforge/.github/workflows/security-standards.yml@main
     with:
       fail_on_skipped_tests: true
       integration_services: '[]'
       service_topologies: '{}'
-      php_extensions: '["bcmath"]'
+      php_extensions: '["ctype", "pcntl"]'
     permissions:
       security-events: write
       actions: read
       contents: read
 
+  release:
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+    uses: infocyph/phpforge/.github/workflows/release.yml@main
+    permissions:
+      contents: write
+    secrets:
+      COPILOT_GITHUB_TOKEN: ${{ secrets.COPILOT_GITHUB_TOKEN }}
+

.gitignore

@@ -1,20 +1,20 @@
-.idea
-.psalm-cache
-.phpunit.cache
-.vscode
-.windsurf
-.codex
+/.idea
+/.psalm-cache
+/.phpunit.cache
+/.vscode
+/.windsurf
+/.codex
 *~
 *.patch
 *.txt
 !docs/requirements.txt
-AI_CONTEXT.md
 composer.lock
 example
 example.php
-git-story_media
+/git-story_media
 patch.php
 test.php
-var
-vendor
+/var
+/vendor
 d2utmp*
+/graphify-out

README.md

@@ -18,13 +18,16 @@ All-in-one unique ID toolkit for PHP.
 - TypeID, ObjectID, NanoID, RandomId, CUID2, KSUID, XID
 - Opaque and deterministic IDs
 - Value objects and comparator utilities
-- Binary conversion and base encoders (`16`, `32`, `36`, `58`, `62`)
+- Binary conversion and base encoders (`10`, `16`, `32`, `36`, `58`, `62`)
 - Pluggable sequence providers (filesystem, memory, PSR-16 cache, callback)
+- Explicit legacy/upstream Sonyflake and Randflake compatibility modes
+- Optional PSR-20 clocks and Runwire 2.1.1+ cooperative wait integration
 
 ## Requirements
 
-- PHP `>=8.2`
+- PHP `>=8.4`
 - A 64-bit PHP runtime
+- PHP ctype extension
 
 ## Installation
 
@@ -75,7 +78,7 @@ $decoded = UUID::fromBase($base58, 58);
 ```
 
 The shared byte-level encoder is available as
-`Infocyph\UID\Support\BaseEncoder` for bases `16`, `32`, `36`, `58`, and `62`.
+`Infocyph\UID\Support\BaseEncoder` for bases `10`, `16`, `32`, `36`, `58`, and `62`.
 
 ## References
 
@@ -98,6 +101,10 @@ UID is protected by [PHPForge](https://github.com/infocyph/PHPForge), an automat
 tests, static and taint analysis, dependency auditing, architecture checks, and release readiness. Automated controls reduce
 risk but do not replace responsible disclosure or manual review.
 
+Release acceptance also runs `php tests/smoke.php` with a production-only install on PHP 8.4 and 8.5.
+One 100-cycle pass covers every generator and supported format, checking valid output, sample uniqueness,
+and relevant round trips. Long HTTP benchmarks and soak runs are not release gates.
+
 ---
 
 <div align="center">

TBSL.md

@@ -23,50 +23,53 @@ Character positions are 1-based.
 
 | Characters | Length | Field | Description |
 |:--|--:|:--|:--|
-| 1-15 | 15 hex chars | Time-machine payload | Uppercase hexadecimal encoding of the decimal payload `SSSSSSSSSSUUUUUUMM`, left-padded with zeroes to 15 characters. |
-| 16-20 | 5 hex chars | Entropy or sequence | Random suffix by default, or a sequence suffix when sequenced mode is enabled. |
+| 1-15 | 15 hex chars | Time-machine payload | Uppercase hexadecimal encoding of the 60-bit integer `(unixMicroseconds * 100) + machineId`, left-padded with zeroes to 15 characters. |
+| 16-20 | 5 hex chars | Sequence or entropy | Zero-based sequence suffix by default, or random entropy when sequenced mode is disabled. |
 
-The decimal payload is composed as follows:
+The time-machine payload is numeric, not a fixed-width decimal string. Parsing is:
 
-| Decimal digits | Length | Field | Description |
-|:--|--:|:--|:--|
-| 1-10 | 10 digits | Unix seconds | Seconds since the Unix epoch. |
-| 11-16 | 6 digits | Microseconds | Microsecond fraction of the current second. |
-| 17-18 | 2 digits | Machine ID | Machine identifier from `00` to `99`. |
+```text
+unixMicroseconds = intdiv(payload, 100)
+machineId        = payload % 100
+```
+
+This representation remains valid when Unix seconds grow beyond ten decimal
+digits, as long as the combined value still fits the 60-bit field.
 
 ## Generation
 
 Generation accepts:
 
 - `machineId`: integer from `0` to `99`; default is `0`.
-- `sequenced`: boolean; default is `false`.
+- `sequenced`: boolean; default is `true`. Use `generateRandom()` or `sequenced: false` for the entropy suffix.
 
 The generator:
 
 1. Reads the current Unix time with microsecond precision.
-2. Builds the decimal time sequence as `seconds + microseconds`.
-3. Appends the two-digit machine ID to form `SSSSSSSSSSUUUUUUMM`.
-4. Converts that decimal payload to hexadecimal and left-pads it to 15
-   characters.
+2. Converts that time to an integer count of Unix microseconds.
+3. Forms the 60-bit time-machine payload as `(unixMicroseconds * 100) + machineId`.
+4. Converts that integer to hexadecimal and left-pads it to 15 characters.
 5. Appends a 5-character hexadecimal suffix:
-   - random mode: first 5 hex characters from 3 random bytes;
-   - sequenced mode: the next sequence value for the
-     `(type = "tbsl", machineId, timestamp)` key, encoded as hex and padded to
-     5 characters.
+   - sequenced mode (default): obtains a positive provider allocation from
+     `(type = "tbsl", machineId, timestamp)`, then encodes
+     `allocation - 1` as five hexadecimal characters;
+   - random mode: first 5 hex characters from 3 random bytes.
 6. Returns the 20-character uppercase hexadecimal string.
 
-Sequence providers should keep returned sequence values within the 20-bit suffix
-range, `0x00000` through `0xFFFFF`.
+In sequenced mode, provider allocations `1..0x100000` map to encoded suffixes
+`00000..FFFFF`. If that range is exhausted for one timestamp, generation waits
+for the next usable timestamp or fails according to the configured bounded-wait
+and clock-backward policy.
 
 ## Parsing
 
 To parse a canonical TBSL value:
 
 1. Validate the string against `^[0-9A-F]{20}$`.
-2. Decode characters `1-15` from hexadecimal to the decimal payload.
-3. Read the first 10 decimal digits as Unix seconds.
-4. Read the next 6 decimal digits as microseconds.
-5. Read the final 2 decimal digits as the machine ID.
+2. Decode characters `1-15` from hexadecimal to the 60-bit payload.
+3. Recover Unix microseconds with `intdiv(payload, 100)`.
+4. Recover the machine ID with `payload % 100`.
+5. Build the timestamp from the recovered seconds and microsecond fraction.
 
 The suffix is intentionally opaque. It is not needed to recover the timestamp or
 machine ID.
@@ -80,18 +83,20 @@ move forward.
 For IDs generated within the same microsecond and machine ID:
 
 - random mode provides uniqueness through entropy, but not generation order;
-- sequenced mode provides deterministic suffix ordering while the sequence value
-  remains within the 5-character hexadecimal suffix.
+- sequenced mode provides deterministic suffix ordering while the sequence range
+  remains available.
 
 If the clock moves backward, the implementation either waits for the next usable
 time sequence or throws, depending on the configured clock-backward policy.
+Waits are bounded; a frozen injected clock cannot spin indefinitely.
 
 ## Encodings
 
 The canonical representation is uppercase hexadecimal. The package can also
 convert canonical TBSL values to and from:
 
 - raw 10-byte binary;
+- base10;
 - base16;
 - base32;
 - base36;
@@ -105,7 +110,8 @@ canonical 20-character uppercase hexadecimal TBSL string.
 
 - Canonical size: 20 hex characters.
 - Binary size: 10 bytes.
+- Time-machine payload: 60 bits.
 - Timestamp precision: microseconds.
 - Machine ID range: `0` through `99`.
 - Suffix size: 5 hex characters, or 20 bits.
-- Maximum suffix cardinality per `(timestamp, machineId)` key: 1,048,576 values.
+- Sequenced suffix cardinality per `(timestamp, machineId)` key: 1,048,576 values.

benchmarks/BaseCodecBench.php

@@ -5,20 +5,40 @@
 namespace Infocyph\UID\Benchmarks;
 
 use Infocyph\UID\Support\BaseEncoder;
+use Infocyph\UID\Support\DecimalBytes;
+use Infocyph\UID\Support\NumericIdCodec;
+use Infocyph\UID\Support\TypeIdCodec;
 use PhpBench\Attributes as Bench;
 
 final class BaseCodecBench
 {
+    /** @var array<int, string> */
+    private array $decimal = [];
+
+    /** @var array<int, array<int, string>> */
+    private array $encoded = [];
+
     /** @var array<int, string> */
     private array $samples = [];
 
+    private string $typeIdEncoded;
+
     public function __construct()
     {
         require_once __DIR__ . '/BenchBootstrap.php';
         BenchBootstrap::load();
-        foreach ([8, 10, 12, 16, 20, 32] as $length) {
-            $this->samples[$length] = random_bytes($length);
+
+        foreach ([8, 10, 12, 16, 20, 32, 64] as $length) {
+            $sample = random_bytes($length);
+            $this->samples[$length] = $sample;
+            $this->decimal[$length] = DecimalBytes::fromBytes($sample);
+
+            foreach ([10, 16, 32, 36, 58, 62] as $base) {
+                $this->encoded[$base][$length] = BaseEncoder::encodeBytes($sample, $base);
+            }
         }
+
+        $this->typeIdEncoded = TypeIdCodec::encode($this->samples[16]);
     }
 
     #[Bench\Revs(1000), Bench\Iterations(5), Bench\ParamProviders('provideLengths')]
@@ -57,6 +77,59 @@ public function benchDecimal(array $params): void
         BaseEncoder::encodeBytes($this->sample($params), 10);
     }
 
+    #[Bench\Revs(250), Bench\Iterations(5), Bench\ParamProviders('provideBaseLengthPairs')]
+    public function benchDecode(array $params): void
+    {
+        BaseEncoder::decodeToBytes(
+            $this->encoded[$params['base']][$params['length']],
+            $params['base'],
+            $params['length'],
+        );
+    }
+
+    #[Bench\Revs(500), Bench\Iterations(5), Bench\ParamProviders('provideLengths')]
+    public function benchNumericFromBytes(array $params): void
+    {
+        NumericIdCodec::decimalFromBytes($this->sample($params), $params['length']);
+    }
+
+    #[Bench\Revs(500), Bench\Iterations(5), Bench\ParamProviders('provideLengths')]
+    public function benchNumericToBytes(array $params): void
+    {
+        DecimalBytes::toFixedBytes($this->decimal[$params['length']], $params['length']);
+    }
+
+    #[Bench\Revs(1000), Bench\Iterations(5)]
+    public function benchTypeIdDecode(): void
+    {
+        TypeIdCodec::decode($this->typeIdEncoded);
+    }
+
+    #[Bench\Revs(1000), Bench\Iterations(5)]
+    public function benchTypeIdEncode(): void
+    {
+        TypeIdCodec::encode($this->samples[16]);
+    }
+
+    /**
+     * @return array<string, array{base:int,length:int}>
+     */
+    public function provideBaseLengthPairs(): array
+    {
+        $pairs = [];
+
+        foreach ([10, 16, 32, 36, 58, 62] as $base) {
+            foreach ([8, 10, 12, 16, 20, 32] as $length) {
+                $pairs['base-' . $base . '-' . $length . '-bytes'] = [
+                    'base' => $base,
+                    'length' => $length,
+                ];
+            }
+        }
+
+        return $pairs;
+    }
+
     /**
      * @return array<string, array{length:int}>
      */
@@ -69,6 +142,7 @@ public function provideLengths(): array
             '16-bytes' => ['length' => 16],
             '20-bytes' => ['length' => 20],
             '32-bytes' => ['length' => 32],
+            '64-bytes' => ['length' => 64],
         ];
     }