Skip to content

feat(random)!: remove the integer form of the random action - #392

Merged
han4wluc merged 4 commits into
mainfrom
feat/remove-random-integer-action
Nov 20, 2026
Merged

han4wluc merged 4 commits into
mainfrom
feat/remove-random-integer-action

Conversation

@han4wluc

@han4wluc han4wluc commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

Why

A random value is now drawn into a variable by an updateVariable operation with op: random, which runs in list order with the action's other operations, can appear any number of times on a line and does not continue to the next line. That leaves the integer form of the random action as a second, more awkward way to do the same thing: one per line, always after every updateVariable operation, and it continues to the next line by itself.

Removing it gives each action one job: updateVariable changes values, including random ones, and random chooses a path.

Breaking change

A random action with distribution.type: integer or a variableId is no longer accepted.

Before:

random:
  distribution: { type: integer, min: 1, max: 100 }
  variableId: randomNumber

After:

updateVariable:
  id: rollNumber
  operations:
    - variableId: randomNumber
      op: random
      distribution: { type: integer, min: 1, max: 100 }

The operation does not continue to the next line, and its line is an ordinary Back stop. A line or button that relied on the removed action continuing keeps that behaviour with an empty default conditional beside the roll:

conditional:
  branches:
    - actions: {}

What changed

  • The random action accepts only a weighted distribution. The schema refuses the integer form and variableId, and the engine refuses them when the action runs. For the integer form the error names the updateVariable random operation.
  • random is a single entry of the Decision phase, after the form actions and before conditional. The separate State-phase entry for the integer form is gone.
  • sampleRandomDistribution draws only weighted outcomes. Integer sampling stays, used by the updateVariable random operation.
  • The version is bumped to 1.55.0.

Existing data:

  • A project that still holds an integer random action is not migrated. The engine refuses the action when its line runs.
  • A save from an older engine can hold an integer result recorded for a random action. It is dropped when the save is loaded or the project is updated, like any record whose action no longer matches. The save loads with its variables as they were saved. Any rollback that replays the line of the roll, including one Back step from a later line, then runs it without the roll, so the variable has the value it had before that line and later lines and conditionals that read it are replayed with that value. Nothing is drawn again, and the record is not moved to an updateVariable roll that replaced the action.
  • Rolls recorded for updateVariable random operations are unaffected.

Testing

  • spec/RouteEngine.randomActions.test.js: the tests that used the integer form now use weighted outcomes that set a variable, and cover the same behaviour: order before conditional, transactions, line recording and replay through save, load and rollback, a new draw after rolling back past the line, same-line re-entry, nested paths, project updates, malformed and unsupported ledgers.
    • New: the integer form and variableId are refused before anything is drawn.
    • New: a random action nested in a weighted outcome or a conditional branch is replayed from its own record, with the second outcome selected.
    • New: an integer result recorded by an older engine is dropped on load and on a project update, for a project that still has the integer action, one changed to the weighted form and one changed to an updateVariable roll. The saved variables are restored, and a Back step from a later line and a rollback to the line both replay it without the roll and without a draw.
    • New: an updateVariable roll stays on its line by itself, and continues once and is skipped by Back with an empty default conditional beside it.
    • Removed: "drops recorded integers outside a replacement project range", which spec/RouteEngine.updateVariableRandom.test.js covers for the operation.
  • spec/random.test.js: integer sampling is tested through the variable distribution, and the action sampler refuses an integer distribution.
  • spec/projectDataSchema.test.js: the integer distribution rules (required bounds, safe integers, no extra keys) are tested through the updateVariable random operation, and a random action with no distribution or a distribution type other than weighted is refused.
  • spec/actionExecutionOrder.test.js: random is placed after the form actions and before conditional.
  • Each new test was checked to fail when the behaviour it covers is broken.
  • bun run test, bun run lint, bun run check:test-markers and bun run build pass.
  • VT: random/choice-integer-branch now rolls with the updateVariable random operation and still matches its two reference images. robustness/variable-random-line-rollback and robustness/variable-random-choice-branch pass the CI flow locally with 0 mismatched images. All three were run on the final source.

The random action now only runs the actions of one weighted outcome.
A random value is drawn into a variable by an updateVariable operation
with op: random, which runs in list order with the action's other
operations and does not continue to the next line.

A random action with an integer distribution or a variableId is
refused by the schema and at runtime. An integer result that an older
engine recorded for a random action is dropped when a save is loaded
or the project is updated, like any record whose action no longer
matches.

random is one entry of the Decision phase, before conditional.

Bumps the version to 1.54.0.
1.54.0 was released from main without this change, so the removal ships as
1.55.0 and the docs name that version.
…aves

- Replay of a random action nested in a weighted outcome or a conditional
  branch is asserted from its own record, with the second outcome selected.
- The integer distribution rules of the schema are tested through the
  updateVariable random operation, which is their only user now.
- The schema test refuses a random action with no distribution or with a
  distribution type other than weighted.
- The order test places random after the form actions.
- The old-save test also covers a project changed to an updateVariable
  roll, a Back step from a later line and a project update.
- An updateVariable roll continues to the next line only with a
  conditional beside it.

The docs say which rollbacks replay a line without a dropped roll, how to
keep the continuation of the removed action, and when an integer roll
draws no word or fails.
@han4wluc
han4wluc merged commit 87ac45f into main Nov 20, 2026
50 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant