You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Add concise fault tolerance documentation to CLAUDE.md and the passes
README covering error accumulation, tryRecord wrapping, and the
distinction between validation vs infrastructure passes. Remove the
detailed planning document now that the work is complete.
Copy file name to clipboardExpand all lines: compiler/CLAUDE.md
+14-15Lines changed: 14 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -229,20 +229,19 @@ Would enable the `enableJsxOutlining` feature and disable the `enableNameAnonymo
229
229
3. Look for `Impure`, `Render`, `Capture` effects on instructions
230
230
4. Check the pass ordering in Pipeline.ts to understand when effects are populated vs validated
231
231
232
-
## Error Handling for Unsupported Features
232
+
## Error Handling and Fault Tolerance
233
233
234
-
When the compiler encounters an unsupported but known pattern, use `CompilerError.throwTodo()` instead of `CompilerError.invariant()`. Todo errors cause graceful bailouts in production; Invariant errors are hard failures indicating unexpected/invalid states.
234
+
The compiler is fault-tolerant: it runs all passes and accumulates errors on the `Environment` rather than throwing on the first error. This lets users see all compilation errors at once.
235
235
236
-
```typescript
237
-
// Unsupported but expected pattern - graceful bailout
238
-
CompilerError.throwTodo({
239
-
reason: `Support [description of unsupported feature]`,
240
-
loc: terminal.loc,
241
-
});
242
-
243
-
// Invariant is for truly unexpected/invalid states - hard failure
244
-
CompilerError.invariant(false, {
245
-
reason: `Unexpected [thing]`,
246
-
loc: terminal.loc,
247
-
});
248
-
```
236
+
**Recording errors** — Passes record errors via `env.recordError(diagnostic)`. Errors are accumulated on `Environment.#errors` and checked at the end of the pipeline via `env.hasErrors()` / `env.aggregateErrors()`.
237
+
238
+
**`tryRecord()` wrapper** — In Pipeline.ts, validation passes are wrapped in `env.tryRecord(() => pass(hir))` which catches thrown `CompilerError`s (non-invariant) and records them. Infrastructure/transformation passes are NOT wrapped in `tryRecord()` because later passes depend on their output being structurally valid.
239
+
240
+
**Error categories:**
241
+
-`CompilerError.throwTodo()` — Unsupported but known pattern. Graceful bailout. Can be caught by `tryRecord()`.
242
+
-`CompilerError.invariant()` — Truly unexpected/invalid state. Always throws immediately, never caught by `tryRecord()`.
0 commit comments