Diagnostics and Warnings

Probability Director includes a bounded, per-UGameInstance diagnostics system for inspecting runtime behavior without turning diagnostics into gameplay state, a replay log, or a source of reconstructable RNG secrets.

This document explains:

What Probability Director records.
What it intentionally does not record.
How diagnostic retention works.
How Record Successful Operations behaves.
The generated-value contract.
How the Probability Director Runtime Inspector presents retained data.
What each V1 warning means.
How to investigate warnings without misinterpreting expected test or boundary behavior.
The security and public-safety boundaries of the diagnostics system.

Important

Diagnostics are observational. Gameplay must never depend on diagnostic history, warning history, Recent Decisions, Inspector state, or diagnostic retention order.

1. Purpose

Probability Director diagnostics are designed to answer developer questions such as:

Was the requested stream available?
Was an operation Sequential or Keyed?
Did a Sequential operation actually consume random bytes?
What status did an operation return?
What bounded scalar result was returned for supported operations?
What sanitized Decision Key metadata was associated with a Keyed operation?
Did persistence operations repeatedly fail or conflict?
Is a caller repeatedly issuing invalid requests?
Which retained operations belong to a selected runtime stream?

Diagnostics are not intended to:

Reconstruct a Secure stream.
Expose a Fixed Seed through diagnostics.
Expose ChaCha state.
Provide a numeric Sequential cursor.
Replace gameplay logging.
Store arbitrary payloads.
Store UObject references.
Preserve an unbounded history.
Become a save/replay format.

2. High-Level Model

Diagnostics are owned by the current Probability Director subsystem and therefore belong to one UGameInstance.

GameInstance
    |
    +--> UProbabilityDirectorSubsystem
            |
            +--> Diagnostics Configuration
            |
            +--> Bounded Event History
            |
            +--> Bounded Warning History
            |
            +--> Probability Director Runtime Inspector projection

A second GameInstance has a separate diagnostics configuration and separate retained history.

There is no process-global diagnostic buffer.

This matters in PIE and multi-PIE: always inspect the intended Runtime Context.

3. Default Configuration

Probability Director uses different default diagnostic capacities by build context.

Build context	Diagnostics enabled	Event capacity	Warning capacity	Warning threshold
Development / Editor	Yes	256	128	3
Test	Yes	512	256	3
Shipping	No	0	0	3

Additional default:

Record Successful Operations: false

Event and warning storage remain bounded.

When the configured capacity is reached, the bounded history continues operating according to its retention policy rather than growing without limit.

4. What a Diagnostic Event May Retain

Supported operations may retain approved, copied, pointer-free metadata from the actual runtime result.

Depending on the operation, an event may include:

Operation category.
Stream identity.
Decision mode.
Result/status metadata.
Semantic Sequential state effect.
Sanitized Decision Key metadata for Keyed operations.
Persistence metadata where applicable.
An approved generated scalar output for supported operations.

The stored representation is deliberately smaller and safer than the original runtime operation.

5. What Diagnostics Never Retain

The diagnostics contract intentionally excludes sensitive, reconstructable, unbounded, or gameplay-owned data.

Diagnostics do not retain:

Raw RNG bytes.
Secure roots.
Secure seed material.
Entropy bytes.
Generator keys.
Generator nonces.
Raw ChaCha state.
Numeric ChaCha byte position.
Numeric Sequential cursor/position.
State fingerprints.
Trace relations.
Persistence secrets.
Arbitrary gameplay payloads.
Gameplay UObject references.
Arbitrary structs.
Arbitrary arrays or maps.
Dice trace trees.
Weighted payload objects.
Unbounded text.
A hidden replayable copy of RNG state.

A retained random result is a historical output value, not the state required to reproduce the generator.

6. Sanitized Decision Key Metadata

Keyed diagnostic events may retain a bounded copied projection of the authored FProbabilityDecisionKey.

The retained fields are:

