Skip to content

fix: Draw recordings whose calls return out of order - #2434

Open
dividedmind wants to merge 2 commits into
mainfrom
fix/out-of-order-returns
Open

dividedmind wants to merge 2 commits into
mainfrom
fix/out-of-order-returns

Conversation

@dividedmind

Copy link
Copy Markdown
Collaborator

Fixes #2430. Fixes the crash in #2399 (see below for the part it doesn't cover).

Problem

appmap-node can write recordings where a call's return arrives after a later call has started but before that call returns (call A, call B, return A, return B). This happens when a call and its return are emitted in different async contexts.

EventStack in @appland/models popped the top of the stack on every return, whichever call it belonged to:

Changes

@appland/models

  • A call's parent is the call that was open when it was made. A return removes its call from the stack wherever it is, not just from the top.
  • If returns came out of order, the stack's events are written back out depth first (each call, then the calls made during it, then its return), so everything that walks the flat event list as a stack (call tree, sequence diagrams, normalize()) still sees them nested.
  • A call that never returned, made inside one that did, gets a return placed before its caller's, with an unused id. Calls made after it remain nested under it, the same as in a recording with returns in order.
  • A second return for a call that already returned is discarded (previously it popped an unrelated call).
  • Recordings whose returns arrive in order build exactly as before: same order, same parents and children.

@appland/appmap (CLI)

  • appmap sequence-diagram handles errors per file: it prints Failed to draw <file>: <message>, continues with the rest of the batch, and exits with status 1.

Tests

Not in this PR

Assisted-by: Claude:claude-opus-5-5

A call's return can arrive after a later call has started but before
that call returns; appmap-node writes such recordings when the call
and return of an event land in different async contexts. EventStack
popped the top of the stack on every return regardless of which call
returned. When the returning call sat right below the top, it became
its own parent and building the AppMap threw "failed trying to compute
event stack", so `appmap sequence-diagram` crashed (#2430). Deeper in
the stack, the tree came out silently wrong; filtering such an AppMap
then rebuilt it into the throwing case, which is how `appmap archive`
dropped diagrams for files the stand-alone command could draw (#2399).

Make a call's parent the call that was open when it was made, and on a
return remove the returning call from the stack wherever it is. When
that happened out of order, write the stack's events back out depth
first, so consumers that walk the flat event list as a stack (the call
tree, sequence diagrams, normalize) still see them nested. A call that
never returned, made inside one that did, gets a return placed before
its caller's, with an id no other event uses, so the list stays
nested. Calls made after it are still nested under it, as they would
be in a recording with returns in order. A second return of a call
that already returned is discarded.

Recordings whose returns arrive in order build exactly as before.

The sequence-diagram command tests now start from an empty output
directory, so a test can't pass by reading a diagram an earlier run
wrote.

Assisted-by: Claude:claude-opus-5-5
`appmap sequence-diagram` awaited each file in turn with no error
handling, so the first file that couldn't be drawn rejected the whole
command with an unhandled error, and the files after it were skipped.

Report the failure per file (`Failed to draw <file>: <message>`),
carry on with the rest of the batch, and exit with status 1.

Assisted-by: Claude:claude-opus-5-5
@dividedmind
dividedmind requested review from kgilpin and a balanced review from Copilot November 16, 2026 17:17
@dividedmind dividedmind self-assigned this Nov 16, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues are reported for the async event-ordering and sequence-diagram changes.

No open issues 🎉

What changed in this PR

Fixes handling of out-of-order returns in async recordings so AppMap models and sequence diagrams can be built without crashing or producing incorrect call trees. Addresses #2430 and the event-stack crash described in #2399; archive/compare reporting remains out of scope.

Changes:

  • Preserve call-time parent relationships, reorder affected events into nested order, and handle missing or duplicate returns.
  • Continue drawing remaining files after a sequence-diagram failure and exit with status 1.
  • Add regression coverage and clear test output directories to prevent stale diagrams from masking failures.
File Description
packages/​models/​tests/​unit/​appMapBuilder.spec.js Tests out-of-order returns, nesting, synthetic IDs, and duplicate returns.
packages/​models/​src/​appMapBuilder/​eventStack.js Tracks call-time parents and repairs event ordering.
packages/​models/​src/​appMapBuilder/​eventSorter.js Uses ordered stack events and allocates synthetic return IDs.
packages/​cli/​tests/​unit/​sequenceDiagram.spec.ts Tests async recordings and batch failures; clears prior output.
packages/​cli/​tests/​unit/​fixtures/​javascript/​out_of_order_return.appmap.json Adds a minimal async-return regression recording.
packages/​cli/​src/​cmds/​sequenceDiagramHandler.ts Reports per-file failures, continues the batch, and sets a failing exit status.

Review effort: Balanced

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

2 participants