genoid 1.21.2

[1.21.2] - 2026-07-27

Summary

Barrel export fix: configureRandom, configurePools, configureFootprint now importable from package.

🔧 Internal

• index.ts — added configureRandom, configurePools, configureFootprint to the barrel export. These were documented in the README as public API (microcontroller setup) but missing from index.ts, causing runtime import failures.

genoid 1.21.1

[1.21.1] - 2026-07-27

Summary

Stability fix: INV-3 timeout, Windows bench-db DDL race; paper Zenodo DOI finalized.

🔧 Internal

• research-invariants.test.ts — raised INV-3 timeout from 5s to 30s for 400k-UUID sequential counter-order check on slower machines.
• bench-db.ts — changed DDL to CREATE TABLE IF NOT EXISTS and index to CREATE INDEX IF NOT EXISTS to fix Windows file-lock race in WAL-mode repeated runs.

📖 Documentation

• Availability paragraph — replaced Zenodo DOI placeholder with real DOI (10.5281/zenodo.21617109).

genoid 1.21.0

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog,
and this project adheres to Semantic Versioning.

[1.21.0] - 2026-07-27

Summary

Paper alignment: Algorithm 1 matches code; public API fully tested; artifact availability footnote added.

🔧 Internal

• repairConstraints — deleted dead monotonic branch (_constraintLast saturating counter). Tick-keyed counter lives only in the pool refill path. The exported function now handles only allowed (idempotent modulo) and range (clamp), matching Algorithm 1.
• Public API test coverage — added tests for compileLayout, DBKEY_LAYOUT, MULTITENANT_LAYOUT, EVENTSOURCING_LAYOUT, and CompiledLayout type, closing the coverage gap. 12/12 tests.
• Cross-lang golden vectors — Rust port now matches TS on all 3 layouts × 1000 UUIDs (3000/3000). Two fixes: (1) TS tick-keyed counter no longer double-increments on first UUID; (2) Rust allowed-set repair uses idempotent contains guard. Mutation testing confirms each layout fails under the wrong repair algorithm.

📖 Documentation

• §3.3 — rollover margin corrected to 10× (counter advances once per UUID).
• §4.3 — added idempotent-guard analysis with distribution-neutrality proof for contiguous admissible sets; added range-clamp uniformity disclosure.
• §6.6 — replaced "caught two porting bugs" with the full mutation-result coverage matrix (nearest-value fails dbkey/multitenant; saturating counter fails dbkey/eventsourcing).
• Algorithm 1 — removed tick/ctr state and monotonic branch; allowed branch is now guarded ($v \in A$ vs modulo); range branch is now clamp ($\max(min, \min(v, max))$).
• Title footnote — artifact availability with GitHub URL (tag v1.21.0), npm package, Zenodo DOI placeholder, and reproducibility command.
• §7.3 — noted npm publication as evidence of portability.

[1.20.1] - 2026-07-26

Summary

Fix compiled-path distribution bias: Hamming-nearest LUT replaced with modulo pickFrom for allowed-set fields. Gate compiled path on default CSPRNG so custom RNGs work.

🐛 Bug fixes

• Compiled-path allowed-set distribution (INV-11) — genLayoutSource used Hamming-nearest LUT repair for allowed-constrained fields (shard, node, process), producing Voronoï-biased output. Replaced with modulo-based pickFrom to match the uniform distribution of the pooled interpreted path. interpretRawLayout updated to match. 106/106 tests pass, INV-11 threshold satisfied.
• Custom CSPRNG bypass — genStructuredGenoID used the compiled path regardless of configureRandom(), silently ignoring the custom RNG when the compiled path used globalThis.crypto. Now gated on _fillRandom === _webCryptoFill; falls through to pooled path when a custom CSPRNG is active.

🔧 Internal

• Removed dead Hamming-LUT precomputation code from genLayoutSource and fieldMeta.

Breaking Changes

• None.

[1.20.0] - 2026-07-24