Namespace
bounded StableSubjectId
Decision
Occurrence
KeySchemaVersion

The copied projection is diagnostic metadata only.

It is not a registry of every possible Decision Key.

It does not expose secret RNG derivation material.

If StableSubjectId exceeds the diagnostic limit, the retained value is bounded and the Inspector marks the value as truncated.

7. Sequential State Effect

Random-operation events record whether the operation actually affected the Sequential generator.

The semantic state is one of:

State	Meaning
Advanced	The operation actually consumed raw bytes from the Sequential generator.
Did Not Advance	The operation did not consume raw bytes from the Sequential generator.
Not Applicable	The event is not a Sequential random operation, such as lifecycle or persistence activity.

This field answers:

“Did this operation actually advance the Sequential generator?”

It does not answer:

“What numeric position is the stream at?”

No numeric call position, byte position, generator cursor, lifetime decision counter, or equivalent reconstructable state is exposed.

8. Deterministic Contract Metadata

The copied diagnostics snapshot exposes sanitized deterministic-contract identity metadata used by developer tooling and the Probability Director Runtime Inspector.

Approved metadata includes:

Production ChaCha20 IETF generator identity.
SecureRandomBytes entropy-source identity.
Seed derivation version.
Keyed derivation version.
Canonical encoding version.
Decision Key schema version where it belongs to a Keyed decision.

These identifiers are compatibility and implementation-contract metadata.

They do not expose:

A Fixed Seed.
A Secure root.
Entropy bytes.
Generator state.
A key.
A nonce.
A numeric generator position.

Knowing the algorithm/version does not make a Secure run reproducible.

9. Recording Successful Operations

Successful-operation capture is intentionally disabled by default.

The Probability Director Runtime Controls tool exposes a live diagnostic setting named:

Record Successful Operations

This control changes only:

FProbabilityDiagnosticsConfig::bRecordSuccessfulOperations

through the existing diagnostics configuration API:

GetDiagnosticsConfiguration()
SetDiagnosticsConfiguration(...)

All other diagnostics configuration fields are preserved.

9.1 What enabling it does

When enabled:

Future successful supported random operations may be retained.
Retained successful events use the existing bounded Event history.
Supported events can appear in:
- Events
- the selected Stream’s Recent Decisions
Approved scalar generated results can be retained when the operation participates in the generated-value contract.

9.2 What enabling it does not do

Enabling Record Successful Operations does not:

Backfill older operations.
Change a random result.
Advance a stream.
Re-seed a stream.
Change deterministic sequences.
Change persistence.
Change gameplay behavior.
Increase the configured event capacity.
Create a second history buffer.
Expose RNG secrets.

9.3 What disabling it does

Disabling the option:

Stops future successful operations from being captured.
Does not delete successful events already retained.
Does not alter retained warning/failure history.
Does not modify stream state.

9.4 Runtime-context ownership

The setting belongs to the selected UGameInstance / Runtime Context.

It is not a process-global preference.

If two PIE GameInstances are active:

PIE GameInstance A
    Record Successful Operations = true

PIE GameInstance B
    Record Successful Operations = false

those configurations remain independent.

9.5 When the Controls setting is unavailable

The control is disabled when:

The selected Runtime Context is unavailable or diagnostics are disabled.
The originating PIE context has ended.
No live Runtime Context exists.
Diagnostics capture itself is disabled.

Frozen views display the captured value from the frozen snapshot without querying or mutating live Runtime state.

9.6 No Blueprint or Project Settings control

There is no:

Project Settings default for this Runtime Controls setting.
Blueprint node for toggling this control.

This is an intentional developer-diagnostics boundary.

C++ diagnostics configuration remains available through the existing subsystem configuration API.

10. Generated Value Contract

A retained event has an explicit generated-value state:

None
or
Present

A legitimate value of 0 or false is therefore distinct from “no generated value.”

10.1 Supported V1 scalar types

The V1 generated-value contract supports:

