@reicek/neataptic-ts 0.1.24 → 0.1.26

package/src/architecture/network/deterministic/README.md

@@ -2,10 +2,6 @@
 
 ## architecture/network/deterministic/network.deterministic.utils.types.ts
 
-### RNGSnapshot
-
-Snapshot payload for RNG state restore flows.
-
 ### NetworkInternals
 
 Internal deterministic network state shape used across deterministic utility modules.
@@ -14,61 +10,66 @@ Internal deterministic network state shape used across deterministic utility mod
 
 Fixed Weyl increment used to advance deterministic PRNG state.
 
+### RNGSnapshot
+
+Snapshot payload for RNG state restore flows.
+
 ### UINT32_NORMALIZER
 
 Divisor used to normalize uint32 PRNG output into [0, 1).
 
 ## architecture/network/deterministic/network.deterministic.utils.ts
 
-### setSeed
+### network.deterministic.utils
+
+Default export bundle for convenient named imports.
+
+### getRandomFn
 
 ```ts
-setSeed(
-  seed: number,
-): void
+getRandomFn(): (() => number) | undefined
 ```
 
-Sets deterministic randomness for a network by installing a seed-backed RNG.
+Returns the active deterministic RNG function currently attached to the network.
 
 Overview:
-- Use this before training, mutation, or stochastic operations when you need repeatable runs.
-- The same seed and operation order produce the same random sequence and reproducible outcomes.
-- This method delegates to setup utilities so behavior stays centralized across deterministic APIs.
+- Use this when tooling or diagnostics need direct RNG access.
+- Returning the function allows advanced integration code to inspect or reuse the random stream.
+- For most persistence workflows, prefer `snapshotRNG` and `getRNGState` over direct function plumbing.
 
 Parameters:
-- `this` - - Bound network instance whose RNG state is being initialized.
-- `seed` - - Seed value used to derive deterministic RNG state (low 32 bits are applied).
+- `this` - - Bound network instance queried for active RNG function.
 
-Returns: Nothing.
+Returns: Active RNG function, or `undefined` when deterministic RNG is not initialized.
 
 Example:
 
 ```ts
-network.setSeed(42);
+const randomFn = network.getRandomFn();
 ```
 
-### snapshotRNG
+### getRNGState
 
 ```ts
-snapshotRNG(): RNGSnapshot
+getRNGState(): number | undefined
 ```
 
-Captures the current deterministic RNG lifecycle state as a portable snapshot.
+Returns the current deterministic RNG numeric state, when available.
 
 Overview:
-- Use this before temporary experiments, branching simulations, or stateful debug sessions.
-- The snapshot preserves enough information to resume from the same deterministic point later.
-- This is useful when comparing alternate algorithm branches from an identical random timeline.
+- Use this for lightweight checkpointing when full lifecycle snapshots are unnecessary.
+- The value can be persisted and later reapplied through `setRNGState`.
+- This is commonly used by tests that assert deterministic continuity across operations.
 
 Parameters:
-- `this` - - Bound network instance whose RNG lifecycle state is captured.
+- `this` - - Bound network instance queried for deterministic RNG numeric state.
 
-Returns: Snapshot containing deterministic progress metadata and RNG state payload.
+Returns: Numeric RNG state value, or `undefined` when no deterministic state exists yet.
 
 Example:
 
 ```ts
-const snapshot = network.snapshotRNG();
+const state = network.getRNGState();
 ```
 
 ### restoreRNG
@@ -98,121 +99,134 @@ Example:
 network.restoreRNG(restoredRandomFunction);
 ```
 
-### getRNGState
+### RNGSnapshot
+
+Snapshot payload for RNG state restore flows.
+
+### setRNGState
 
 ```ts
-getRNGState(): number | undefined
+setRNGState(
+  state: number,
+): void
 ```
 
-Returns the current deterministic RNG numeric state, when available.
+Applies a deterministic RNG numeric state to continue from a known checkpoint.
 
 Overview:
-- Use this for lightweight checkpointing when full lifecycle snapshots are unnecessary.
-- The value can be persisted and later reapplied through `setRNGState`.
-- This is commonly used by tests that assert deterministic continuity across operations.
+- Pair this with `getRNGState` to pause/resume deterministic sequences.
+- Useful for reproducible tests, multi-stage training workflows, and deterministic replay.
+- Delegation keeps the write path consistent with the rest of deterministic state utilities.
 
 Parameters:
-- `this` - - Bound network instance queried for deterministic RNG numeric state.
+- `this` - - Bound network instance receiving deterministic RNG state.
+- `state` - - Numeric RNG state checkpoint to install.
 
-Returns: Numeric RNG state value, or `undefined` when no deterministic state exists yet.
+Returns: Nothing.
 
 Example:
 
 ```ts
-const state = network.getRNGState();
+network.setRNGState(savedState);
 ```
 
-### setRNGState
+### setSeed
 
 ```ts
