suaveplan/openspec/changes/_superseded-narrow-deferrals-2026-05-17/unify-rng-across-packages/proposal.md

# OpenSpec Change: unify-rng-across-packages

- **Change ID**: unify-rng-across-packages
- **Package**: `@suaveplan/types` (canonical) + downstream consumers
- **Design**: ./design.md
- **Spec delta**: ./specs/types/spec.md
- **Status**: PROPOSED
- **Date**: 2026-05-17

## Why

The 2026-04-27 `types-contract-tightening` change widened the canonical `Rng`
interface in `@suaveplan/types` (adding optional `nextBytes` and
`nextIntInRange` members) and explicitly **deferred** migration of the
packages that were redefining `Rng`-shaped interfaces locally
(`crypto-core`, `cache`, `idempotency`). That deferral has lapsed: every
fresh package author who needs randomness still has to choose between
importing the canonical `Rng` or hand-rolling a local one, and the existing
local redefinitions silently fork the contract.

This change closes the loop. It migrates every genesis package with a local
`Rng` type to consume the canonical `Rng` from `@suaveplan/types`, leaving
deprecated aliases in place for one release cycle so consumers can update at
their own pace.

## What changes

For each affected genesis package, the source files that currently declare a
local `Rng` interface are migrated to:

1. Import the canonical `Rng` from `@suaveplan/types`.
2. Re-export the canonical `Rng` from the original module path under the
   original name, with a "Backwards-compatibility alias for `@suaveplan/types`
   `Rng`" prose comment (per CLAUDE.md §2 — no `@deprecated` JSDoc).
3. Add `@suaveplan/types` as a `workspace:^` dependency where missing.
4. Re-run `bunx turbo typecheck` and `bunx turbo test` to confirm zero
   runtime / behavioural change.

The spec delta is a `## MODIFIED Requirements` block on the existing
`Rng has optional bounded operations` requirement in `openspec/specs/types/`
that adds an explicit single-source-of-truth clause: no other `@suaveplan/*`
package may declare its own `Rng` interface; downstream packages that need a
narrower or wider random-source shape MUST either consume `Rng` directly or
define a sub-interface that `extends` it.

## Impact

### Affected dependents

Run `bunx turbo ls --filter=...@suaveplan/types` to enumerate. Packages that
currently declare a local `Rng` type (surveyed via
`grep -rln "interface Rng\b\|type Rng = " packages/`) are:

- `@suaveplan/crypto-core` — [x] tests run / [x] docs reviewed / [ ] no action needed
  (declares `type Rng = ByteSource` as a back-compat alias in
  `src/primitives/random-bytes/random-bytes.ts`)
- `@suaveplan/crypto` — [x] tests run / [x] docs reviewed / [ ] no action needed
  (re-exports the alias from `crypto-core` via `src/index.ts`)
- `@suaveplan/testing` — [x] tests run / [x] docs reviewed / [ ] no action needed
  (declares a full `interface Rng` in `src/context/context.ts`; consumed by
  `src/factories/factory/factory.ts`)

For every other dependent of `@suaveplan/types`: [x] no action needed —
they already consume `Rng` from `@suaveplan/types` and are unaffected by
this change.

### Source mapping (local Rng → canonical)

| Package | Local file | Local symbol | Action |
|---|---|---|---|
| `@suaveplan/crypto-core` | `src/primitives/random-bytes/random-bytes.ts` | `type Rng = ByteSource` | Replace with deprecated re-export of canonical `Rng`; keep `ByteSource` (distinct contract). |
| `@suaveplan/crypto` | `src/index.ts` | re-export `Rng` from `crypto-core` | Update re-export to point at canonical alias. |
| `@suaveplan/testing` | `src/context/context.ts` | `interface Rng { nextUint32; nextFloat }` | Import canonical `Rng`; re-export as deprecated alias. Add `@suaveplan/types` workspace dep (rule 8 exception). |

### Verification

- **Verified by:** `bunx turbo typecheck test --filter=@suaveplan/crypto-core`
- **Verified by:** `bunx turbo typecheck test --filter=@suaveplan/crypto`
- **Verified by:** `bunx turbo typecheck test --filter=@suaveplan/testing`
- **Verified by:** `bunx turbo typecheck test --filter=...@suaveplan/testing`
  (dependents of `testing` consume `Rng` transitively via `factory.ts`)
- **Verified by:** repo-wide grep `grep -rln "interface Rng\b\|type Rng = " packages/ --include="*.ts" | grep -v "/dist/\|/node_modules/"` returns only the canonical declaration in `packages/core/types/src/rng.ts` plus the deprecated alias forwarders the change introduces.

## Out of scope

- **Widening the canonical `Rng`.** If a consumer needs additional members
  (e.g. `nextBigInt`, streaming bytes), open a separate
  `types-contract-tightening`-style change against `@suaveplan/types`.
- **Removing the deprecated aliases.** Follow-up change (one release cycle
  after this one archives) removes the `Rng` re-exports from `crypto-core`,
  `crypto`, and `testing`. Tracked as a TODO in this proposal's design.md.
- **Upstream-only packages (`cache`, `idempotency` upstream RNG redefinitions).**
  The 2026-04-27 deferral text named `cache` and `idempotency` as RNG-shape
  redefiners. On genesis, `@suaveplan/idempotency` and the three cache
  packages (`@suaveplan/cache`, `cache-storage`, `cache-redis`) do **not**
  currently reference `Rng` at all (verified by grep). When those packages
  port the upstream randomness features, the migration must consume the
  canonical `Rng` directly — there is no local type to migrate here yet.
- **Runtime behaviour changes.** This change is type-only; the test suite
  must remain green pre- and post-migration with zero assertion edits.

## Migration

- **Old**: consumers importing `Rng` from `@suaveplan/crypto-core`,
  `@suaveplan/crypto`, or `@suaveplan/testing`.
- **New**: import `Rng` from `@suaveplan/types`.
- **Search command**: `grep -rln "from ['\"]@suaveplan/\(crypto-core\|crypto\|testing\)['\"]" packages/ | xargs grep -l "Rng\b"`
- **Recommended replacement**: `import type { Rng } from "@suaveplan/types"`.
  The deprecated alias re-exports remain functional for one release cycle.