Type	Support
Boolean	Supported
Signed Integer	Supported
Unsigned Integer	Supported
Floating Point	Supported
Identifier	Reserved for individually audited bounded outputs
Bounded Text	Reserved for individually audited bounded outputs

Boolean and integer values are exact.

Floating-point values are stored numerically and formatted using a shortest invariant representation appropriate for identifying the captured result.

10.2 Unsupported arbitrary values

Diagnostics do not stringify arbitrary runtime objects merely to make them displayable.

The generated-value contract does not serialize:

arbitrary FString
UObject
arrays
maps
arbitrary structs
Dice traces
weighted payloads
gameplay objects
arbitrary Name-generation data

If an operation family has not been individually approved for bounded generated-value capture, it remains unavailable instead of being converted into a string.

11. Generated Values by Operation Family

Sequential Random

Supported Sequential random operations retain the exact scalar integer/float result copied at the Runtime return boundary.

The diagnostic record does not retain raw generator bytes.

Keyed Random

Supported Keyed random operations retain the exact scalar result copied at the Runtime return boundary.

Keyed diagnostic metadata may additionally include the sanitized Decision Key projection.

Numeric Dice

Numeric Dice diagnostics capture only an approved canonical scalar result such as:

Final numeric outcome.
Final Success Count.

They do not retain a complete Dice execution trace.

Supported Scalar Distributions

Supported scalar Distribution sampling may retain the returned scalar sample.

The diagnostic value is the returned result, not the random source material used to obtain it.

Failed Operations

A failure with no returned output has:

Generated Value = None

Failure status remains separate from generated output.

Name Generation, Coin, and Weighted Payloads

No current:

Name-generation operation
Coin operation
weighted-payload operation

participates in the generated-value event contract described here.

Those families remain unavailable rather than being stringified into diagnostic text.

12. Generated Value Lifetime

Generated values live inside the existing bounded diagnostic event.

They follow the same lifecycle as that event:

Operation occurs
    |
    +--> Event retained
            |
            +--> Generated Value retained with Event
                    |
                    +--> Event eventually evicted by bounded history
                            |
                            +--> Generated Value disappears with it

There is no second generated-value history.

Enabling successful-operation recording does not backfill earlier values.

13. Probability Director Runtime Inspector Presentation

The Probability Director Runtime Inspector projects retained diagnostic information for developer inspection.

Relevant areas include:

Streams
Selected Stream Details
Recent Decisions
Events
Warnings

The Inspector is a presentation over Runtime diagnostics, not a second source of truth.

14. Recent Decisions

Recent Decisions is a convenience projection of the existing bounded per-GameInstance event history for the currently selected Stream.

It does not allocate or maintain a separate unbounded decision history.

Recent Decisions excludes lifecycle operations such as:

CreateStream
RemoveStream

and focuses on retained decision-oriented activity.

Depending on the operation, it may show:

Sequential or Keyed mode.
Sanitized Decision Key fields.
Occurrence.
Status/result metadata.
Semantic Sequential state effect.
Approved generated value.

15. Status vs. Generated Value

The Inspector presents operation status and generated output separately.

For example:

Status: Success
Generated Value: 17

or:

Status: Failure - <domain/code>
Generated Value: N/A

This avoids ambiguous displays where a legitimate 0 or false could be mistaken for failure.

16. Events Table Status

The Inspector’s Events table presents a readable Status:

Success

or:

Failure - <domain/code>

The raw diagnostic result/domain/code remains available through:

Tooltips.
Details.
Structured exports.

The readable Status is a developer-facing presentation layer; it does not discard the underlying diagnostic classification.

17. Persistence Generation

Persistence Generation is shown as:

N/A

when no persisted stream-state generation applies.

This includes Ephemeral streams.

Persistence Generation is not:

A random-call count.
Sequential position.
Generator byte position.
Lifecycle epoch.
Keyed decision count.