-setRNGState(
-  state: number,
+setSeed(
+  seed: number,
 ): void
 ```
 
-Applies a deterministic RNG numeric state to continue from a known checkpoint.
+Sets deterministic randomness for a network by installing a seed-backed RNG.
 
 Overview:
-- Pair this with `getRNGState` to pause/resume deterministic sequences.
-- Useful for reproducible tests, multi-stage training workflows, and deterministic replay.
-- Delegation keeps the write path consistent with the rest of deterministic state utilities.
+- Use this before training, mutation, or stochastic operations when you need repeatable runs.
+- The same seed and operation order produce the same random sequence and reproducible outcomes.
+- This method delegates to setup utilities so behavior stays centralized across deterministic APIs.
 
 Parameters:
-- `this` - - Bound network instance receiving deterministic RNG state.
-- `state` - - Numeric RNG state checkpoint to install.
+- `this` - - Bound network instance whose RNG state is being initialized.
+- `seed` - - Seed value used to derive deterministic RNG state (low 32 bits are applied).
 
 Returns: Nothing.
 
 Example:
 
 ```ts
-network.setRNGState(savedState);
+network.setSeed(42);
 ```
 
-### getRandomFn
+### snapshotRNG
 
 ```ts
-getRandomFn(): (() => number) | undefined
+snapshotRNG(): RNGSnapshot
 ```
 
-Returns the active deterministic RNG function currently attached to the network.
+Captures the current deterministic RNG lifecycle state as a portable snapshot.
 
 Overview:
-- Use this when tooling or diagnostics need direct RNG access.
-- Returning the function allows advanced integration code to inspect or reuse the random stream.
-- For most persistence workflows, prefer `snapshotRNG` and `getRNGState` over direct function plumbing.
+- Use this before temporary experiments, branching simulations, or stateful debug sessions.
+- The snapshot preserves enough information to resume from the same deterministic point later.
+- This is useful when comparing alternate algorithm branches from an identical random timeline.
 
 Parameters:
-- `this` - - Bound network instance queried for active RNG function.
+- `this` - - Bound network instance whose RNG lifecycle state is captured.
 
-Returns: Active RNG function, or `undefined` when deterministic RNG is not initialized.
+Returns: Snapshot containing deterministic progress metadata and RNG state payload.
 
 Example:
 
 ```ts
-const randomFn = network.getRandomFn();
+const snapshot = network.snapshotRNG();
 ```
 
-### RNGSnapshot
+## architecture/network/deterministic/network.deterministic.setup.utils.ts
 
-Snapshot payload for RNG state restore flows.
+### advanceStateWithWeylIncrement
 
-### network.deterministic.utils
+```ts
+advanceStateWithWeylIncrement(
+  currentState: number | undefined,
+): number
+```
 
-Default export bundle for convenient named imports.
+Advance state using a fixed Weyl increment with uint32 wraparound.
 
-## architecture/network/deterministic/network.deterministic.setup.utils.ts
+Parameters:
+- `currentState` - - Current state word (possibly undefined).
 
-### setSeed
+Returns: Next unsigned 32-bit state.
+
+### createDeterministicRandomFunction
 
 ```ts
-setSeed(
-  seed: number,
-): void
+createDeterministicRandomFunction(
+  internalState: DeterministicNetworkInternals,
+): () => number
 ```
 
-Seed the internal PRNG and install a deterministic random() implementation on the Network instance.
+Create deterministic PRNG function bound to provided internal state holder.
 
 Parameters:
-- `this` - - Bound Network instance.
-- `seed` - - A finite number; only its lower 32 bits are used.
+- `internalState` - - Runtime network internals used by deterministic RNG pipeline.
 
-Returns: Nothing.
+Returns: PRNG function returning values in [0,1).
 
-### toUint32
+### mixStateWord
 
 ```ts
-toUint32(
-  numericValue: number,
+mixStateWord(
+  stateWord: number,
 ): number
 ```
 
-Convert a numeric value into unsigned 32-bit state.
+Mix state word with xorshift and multiplication steps.
 
 Parameters:
-- `numericValue` - - Numeric value to normalize.
+- `stateWord` - - Unsigned 32-bit state word.
 
-Returns: Unsigned 32-bit representation.
+Returns: Mixed unsigned 32-bit word.
 
 ### setInternalSeedState
 
@@ -248,50 +262,36 @@ Parameters:
 
 Returns: Nothing.
 
-### createDeterministicRandomFunction
-
-```ts
-createDeterministicRandomFunction(
-  internalState: DeterministicNetworkInternals,
-): () => number
-```
-
-Create deterministic PRNG function bound to provided internal state holder.
-
-Parameters:
-- `internalState` - - Runtime network internals used by deterministic RNG pipeline.
-
-Returns: PRNG function returning values in [0,1).
-
-### advanceStateWithWeylIncrement
+### setSeed
 
 ```ts
-advanceStateWithWeylIncrement(
-  currentState: number | undefined,
-): number
+setSeed(
+  seed: number,
+): void
 ```
 
-Advance state using a fixed Weyl increment with uint32 wraparound.
+Seed the internal PRNG and install a deterministic random() implementation on the Network instance.
 
 Parameters:
-- `currentState` - - Current state word (possibly undefined).
+- `this` - - Bound Network instance.
+- `seed` - - A finite number; only its lower 32 bits are used.
 
-Returns: Next unsigned 32-bit state.
+Returns: Nothing.
 
-### mixStateWord
+### toUint32
 
 ```ts
-mixStateWord(
-  stateWord: number,
+toUint32(
+  numericValue: number,
 ): number
 ```
 
-Mix state word with xorshift and multiplication steps.
+Convert a numeric value into unsigned 32-bit state.
 
 Parameters:
-- `stateWord` - - Unsigned 32-bit state word.
+- `numericValue` - - Numeric value to normalize.
 
-Returns: Mixed unsigned 32-bit word.
+Returns: Unsigned 32-bit representation.
 
 ### toUnitInterval
 
@@ -310,62 +310,62 @@ Returns: Unit-interval floating-point value.
 
 ## architecture/network/deterministic/network.deterministic.state.utils.ts
 
-### getRNGState
+### getRandomFn
 
 ```ts
-getRNGState(): number | undefined
+getRandomFn(): (() => number) | undefined
 ```
 
-Get the current internal 32-bit RNG state value.
+Retrieve the active random function reference.
 
 Parameters:
 - `this` - - Bound Network instance.
 
-Returns: Unsigned 32-bit state integer or undefined if generator not yet seeded or was reset.
+Returns: Function producing numbers in [0,1). May be undefined if never seeded.
 
-### setRNGState
+### getRNGState
 
 ```ts
-setRNGState(
-  state: number,
-): void
+getRNGState(): number | undefined
 ```
 
-Explicitly set (override) the internal 32-bit RNG state without changing the generator function.
+Get the current internal 32-bit RNG state value.
 
 Parameters:
 - `this` - - Bound Network instance.
-- `state` - - A finite number (only low 32 bits used). Ignored when non-numeric.
 
-Returns: Nothing.
+Returns: Unsigned 32-bit state integer or undefined if generator not yet seeded or was reset.
 
-### getRandomFn
+### isNumericState
 
 ```ts
-getRandomFn(): (() => number) | undefined
+isNumericState(
+  candidateState: number,
+): boolean
 ```
 
-Retrieve the active random function reference.
+Check whether incoming state is numeric.
 
 Parameters:
-- `this` - - Bound Network instance.
+- `candidateState` - - Candidate state value.
 
-Returns: Function producing numbers in [0,1). May be undefined if never seeded.
+Returns: True when state is numeric.
 
-### isNumericState
+### setRNGState
 
 ```ts
-isNumericState(
-  candidateState: number,
-): boolean
+setRNGState(
+  state: number,
+): void
 ```
 
-Check whether incoming state is numeric.
+Explicitly set (override) the internal 32-bit RNG state without changing the generator function.
 
 Parameters:
-- `candidateState` - - Candidate state value.
+- `this` - - Bound Network instance.
+- `state` - - A finite number (only low 32 bits used). Ignored when non-numeric.
 
-Returns: True when state is numeric.
+Returns: Nothing.
 
 ### toUint32
 
@@ -384,18 +384,20 @@ Returns: Unsigned 32-bit state.
 
 ## architecture/network/deterministic/network.deterministic.lifecycle.utils.ts
 
-### snapshotRNG
+### clearStoredRngState
 
 ```ts
-snapshotRNG(): RNGSnapshot
+clearStoredRngState(
+  internalState: DeterministicNetworkInternals,
+): void
 ```
 
-Capture a snapshot of the RNG state together with the network's training step.
+Clear stored numeric RNG state.
 
 Parameters:
-- `this` - - Bound Network instance.
+- `internalState` - - Runtime network internals used by deterministic RNG pipeline.
 
-Returns: Object containing current training step and 32-bit RNG state.
+Returns: Nothing.
 
 ### restoreRNG
 
@@ -430,17 +432,15 @@ Parameters:
 
 Returns: Nothing.
 
-### clearStoredRngState
+### snapshotRNG
 
 ```ts
-clearStoredRngState(
-  internalState: DeterministicNetworkInternals,
-): void
+snapshotRNG(): RNGSnapshot
 ```
 
-Clear stored numeric RNG state.
+Capture a snapshot of the RNG state together with the network's training step.
 
 Parameters:
-- `internalState` - - Runtime network internals used by deterministic RNG pipeline.
+- `this` - - Bound Network instance.
 
-Returns: Nothing.
+Returns: Object containing current training step and 32-bit RNG state.