Summary

Bug fixes (pickFrom bias, entropy poisoning), two new benchmark experiments (rejection-cost sweep, DB index-locality), IEEE paper draft, and refreshed CI results.

A critical pickFrom bug — the Lemire-style variant collapsed ~98% of its draws onto allowed[0] — was silently making every constrained field (shard, tenant) effectively constant, breaking the load-balancing use case. An entropy-poisoning bug in genStructuredGenoID — structured field writes clobbered the CSPRNG bytes that downstream fields drew as their randomness — compounded the distribution collapse. Both fixed and pinned by new INV-11.

Two new benchmarks: the rejection-cost sweep (bench-rejection) validates the O(k) vs (1/d)^k complexity claim empirically (48 cells, flat 1.4–3.2 µs/ID vs 2.8×10¹⁴ trials/ID); the DB index-locality benchmark (bench-db) measures 8 PK types in bun:sqlite (500k × 3 runs), reproducing the 2.7× v4→v7 result and showing GenoID's shardfirst layout answers partition queries with 0 index bytes vs 24.5% insert tax + ~10% storage. An IEEE-format paper draft (Sections I–III) and fresh CI benchmark numbers across 7 environments complete the release.

Highlights

🐛 Bug fixes

• pickFrom bias (INV-11) — replaced Lemire-style debiasing with rejection debiasing (byte-range discard + modulo). The old picker collapsed ~98% of draws onto allowed[0] because a 256-entry byte range does not divide evenly by small n, and the incremental-frac arithmetic amplified the remainder. Fixed: discard the top 256 % n values and retry (rare — 1 retry in 256/n draws). INV-11 asserts every allowed value lands within ±50% of its expected share.
• Entropy poisoning in structured gen — applyStructuredFields wrote allowed-field values (e.g. shard at byte 0) directly into parent buffers A/B, then later fields drew their "randomness" from the same buffer — reading the previously-written field value instead of CSPRNG bytes. Fixed by snapshotting _rngA/_rngB before writes; downstream fields now draw from the unmodified CSPRNG copy.

🧪 New experiments

• Rejection-cost sweep (scripts/bench-rejection.ts) — 48 cells (k=1..6 × 8 density levels). GenoID cost flat at 1.4–3.2 µs/ID (O(k), independent of density — actually decreases as density falls). Rejection detonates as (1/d)^k: k=6, d≈0.004 → 2.81×10¹⁴ trials/ID. Measured rejection trials match the analytical model where both are measurable, validating the §III bound. Output: results/rejection-sweep.{json,csv}.
• DB index-locality benchmark (scripts/bench-db.ts) — zero-install bun:sqlite, 8 PK types, clustered + secondary modes (InnoDB-like + Postgres-like), 500k rows × 3 runs. uuid_v4→v7 = 2.7× (reproduces ULID/Shopify). GenoID-structured matches time-ordered peers (402k rows/s). Shardfirst layout: partition-queryable from PK with 0 index bytes, 0 insert tax vs v7's 24.5% insert-throughput tax + ~10% storage for an equivalent secondary index. Output: results/db-sqlite.json.

📄 Paper

• IEEE-format draft (GenoID_IEEE_paper.md) — Sections I–III covering introduction, design (declarative layout, field-boundary crossover, constraint-guided repair), and formal analysis (complexity bound, entropy-preservation proof).

⚡ CI refresh

• Consolidated 7-environment benchmark table refreshed with fresh CI run numbers.

Breaking Changes

• None.

Upgrade Guide

• Rebuild with bun run build.
• No import changes or API deprecations — the pickFrom fix is internal and output-preserving (all entries remain valid v8 UUIDs with constrained fields correctly populated).

[1.19.0] - 2026-07-23

Summary