Do not use it to infer RNG progression.

18. Freeze View

When the Probability Director Runtime Inspector is frozen:

The Inspector uses the captured pointer-free snapshot.
Live Runtime mutation controls are disabled.
Recorded generated values are limited to values captured before Freeze.
Frozen exports contain only the frozen snapshot.
The Inspector does not query destroyed PIE state to reconstruct missing information.

Freeze does not stop the game or stop Probability Director itself. It freezes the Inspector’s view.

19. Diagnostics Export Contract

Structured Recent Decisions exports preserve status and generated values without exposing secret state.

CSV

Recent Decisions CSV includes:

GeneratedValueType
GeneratedValue
GeneratedValueTruncated

along with the other approved structured fields.

Markdown

Markdown presents:

Status.
Generated Value.

as separate concepts.

JSON

JSON uses either:

a typed generatedValue object

or:

"generatedValue": null

No generated output is inferred when the value is absent.

Frozen export behavior

Frozen exports contain only data present in the captured frozen view.

They do not:

Query live Runtime for newer decisions.
Backfill earlier uncaptured successful operations.
Reconstruct Secure stream state.

20. Export Security Boundary

Captured outputs and structured exports never expose:

Fixed Seed.
Secure root.
Secure seed.
Entropy bytes.
Generator key.
Generator nonce.
Raw generator state.
ChaCha byte position.
Numeric Stream cursor.
State fingerprint.
Arbitrary gameplay payload.
Persistence secret state.

A historical generated result is not sufficient to reconstruct any of those internal values.

21. Warning System

Probability Director warnings are bounded developer diagnostics for repeated or suspicious runtime conditions.

Warnings do not automatically mean:

Probability Director is defective.
The RNG is unhealthy.
A save is corrupted.
A caller must retry.
A Shipping build should continue diagnostics capture.

Several warnings are intentionally triggerable by:

Negative tests.
Boundary tests.
Compatibility tests.
Stress tests.
Explicit developer tooling.

The correct response is to interpret the warning in context.

22. Warning Quick Reference

Warning	Typical meaning	First thing to check
`RepeatedInvalidStreamRequest`	Repeated use of unavailable/invalid Stream ID	Stream creation and exact Stream ID
`RepeatedInvalidDecisionKey`	Repeated rejection of Decision Key/schema input	Key construction, Occurrence, schema
`RepeatedNumericalFailure`	Numerical operation repeatedly could not produce a valid representable result	Input parameters and native status
`RepeatedSamplingLimitFailure`	Bounded work/sampling limit repeatedly reached	Extreme/rejection-heavy inputs
`StaleRotateOnSaveCommit`	Prepared RotateOnSave transaction became stale	Save overlap/order/ownership
`RepeatedRestoreRejection`	Persistence restore repeatedly rejected	Campaign, stream config, compatibility
`RepeatedBeginNewCampaign`	New-campaign reset called repeatedly	Reset call sites and intended ownership

The V1 warning threshold defaults to 3.

23. RepeatedInvalidStreamRequest

Meaning

Gameplay or tooling repeatedly requested a stream that Probability Director could not accept as a valid available stream.

Common causes

The stream was never created.
The caller used the wrong StreamId.
The semantic ID differs by spelling/case/identity from the created stream.
The call occurred before stream creation.
A stream was removed while another system still expected it.
A test intentionally probes invalid Stream IDs.

Legitimate occurrences

This warning may be expected during:

Negative tests.
Validation probes.
Explicit invalid-input testing.

Investigation

Confirm the stream is created in the intended GameInstance.
Confirm the exact semantic Stream ID.
Confirm the operation happens after creation.
Check whether another system removes the stream.
Verify the caller is using the intended Runtime Context in PIE.
Inspect the returned native status rather than relying on the warning alone.

Example

BeginPlay
    -> Random operation on Combat.Damage
    -> Create Stream Combat.Damage

This ordering is wrong.

Prefer:

