Skip to content

feat(actor): report contained lifecycle failures to spawn-time error reporters - #90

Merged
cevr merged 5 commits into
mainfrom
fix/actor-error-reporting
Oct 7, 2026
Merged

cevr merged 5 commits into
mainfrom
fix/actor-error-reporting

Conversation

@cevr

@cevr cevr commented Oct 7, 2026

Copy link
Copy Markdown
Owner

Report contained actor failures to the Effect ErrorReporters that are registered where the actor is spawned.

What changes

  • Generations: each runtime generation reports its full defect cause once, when it closes. The cause covers transition, spawn, task, background and cleanup failures.
  • Restarts: supervised restarts report each generation. A restart step that fails before a new generation exists reports with phase restart. This covers a restart recovery that dies, a restart schedule that dies, and a schedule defect that settles together with exhaustion. An exhausted schedule alone does not report.
  • Cold start: a cold-start recovery failure reports with phase recovery. This covers a resolver that throws and a stop that interrupts the start.
  • Other paths: a final output defect reports, child actors report, and cluster entities report through their allocation-time reporters.
  • Pinned reporters: the reporters captured at spawn are pinned. A later start or stop caller cannot replace them.
  • No report: normal stops, final states and pure interruption send no report.
  • Overlap: the changeset and docs/persistence-and-supervision.md describe where a report can repeat at a caller boundary or in a parent handler, and how ErrorReporter.make dedup applies.

Validation

  • typecheck, lint, fmt:check, test (425 pass), build and examples:gate pass. Lefthook passes on every commit.
  • New regression tests fail on 0.28.0. Mutation runs prove the interrupt-only guard and the onError placement.
  • An independent review ran two rounds. This head includes the round-2 repairs for a cold recovery that throws synchronously, for Pull.filterDone schedule classification, and for the parent re-raise docs.

Changeset: minor (0.29.0). No exported type changes.

cevr added 5 commits October 7, 2026 14:16
…reporters

Actor generations close with a Defect exit that awaitExit returns as a value,
so no Effect boundary reported those failures. Inspection only logged the
pretty cause.

- Report each generation's combined defect cause once at closeGeneration,
  before the exit is published, with the reporters captured at allocation.
- Pin CurrentErrorReporters in the actor service context so restarted
  generations and later start/stop callers keep the spawn-time reporters.
- Report final output defects at terminal completion and restart-step
  failures in the supervisor. Leave re-raised stop and child failures to
  their owners.
- Annotate reports with actor id, generation and defect phase, skip pure
  interruption, and isolate reporter defects from lifecycle settlement.
…reporters

The changeset states that cluster entity runtimes report generation defects
through the reporters in their allocation context. Cover that claim with an
entity whose background effect dies under EntityMachine.layer.
… a generation

A cold-start lifecycle.recovery.resolve defect left a Defect exit with no
report, in start and when stop interrupted the start. Report it with phase
"recovery" through Effect.onError, so a stop that interrupts the start
cannot skip the report. The restart-step hook moves to Effect.onError for
the same reason.

A restart schedule that died was read as exhaustion. Tell a halted pull
apart from a schedule defect and report the defect with phase "restart".

Add raw-recorder tests for pure interruption from a handler and from a
restart recovery; the old negative test covered only routine stops.
…pinned handler reporters

Name the cold-start recovery report and the schedule-defect report. State
that a caller boundary can report a failure again unless the reporter is
built with ErrorReporter.make and the defect is an object. State that
handler code runs with the spawn-time reporters. Note reporter dispatch
order and that entity reports name one allocation.
… settle with exhaustion

Wrap the cold-start recovery resolver in Effect.suspend so a synchronous
throw becomes a reported defect. Classify a failed restart schedule with
Pull.filterDone so a defect that settles together with exhaustion still
reports. Document that a parent handler which re-raises a child failure
reports it again as its own defect.
@cevr
cevr merged commit 3b26534 into main Oct 7, 2026
1 check passed
@cevr
cevr deleted the fix/actor-error-reporting branch October 7, 2026 16:06
@github-actions github-actions Bot mentioned this pull request Oct 7, 2026
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