Embedded-portability APIs: injectable CSPRNG, configurable pool sizes, lean hex footprint. GenoID now runs on microcontroller-class hosts (ESP8266/ESP32, MicroPython) without Web Crypto. Three new configurators (configureRandom, configurePools, configureFootprint) adapt memory and entropy sources with zero output change — every ID is byte-identical across all settings (pinned by INV-10). A research-invariant suite (INV-0–INV-10) protects every load-bearing paper claim as an executable tripwire with parallel worker-pool generation. Benchmark infra gains a JIT warmup pass and Welch t-test p-value + Cohen's d vs v4-native baseline.

Highlights

🆕 Embedded-portability configurators

• configureRandom(fn) — inject a platform CSPRNG where Web Crypto is absent. Import never eagerly draws entropy, so the module loads on a no-Web-Crypto host.
• configurePools({ simplePoolSize, structuredPoolSize }) — shrink generation pools to trade batch size for RAM (default 256/1024; ESP8266-class budget: 16/8).
• configureFootprint("lean") — format from the 256-entry hex table instead of the default lazily-built 65536-entry word table, saving ~131k interned strings.
• HEX16/HEX16_VIEW → HEX8: 131k strings → 256 strings at import (~2KB heap).
• Lazy word table built on first use; freed via configureFootprint("lean").

🧪 Research-invariant suite

• scripts/research-invariants.test.ts: INV-0–INV-10 pins v8 conformance, 0 constraint violations, counter ordering, repair idempotence, collision-freedom, monobit entropy, round-trip exactness, API guard rejection, goal-preservation under injected RNG (INV-9), and lean/fast footprint identity (INV-10).
• Parallel worker pool across os.availableParallelism() cores. GENOID_FAST=1 for quick local runs.

⚡ Benchmark infra

• benchRepeated gains a warmupTrials parameter — the first pass discards JIT compilation noise.
• CI bench output includes Welch t-test p-value and Cohen's d vs v4-native baseline.
• CI table refreshed with fresh numbers: genoid-structured now 0.82–1.66M/s across 7 envs (was 0.66–1.15M/s).

📝 Docs

• README: new "Constrained / embedded hosts" section with usage examples.
• Benchmark stats and regression guard sections.

Breaking Changes

• None. All additions are backward-compatible; existing imports and API surface unchanged.

Upgrade Guide

• Rebuild with bun run build.
• No import changes or API deprecations.

[1.18.1] - 2026-07-23

Summary

Byte-level write plan for genStructuredGenoID — +59% throughput on Apple A18 Pro, +69% on Windows Bun. The hot-path field-write loop (setFieldBytes) was replaced with a precomputed byte-level write plan that reduces 48-bit timestamp writes from 48 bit ops to 6 byte ops. Hex string conversion in the pool refill was aligned with the base GA pool pattern (Uint16Array + HEX16_VIEW), and the pool size increased from 256→1024 to amortize getRandomValues on slower-URNG platforms (Raspberry Pi).