BeginPlay
    -> Create Stream Combat.Damage
    -> Random operation on Combat.Damage

24. RepeatedInvalidDecisionKey

Meaning

Keyed operations repeatedly rejected the supplied DecisionKey or its schema input.

Common causes

Invalid Decision Key construction.
Unsupported schema version.
Missing or invalid semantic fields.
Incorrect Keyed setup.
Caller forgot that Occurrence is explicit.
A negative test intentionally submits bad keys.

Legitimate occurrences

Expected during:

Invalid-input tests.
Schema rejection tests.
Compatibility tests.

Investigation

Use the approved Decision Key construction path.
Verify Namespace.
Verify stable StableSubjectId.
Verify Decision.
Verify explicit Occurrence.
Confirm the expected schema version.
Confirm the target stream is configured for Keyed decisions.
Inspect the operation’s native status/result.

Only the bounded sanitized metadata projection is retained by diagnostics.

25. RepeatedNumericalFailure

Meaning

A numerical operation repeatedly failed to produce a valid representable result.

Common causes

Extreme distribution parameters.
Nonfinite inputs.
Representability limits.
Numerically unstable/extreme domains.
Inputs that are individually representable but produce an invalid derived result.

Legitimate occurrences

Expected during:

Numerical boundary tests.
Stress tests.
Explicit failure-path tests.

Investigation

Check all authored/runtime parameters.
Reject nonfinite input before building gameplay behavior around it.
Inspect the native status/result.
Compare the request to documented numerical limits.
Determine whether the failure is expected at that boundary.
Do not silently clamp the request unless your gameplay layer explicitly owns that policy.

26. RepeatedSamplingLimitFailure

Meaning

A bounded sampling or bounded-work operation repeatedly reached its configured/native safety limit.

Common causes

Extreme distributions.
Rejection-heavy sampling conditions.
Very difficult tail regions.
Inputs that force unusually high work.
Intentional stress testing.

Important behavior

This warning does not imply:

Probability Director will automatically retry until success.

Automatic retry is not implied.

Investigation

Inspect the parameters.
Check the operation’s native limit/status.
Determine whether the requested configuration is practical for runtime use.
Check whether caller code is blindly repeating the same failed request.
Review whether the failure is expected in a stress/boundary test.

27. StaleRotateOnSaveCommit

Meaning

A prepared RotateOnSave persistence transaction became stale before commit.

Common causes

Two save operations overlap.
Another persistence generation commits first.
Generation state changed after preparation.
Save ownership/order is not coordinated.

Legitimate occurrences

Expected during:

Save-conflict tests.
Explicit stale-transaction tests.

Investigation

Identify which system owns save sequencing.
Check for overlapping save requests.
Check whether another generation committed first.
Verify Prepare/Commit ordering.
Confirm stale transactions are rejected rather than forcibly committed.
Review asynchronous save orchestration in the host save system.

Do not expose persistence secret payloads while debugging.

28. RepeatedRestoreRejection

Meaning

Probability Director repeatedly rejected persistence restore attempts.

Common causes

Campaign mismatch.
Persistent Stream mismatch.
Malformed save data.
Incompatible save data.
Unexpected persistent-stream configuration.
A compatibility test intentionally loads invalid data.

Legitimate occurrences

Expected during:

Compatibility tests.
Corruption/malformed-data tests.
Campaign mismatch tests.
Persistent-stream mismatch tests.

Investigation

Confirm the expected campaign identity.
Confirm the expected persistent streams exist/configure correctly.
Verify save-data compatibility.
Check the native restore status.
Determine whether the load belongs to the current campaign/runtime context.
Do not log or expose secret persistence payload contents.

29. RepeatedBeginNewCampaign

Meaning

BeginNewCampaign or equivalent campaign-reset behavior was invoked repeatedly.

Common causes

Tooling repeatedly triggers reset.
A caller loop invokes reset every frame/tick.
More than one gameplay owner thinks it owns campaign initialization.
Tests intentionally exercise repeated reset behavior.

