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

# Tasks: unify-rng-across-packages

## 1. `@suaveplan/crypto-core` — migrate Rng alias

- [ ] 1.1 Locate local `Rng` declaration: `packages/crypto/crypto-core/src/primitives/random-bytes/random-bytes.ts` line 12 (`type Rng = ByteSource`).
- [ ] 1.2 Confirm structural compatibility — `ByteSource = (n: number) => Uint8Array` is **not** structurally compatible with canonical `Rng`; see design.md compatibility table for rationale.
- [ ] 1.3 Remove `type Rng = ByteSource` alias; keep `ByteSource` under its real name.
- [ ] 1.4 Add deprecated re-export: `export type { Rng } from "@suaveplan/types";` with prose comment ("Backwards-compatibility alias for `@suaveplan/types` `Rng` — prefer the canonical import; this re-export will be removed in the follow-up `remove-deprecated-rng-aliases` change.").
- [ ] 1.5 Verify `@suaveplan/types` is in `dependencies` (it already is per `MANIFEST.md` dep graph).
- [ ] 1.6 Update sibling `random-bytes.md` API reference: drop `Rng` from the local symbols list; document the back-compat re-export under "Implementation Notes".
- [ ] 1.7 Update barrel re-exports if `Rng` is named in `packages/crypto/crypto-core/src/primitives/random-bytes/index.ts` or `src/primitives/index.ts` or `src/index.ts` — keep the name routed through the new deprecated forwarder.
- [ ] 1.8 `bunx turbo typecheck --filter=@suaveplan/crypto-core` — green.
- [ ] 1.9 `bunx turbo test --filter=@suaveplan/crypto-core` — green, zero assertion edits.
- [ ] 1.10 `bunx turbo test:coverage --filter=@suaveplan/crypto-core` — 100/100/100/100 preserved.

## 2. `@suaveplan/crypto` — update forwarder

- [ ] 2.1 Locate `Rng` re-export in `packages/crypto/crypto/src/index.ts`.
- [ ] 2.2 Confirm it forwards from `@suaveplan/crypto-core`; no further changes needed beyond confirming the canonical type flows through.
- [ ] 2.3 If `Rng` is mentioned in `packages/crypto/crypto/src/index.md` or any sibling doc, update to reference `@suaveplan/types` as the canonical home.
- [ ] 2.4 `bunx turbo typecheck --filter=@suaveplan/crypto` — green.
- [ ] 2.5 `bunx turbo test --filter=@suaveplan/crypto` — green.

## 3. `@suaveplan/testing` — migrate Rng interface

- [ ] 3.1 Locate local `Rng` declaration: `packages/testing/testing/src/context/context.ts` line 45 (`interface Rng { nextUint32(): number; nextFloat(): number }`).
- [ ] 3.2 Confirm structural compatibility — required members are an exact match for canonical `Rng`; canonical adds two OPTIONAL members which existing `cryptoRng` / `seededRng` implementations may omit.
- [ ] 3.3 Add `"@suaveplan/types": "workspace:^"` to `packages/testing/testing/package.json` `dependencies` (rule 8 exception: testing-infrastructure may depend on `@suaveplan/types` for types-only consumption — verify byte-size test still passes since `@suaveplan/types` emits zero-runtime stubs).
- [ ] 3.4 Replace `interface Rng { ... }` with `import type { Rng } from "@suaveplan/types"; export type { Rng };` plus prose comment marking the local re-export as a backwards-compatibility alias.
- [ ] 3.5 Confirm `cryptoRng: Rng = { ... }` and `seededRng(seed): Rng` still typecheck against canonical `Rng` (they should — they provide only the required members).
- [ ] 3.6 Update `packages/testing/testing/src/factories/factory/factory.ts` import — `import { cryptoRng, type Rng } from "../../context/context.js"` continues to work via the re-export, so no edit required unless the import path is changed for clarity.
- [ ] 3.7 Update sibling `context.md` API reference: note that `Rng` is now a re-export of the canonical `@suaveplan/types` `Rng`; remove the local interface from "API Reference"; cross-link to `@suaveplan/types`.
- [ ] 3.8 Update sibling `factory.md` if it mentions the local `Rng` source.
- [ ] 3.9 Verify rule 8 byte-size guard still passes (`@suaveplan/types` emits zero runtime).
- [ ] 3.10 `bunx turbo typecheck --filter=@suaveplan/testing` — green.
- [ ] 3.11 `bunx turbo test --filter=@suaveplan/testing` — green, zero assertion edits.
- [ ] 3.12 `bunx turbo test:coverage --filter=@suaveplan/testing` — 100/100/100/100 preserved.
- [ ] 3.13 Dependent sweep: `bunx turbo test --filter=...@suaveplan/testing` — every consumer of `factory.ts` / `context.ts` `Rng` continues to typecheck and pass.

## 4. Spec delta

- [ ] 4.1 Author `specs/types/spec.md` delta with `## MODIFIED Requirements` block on `Rng has optional bounded operations` adding the single-source-of-truth clause.
- [ ] 4.2 Carry `**Verified by:**` on the modified requirement.

## 5. Repo-wide verification gate

- [ ] 5.1 `grep -rln "interface Rng\b\|type Rng = " packages/ --include="*.ts" | grep -v "/dist/\|/node_modules/"` returns exactly:
  - `packages/core/types/src/rng.ts` (canonical)
  - the three deprecated re-export forwarders introduced above
- [ ] 5.2 No other genesis package declares a local `Rng` interface.
- [ ] 5.3 `bunx turbo lint typecheck --filter=...` (full repo) — green.

## 6. Doc-drift + behaviour-change propagation

- [ ] 6.1 Per CLAUDE.md §4a: every `.ts` edited has its sibling `.md` updated in the same change set.
- [ ] 6.2 Per CLAUDE.md §13a: add the `## Migration` note to proposal.md (already authored).
- [ ] 6.3 Repo-wide consumer scan: `grep -rln "from ['\"]@suaveplan/\(crypto-core\|crypto\|testing\)['\"]" packages/ | xargs grep -l "Rng\b"` — every hit either continues to compile via the deprecated forwarder OR is updated to the canonical import in this change set.

## 7. Fold + archive

- [ ] 7.1 Fold `specs/types/spec.md` delta into `openspec/specs/types/spec.md`.
- [ ] 7.2 Move `openspec/changes/unify-rng-across-packages/` → `openspec/archive/<yyyy-mm-dd>-unify-rng-across-packages/`.
- [ ] 7.3 Refresh `MANIFEST.md` / `MISSING.yml` / `STATUS.md` / `SUMMARY.md` per CLAUDE.md §13b (no package add/remove here, but dep-graph edge added: `@suaveplan/testing → @suaveplan/types`).
- [ ] 7.4 Open the follow-up `remove-deprecated-rng-aliases` change to track removal of the three forwarders after one release cycle.