GenoID-structured now beats pg-uuid-v8 and ulid-v8 on every platform in the CI matrix (7 enviro...

genoid 1.20.1

[1.20.1] - 2026-07-26

Summary

Fix compiled-path distribution bias: Hamming-nearest LUT replaced with modulo pickFrom for allowed-set fields. Gate compiled path on default CSPRNG so custom RNGs work.

🐛 Bug fixes

• Compiled-path allowed-set distribution (INV-11) — genLayoutSource used Hamming-nearest LUT repair for allowed-constrained fields (shard, node, process), producing Voronoï-biased output. Replaced with modulo-based pickFrom to match the uniform distribution of the pooled interpreted path. interpretRawLayout updated to match. 106/106 tests pass, INV-11 threshold satisfied.
• Custom CSPRNG bypass — genStructuredGenoID used the compiled path regardless of configureRandom(), silently ignoring the custom RNG when the compiled path used globalThis.crypto. Now gated on _fillRandom === _webCryptoFill; falls through to pooled path when a custom CSPRNG is active.

🔧 Internal

• Removed dead Hamming-LUT precomputation code from genLayoutSource and fieldMeta.

genoid 1.20.0

[1.20.0] - 2026-07-24

Summary

Bug fixes (pickFrom bias, entropy poisoning), two new benchmark experiments (rejection-cost sweep, DB index-locality), IEEE paper draft, and refreshed CI results.

A critical pickFrom bug — the Lemire-style variant collapsed ~98% of its draws onto allowed[0] — was silently making every constrained field (shard, tenant) effectively constant, breaking the load-balancing use case. An entropy-poisoning bug in genStructuredGenoID — structured field writes clobbered the CSPRNG bytes that downstream fields drew as their randomness — compounded the distribution collapse. Both fixed and pinned by new INV-11.

Two new benchmarks: the rejection-cost sweep (bench-rejection) validates the O(k) vs (1/d)^k complexity claim empirically (48 cells, flat 1.4-3.2 µs/ID vs 2.8e14 trials/ID); the DB index-locality benchmark (bench-db) measures 8 PK types in bun:sqlite (500k x 3 runs), reproducing the 2.7x v4->v7 result and showing GenoID's shardfirst layout answers partition queries with 0 index bytes vs 24.5% insert tax + ~10% storage. An IEEE-format paper draft (Sections I-III) and fresh CI benchmark numbers across 7 environments complete the release.

Highlights

Bug fixes

• pickFrom bias (INV-11) — replaced Lemire-style debiasing with rejection debiasing (byte-range discard + modulo). The old picker collapsed ~98% of draws onto allowed[0] because a 256-entry byte range does not divide evenly by small n, and the incremental-frac arithmetic amplified the remainder. Fixed: discard the top 256 % n values and retry (rare — 1 retry in 256/n draws). INV-11 asserts every allowed value lands within +/-50% of its expected share.
• Entropy poisoning in structured gen — applyStructuredFields wrote allowed-field values (e.g. shard at byte 0) directly into parent buffers A/B, then later fields drew their "randomness" from the same buffer — reading the previously-written field value instead of CSPRNG bytes. Fixed by snapshotting _rngA/_rngB before writes; downstream fields now draw from the unmodified CSPRNG copy.

New experiments

• Rejection-cost sweep (scripts/bench-rejection.ts) — 48 cells (k=1..6 x 8 density levels). GenoID cost flat at 1.4-3.2 us/ID (O(k), independent of density). Rejection detonates as (1/d)^k: k=6, d~0.004 -> 2.81e14 trials/ID.
• DB index-locality benchmark (scripts/bench-db.ts) — zero-install bun:sqlite, 8 PK types, clustered + secondary modes. uuid_v4->v7 = 2.7x. Shardfirst: partition-queryable from PK with 0 index bytes, 0 insert tax vs v7's 24.5% insert tax + ~10% storage.

Paper

• IEEE-format draft (GenoID_IEEE_paper.md) — Sections I-III covering introduction, design (declarative layout, field-boundary crossover, constraint-guided repair), and formal analysis.

CI refresh

• Consolidated 7-environment benchmark table refreshed with fresh CI run numbers.

Breaking Changes

• None.

genoid 1.19.0

Summary

Embedded-portability APIs: injectable CSPRNG, configurable pool sizes, lean hex footprint. GenoID now runs on microcontroller-class hosts (ESP8266/ESP32, MicroPython) without Web Crypto. Three new configurators (configureRandom, configurePools, configureFootprint) adapt memory and entropy sources with zero output change.

Highlights

• configureRandom(fn): inject platform CSPRNG where Web Crypto absent
• configurePools: tune simple/structured pool sizes for RAM budgeting
• configureFootprint('lean'): 256-entry hex table vs 65k-word table
• Research-invariant suite (INV-0–INV-10): every paper claim pinned as executable tripwire
• Benchmark warmup pass + Welch p / Cohen's d in CI output
• No breaking changes

genoid 1.18.1

Summary

Byte-level write plan for genStructuredGenoID — +59% throughput on Apple A18 Pro, +69% on Windows Bun. The hot-path field-write loop was replaced with a precomputed byte-level write plan that reduces 48-bit timestamp writes from 48 bit ops to 6 byte ops. Pool size increased from 256→1024 to amortize getRandomValues on slower-URNG platforms (Raspberry Pi).

GenoID-structured now beats pg-uuid-v8 and ulid-v8 on every platform in the CI matrix (7 environments).

Highlights

• genStructuredGenoID throughput across CI: 0.66–1.15M ops/sec (was 0.42–0.78M), +57–69% depending on platform
• Byte-level setFieldBytes replacement eliminates per-bit loops for all structured fields
• Pool size 256→1024: 4x fewer getRandomValues syscalls
• README table updated with new consolidated CI results
• No public API changed

genoid 1.18.0

[1.18.0] - 2026-07-20

Summary

Extend the CI matrix to cover the structured-generation contribution and refresh published results. The 7-environment benchmark now includes genoid-structured (dbkey layout) in the speed table, and collision-checks the two previously-untested baselines ulid and ksuid (both PASS, 0 collisions at 1M). snowflake is intentionally excluded from the collision gate — it is a 64-bit time+sequence ID (12-bit sequence that wraps within a millisecond), so tight-loop 1M generation collides by design, not as a defect; it remains in the speed benchmark. README.md §6 refreshed with the latest consolidated numbers; AGENTS.md restructured to the official agents.md/ format with the /i-have-adhd discipline. No public API changed since 1.17.0.

Highlights

🧪 CI / results

• genoid-structured (dbkey) added to the 7-env speed table — ~0.54–0.78M ops/s across runtimes/OSes.
• Collision gate extended: ulid + ksuid now PASS (0 collisions at 1M); total 9 collision-tested generators × 7 envs = 63/63 PASS.
• snowflake excluded from the collision gate with a documented rationale (sequence-based, not entropy-based).

📝 Docs

• README.md §6 baseline table refreshed with latest CI numbers + genoid-structured row (NIST 15/15).
• AGENTS.md restructured to official agents.md/ sections while keeping the /i-have-adhd lead-with-action / numbered-gates / visible-wins structure.

Breaking Changes

• None.

Upgrade Guide

• Drop-in minor. No API or layout changes.

Known Issues

• None.

Dependencies Updated

• None.

genoid 1.17.1

Summary

Fix an entropy regression in structured-field generation. The pool-reuse performance change in 1.17.0 left structuredValue drawing a single byte per field, silently capping any structured field wider than 8 bits at 256 values. The 16-bit EVENTSOURCING.stream field collapsed to 0–255. Fields now draw width-matched entropy, restoring the full declared keyspace. No public API changed.

Highlights

🐛 Bug fix

• structuredValue now uses drawValue (multi-byte accumulation) and pickFrom (unbiased allowed-set pick) so node/process/shard fields wider than 8 bits keep their full entropy.
• Added a regression test asserting wide fields span their full declared range (guards against any future single-byte cap).

Breaking Changes

• None.

Upgrade Guide

• Drop-in patch. No API or layout changes.

Known Issues

• None.

Dependencies Updated

• None.

genoid 1.17.0

[1.17.0] - 2026-07-20

Summary

Ship the P1/P2 experiment sources that 1.16.0 missed. The 1.16.0 npm publish was README-only and omitted scripts/bench-pg-uuid-v8.ts, scripts/export-rank-scan.ts, and docs/literature-review.md. This release publishes the full local state so the evidence scripts are actually distributed.

Highlights

📦 Packaging fix

• scripts/bench-pg-uuid-v8.ts (P1 head-to-head vs pg_uuid_v8) now shipped.
• scripts/export-rank-scan.ts + dist/rank-scan.csv (P2 NIST draw-size scan) now shipped.
• docs/literature-review.md (C1/C2 refutable claims) now shipped.

Breaking Changes

• None.

Upgrade Guide

• No action required.

Known Issues

• None.