Legitimate occurrences

Expected during:

Explicit reset tests.
Campaign lifecycle tests.

Investigation

Search all reset call sites.
Identify the authoritative owner of campaign reset.
Verify reset is event-driven rather than tick-driven.
Check whether multiple initialization systems call it.
Confirm repeated universe/identity resets are intentional.

30. Warning Investigation Workflow

Use this workflow when a warning appears unexpectedly.

Warning appears
    |
    +--> 1. Identify Runtime Context
    |
    +--> 2. Identify Stream ID if applicable
    |
    +--> 3. Read readable Status
    |
    +--> 4. Inspect raw domain/code in Details or structured export
    |
    +--> 5. Check whether this is a test/boundary condition
    |
    +--> 6. Check caller ordering/configuration
    |
    +--> 7. Check documented native limits
    |
    +--> 8. Fix caller/configuration OR classify as expected

Do not start by increasing capacities or retry counts.

A warning should first be understood.

31. Diagnostics Configuration from C++

The Inspector’s successful-operation toggle is implemented by reading the existing configuration, changing only bRecordSuccessfulOperations, and writing the complete configuration back.

Conceptual pattern:

FProbabilityDiagnosticsConfig Config =
    ProbabilitySubsystem->GetDiagnosticsConfiguration();

Config.bRecordSuccessfulOperations = true;

ProbabilitySubsystem->SetDiagnosticsConfiguration(Config);

When changing diagnostics configuration programmatically:

Preserve unrelated fields unless you intentionally mean to change them.
Respect build-specific defaults.
Do not assume Shipping diagnostics are enabled.
Do not make gameplay logic depend on whether capture is enabled.

This API is for diagnostics configuration. It is not a random-stream configuration API.

32. Blueprint Guidance

There is no Blueprint node for Record Successful Operations.

Blueprint gameplay should consume normal Probability Director result/status APIs.

Use the Probability Director Runtime Inspector during development when you need to inspect retained events.

Do not add Blueprint diagnostic toggles in project utility graphs as a substitute for the intended Inspector/C++ boundary.

33. Shipping Behavior

Shipping defaults are intentionally restrictive:

Diagnostics Enabled: false
Event Capacity:       0
Warning Capacity:     0
Warning Threshold:    3

This means the normal Shipping configuration does not retain diagnostic histories.

Do not write Shipping gameplay that depends on:

Events.
Warnings.
Recent Decisions.
Inspector-only metadata.
Generated diagnostic values.

The application must behave correctly when diagnostics retention is completely unavailable.

34. Retention and Memory Expectations

Diagnostic storage is bounded.

Default Development/Editor limits:

Events:   256
Warnings: 128

Default Test limits:

Events:   512
Warnings: 256

The design intentionally favors a recent bounded diagnostic window rather than an ever-growing historical log.

If you need long-term application telemetry, build that as a separate application-owned system.

Do not increase Probability Director diagnostic capacity merely to create a gameplay analytics database.

35. Diagnostics vs. Gameplay Logging

Use Probability Director diagnostics for Probability Director behavior.

Use your game’s logging/telemetry for gameplay meaning.

Example:

Probability Director can tell you:

Stream: Loot.DropTable
Mode: Sequential
Status: Success
Generated Value: 2
Sequential Effect: Advanced

Your game should tell you:

Generated Value 2 mapped to ItemTier::Epic for Chest 42.

Probability Director intentionally does not retain arbitrary gameplay payloads to bridge those two meanings.

36. Diagnostics vs. RNG Health

Diagnostic events show what runtime operations occurred.

They do not by themselves determine whether an RNG is statistically “good” or “bad.”

A short retained event history is not enough to make a general randomness-quality judgment.

Use statistical analysis tooling for questions about:

Distribution fit.
Correlation.
Streakiness.
Cumulative deviation.
Long-run empirical behavior.

