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.