Skip to content

feat(routing): name the lines of an immediate routing cycle on its error - #390

Merged
han4wluc merged 4 commits into
mainfrom
feat/routing-cycle-lines
Nov 19, 2026
Merged

han4wluc merged 4 commits into
mainfrom
feat/routing-cycle-lines

Conversation

@han4wluc

@han4wluc han4wluc commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

What

When a story routes in an immediate cycle, the engine stops after 1,000 synchronous effect batches and throws an error with code: "routing_cycle" and pointer, the one line it was on at that moment. A cycle usually involves more than one line, and the line it happens to stop on is not necessarily the one an author needs to change.

The error now also has cycle: an array of { sectionId, lineId } for the lines of the cycle. It starts with the line the story stopped on and lists each other line once, in the order the story first reached it after that line.

  • The cycle is the block of lines the story kept repeating, so lines that only led into it are not included. A line that routes to itself gives a cycle of that one line.
  • It lists the lines the story actually entered, whichever action moved it there: sectionTransition, jumpToLine, a conditional branch, or a conditional's continuation to the next line.
  • When the route varied between turns, so that no block repeats, cycle is the story's last trip from the line it stopped on back to that line.
  • When the story never entered a line twice, it ran out of budget on a long chain of lines rather than in a cycle, and cycle is empty.

code, pointer and the message are unchanged, so existing hosts are not affected.

How

While draining pending effects, the engine records each line the story enters (a batch that queues a line's actions). When the budget runs out, selectRoutingCycle in src/routingCycle.js finds the smallest block of entered lines that repeats at the end of that record, falling back to the last return to the final line. The record holds at most about 1,000 small entries and lives only for the drain; the search runs only when the error is raised.

Version

Bumps the version to 1.54.0.

Testing

Unit tests for selectRoutingCycle (spec/routingCycle.test.js), on records of entered lines:

  • nothing entered, one line, and a chain that never comes back (empty cycle)
  • a line entering itself, with and without a lead-in
  • two- and three-line cycles, stopped on each position, with lead-in lines
  • a line passed twice in a turn, and a line entering itself inside a longer cycle
  • a single full turn, one and a half turns, a route that varies between turns, and a route that changed and then settled
  • lines that share an ID across sections
  • a 500-line cycle (exactly two turns), a 700-line cycle (less than two turns), and 1,000 entries of one line
  • the result is a copy of the record

Integration tests through the engine (spec/integration/projectRobustness.integration.test.js):

  • the existing self-routing cases (jumpToLine, sectionTransition, conditional) now assert a one-line cycle, and the existing two-section reset case asserts both lines
  • a two-section cycle and a cycle across two scenes
  • a three-line cycle entered from a line outside it, mixing jumpToLine, sectionTransition and a conditional branch
  • a cycle through a line a conditional continues past
  • a variable-driven cycle that passes one line twice in a turn
  • a cycle started by an action from a waiting line, rather than at initialization
  • a second cycle after recovering from a first lists only its own lines
  • a 1,200-line chain that never repeats reports an empty cycle
  • changing the returned cycle does not affect the engine

bun run test: 105 files, 2,639 tests pass. bun run lint, bun run format:changed and bun run check:test-markers pass.

The routing cycle error named only the line the story was on when the
effect budget ran out. It now also has `cycle`: the lines of the story's
most recent turn around the cycle, starting with that line and in the
order the story reached them, so a host can show every line involved.

The existing `code`, `pointer` and message are unchanged.

Bumps the version to 1.53.0.
The cycle was taken as the story's last trip from the line it stopped on
back to that line. A story that passes one line twice in a turn, going on
to a different line each time, got only half of its cycle.

The engine now records every line the story enters, including a line
entering itself, and reports the block of lines that keeps repeating, with
each line listed once. A route that never repeats a block still falls back
to the last trip, and a chain of lines that outruns the budget without
entering a line twice reports an empty cycle instead of a one-line one.
@han4wluc
han4wluc merged commit b0bfc07 into main Nov 19, 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