Do not interpret a visually unusual short sequence in Recent Decisions as proof of RNG failure.

37. Diagnostics vs. Persistence

Diagnostics and persistence have different responsibilities.

Diagnostics	Persistence
Developer observation	Runtime continuity
Bounded history	Persisted state contract
May be disabled	Used when the game chooses to save state
Sanitized	May contain internal deterministic state
Not a replay source	Restores approved runtime state
Not gameplay authority	Participates in gameplay continuity

Never attempt to restore Probability Director state from exported diagnostics.

38. Diagnostics vs. Replay

A list of generated values is not a supported Probability Director replay format.

Reasons include:

Event retention is bounded.
Successful operations may not have been recorded.
Some operation families do not expose generated values.
Failed operations may have no value.
Diagnostic metadata intentionally omits reconstructable state.
Shipping diagnostics may be disabled.

If a game requires gameplay replay, implement replay at the gameplay/application layer with an explicit replay contract.

39. Public Safety Boundaries

The diagnostics API and Inspector intentionally expose enough information to debug behavior while withholding sensitive implementation state.

Approved public/sanitized concepts include:

Stream identity.
Seed-source identity.
Decision mode.
Persistence policy.
Algorithm identity/version.
Derivation/encoding version identities.
Sanitized Decision Key metadata.
Semantic Sequential effect.
Status/result classification.
Approved bounded generated scalar outputs.

Intentionally excluded concepts include:

Fixed Seed in diagnostic history.
Secure root.
Secure seed.
Entropy bytes.
Raw RNG bytes.
Key.
Nonce.
Raw generator state.
Byte position.
Numeric Sequential cursor.
State fingerprint.
Arbitrary persistence state.
Gameplay UObject references.
Arbitrary gameplay payloads.

40. Common Misinterpretations

“Advanced means this was random call number 27.”

Incorrect.

Advanced only means the operation consumed Sequential generator bytes.

“Did Not Advance means the result was cached.”

Not necessarily.

It means the operation did not consume raw bytes from the Sequential generator. Interpret the operation’s actual status/details separately.

“Persistence Generation is the RNG generation counter.”

Incorrect.

Persistence Generation belongs to persisted stream-state generation and is shown as N/A when it does not apply.

“Generated Value 0 means no value.”

Incorrect.

The generated-value state explicitly distinguishes None from a legitimate scalar zero.

“If I enable successful-operation recording, earlier rolls will appear.”

Incorrect.

There is no backfill.

Only future qualifying operations can be retained.

“Freeze View freezes the RNG.”

Incorrect.

Freeze View freezes the Inspector snapshot, not gameplay Runtime.

“Recent Decisions is an unlimited roll history.”

Incorrect.

It is a projection of the existing bounded Event history.

“Secure metadata in the Inspector means I can reproduce the Secure stream.”

Incorrect.

Algorithm/entropy-source/version identities do not expose secret root or generator material.

41. Troubleshooting Examples

Example A — No successful rolls appear in Recent Decisions

Check:

Is diagnostics capture enabled?
Is Record Successful Operations enabled for the selected live Runtime Context?
Did the operation occur after enabling it?
Is the selected Stream correct?
Has the bounded event history already evicted the older operation?
Does that operation family participate in generated-value capture?

Example B — Record Successful Operations is unavailable

Check whether:

The selected Runtime Context is unavailable or diagnostics are disabled.
PIE has ended.
No live Runtime Context is selected.
Diagnostics capture is disabled.

This is expected behavior in those states.

Example C — Keyed Recent Decision shows truncated Stable Subject ID

The authored StableSubjectId exceeded the diagnostic retention limit.

The Runtime operation and the sanitized diagnostic projection are separate concepts.

The Inspector indicates diagnostic truncation rather than pretending the retained text is complete.

Example D — Sequential operation says Did Not Advance

Inspect:

The operation status.
Raw diagnostic result.
Operation type.
Whether validation rejected before random consumption.
Whether the operation mathematically required random consumption.

Do not infer a numeric stream position.

Example E — RepeatedSamplingLimitFailure appears in a stress test

This can be legitimate.

Confirm:

The test intentionally exercises an extreme/rejection-heavy condition.
The returned native status is the expected bounded failure.
Production caller code is not blindly repeating the same request forever.

Do not “fix” the warning by making the sampling loop unbounded.

42. Test and Automation Guidance

Warnings generated by explicit negative/boundary tests are not automatically product defects.

When reviewing automated output:

Identify the exact warning type.
Identify the test that generated it.
Determine whether the test intentionally exercised the warning condition.
Verify the expected status/result contract.
Ensure no new unexplained warning has appeared.

A warning should be classified, not simply ignored.

43. Deferred Warning Families

The following categories are intentionally deferred and are not V1 release defects:

Timing/rate warnings.
Dice-pressure warnings.

Do not document them as active V1 warning contracts until they are implemented and approved.

44. Recommended Developer Workflow

During development:

1. Start PIE
2. Open Probability Director Runtime Inspector
3. Select the intended Runtime Context
4. Select the intended Stream
5. Open Runtime Controls and enable Record Successful Operations if needed
6. Reproduce the behavior
7. Review Recent Decisions
8. Review Events
9. Review Warnings
10. Inspect Details/raw domain codes where necessary
11. Freeze View when you need a stable snapshot
12. Export the sanitized snapshot when needed

Then diagnose the gameplay caller using:

Stream lifecycle.
Decision mode.
Decision Key construction.
Operation status.
Numerical/sampling limits.
Persistence ownership/order.

Do not use the Inspector to mutate RNG state.

45. API Responsibility Summary

Probability Director diagnostics are responsible for

Bounded diagnostic retention.
Bounded warning retention.
Sanitized event metadata.
Sanitized Decision Key projection.
Semantic Sequential state effect.
Approved generated scalar output capture.
Build-specific diagnostic defaults.
Structured warning categorization.
Pointer-free Inspector snapshots.
Safe structured exports.

The developer/game is responsible for

Correct Stream IDs.
Correct stream lifecycle ordering.
Correct Decision Key construction.
Handling returned failure statuses.
Interpreting warnings in gameplay context.
Deciding whether a warning is expected in a test.
Keeping gameplay independent from diagnostics.
Application-level telemetry.
Gameplay replay.
Save orchestration.
Not exposing sensitive persistence data through external logging.

46. Quick Reference

Development / Editor defaults

Diagnostics: Enabled
Events:      256
Warnings:    128
Threshold:   3
Record Successful Operations: false

Test defaults

Diagnostics: Enabled
Events:      512
Warnings:    256
Threshold:   3
Record Successful Operations: false

Shipping defaults

Diagnostics: Disabled
Events:      0
Warnings:    0
Threshold:   3
Record Successful Operations: false

Sequential effect

Advanced
Did Not Advance
Not Applicable

Retained Decision Key projection

Namespace
StableSubjectId (bounded)
Decision
Occurrence
KeySchemaVersion

Generated scalar types

Boolean
SignedInteger
UnsignedInteger
FloatingPoint

Core rule

Diagnostics may tell you what happened, but they must not expose enough internal state to reconstruct how the Secure generator produced it.

For the surrounding systems, see:

API Overview — subsystem access, stream lifecycle, Sequential/Keyed selection, error handling, and public API boundaries.
Probability Director Runtime Inspector — live Runtime Context selection, Streams, Recent Decisions, Events, Warnings, Freeze View, and exports.
Persistence — campaign identity, stream state, save/restore contracts, and persistence security.
Dice — Dice runtime semantics and supported Dice result contracts.
Distributions and Bias — scalar distribution sampling, numerical status handling, and Bias.
Markov Models and N-Gram Names — Name Model analysis and generation behavior.