@@ -37,10 +37,37 @@ export function* settle(segment: ErrorSegment): Operation<ErrorSegment> {
3737 return segment ;
3838}
3939
40+ /**
41+ * The failure a contextual ErrorSegment was translated from.
42+ *
43+ * The segment is what the document says; the failure is the structural account
44+ * of how expansion got there, and a component that recovered from failed content
45+ * and then failed on its own terms is the only place that account survives. The
46+ * two have to arrive together: settlement happens at the far end of the
47+ * observation chain, which carries the segment and nothing else, so the link
48+ * travels beside the chain instead of through it. Every `DocumentationError`
49+ * built for the segment therefore has its `cause` in place before any observer —
50+ * including middleware that catches what `raise` throws — can look at it.
51+ */
52+ const segmentCauses = new WeakMap < ErrorSegment , unknown > ( ) ;
53+
54+ /**
55+ * Internal: record what expansion translated into this segment, before raising
56+ * it. Not part of the package surface — an author reports a failure by throwing
57+ * it, and the engine decides what a diagnostic is made from.
58+ */
59+ export function attributeCause ( segment : ErrorSegment , from : unknown ) : void {
60+ segmentCauses . set ( segment , from ) ;
61+ }
62+
4063/**
4164 * Thrown by suppressed-documentation settlement (spec §6.9). Generic
4265 * catches in the engine rethrow it instead of converting it into an
4366 * ErrorSegment, so documentation fail-fast is never swallowed.
67+ *
68+ * A segment that expansion built from a failure of its own brings that failure
69+ * along as `cause`, so nothing that catches this error can see it without the
70+ * account of how the component got there.
4471 */
4572export class DocumentationError extends Error {
4673 readonly segment : ErrorSegment ;
@@ -49,6 +76,10 @@ export class DocumentationError extends Error {
4976 super ( segment . message ) ;
5077 this . name = "DocumentationError" ;
5178 this . segment = segment ;
79+ const from = segmentCauses . get ( segment ) ;
80+ if ( from !== undefined ) {
81+ this . cause = from ;
82+ }
5283 }
5384}
5485
@@ -69,8 +100,9 @@ export class DocumentationError extends Error {
69100 * A component that recovers and then fails on its own terms keeps this error in
70101 * the cause chain of the failure it reports, so the content failure it recovered
71102 * from — and the segments it carries — stay reachable from the outside. What is
72- * *reported* is still the component's own failure: fatal discovery stops here
73- * rather than continuing into the decision the component replaced (`causesOf`).
103+ * *reported* is still the component's own failure: documentation discovery stops
104+ * here rather than continuing into the decision the component replaced
105+ * (`isRecoveredContent`).
74106 */
75107export class ContentError extends Error {
76108 readonly errors : readonly ErrorSegment [ ] ;
@@ -124,9 +156,13 @@ export type FatalFailure = DocumentationError | DurabilityFailure;
124156 * a journal already known not to describe this run. Precedence is therefore
125157 * decided by kind, not by position: the graph is searched for a durability
126158 * failure first, and only a graph without one reports a documentation failure.
159+ *
160+ * The two searches reach different parts of the same graph. A content failure
161+ * ends the documentation search and not the durability one — see
162+ * `isRecoveredContent` for why the asymmetry is the point.
127163 */
128164export function fatalCause ( error : unknown ) : FatalFailure | undefined {
129- return durabilityFailure ( error ) ?? firstCause ( error , asDocumentationError ) ;
165+ return durabilityFailure ( error ) ?? firstCause ( error , asDocumentationError , isRecoveredContent ) ;
130166}
131167
132168/**
@@ -138,6 +174,10 @@ export function fatalCause(error: unknown): FatalFailure | undefined {
138174 * `DocumentationError` is deliberately not included — an ordinary document
139175 * failure *is* an outcome, which is why this is a narrower question than
140176 * `fatalCause`.
177+ *
178+ * This walks the whole graph. Nothing a failure is wrapped in may keep a
179+ * durability failure from being found, so unlike documentation discovery it
180+ * treats no node as a leaf.
141181 */
142182export function durabilityFailure ( error : unknown ) : DurabilityFailure | undefined {
143183 return firstCause ( error , asDurabilityFailure ) ;
@@ -160,24 +200,56 @@ function asDocumentationError(error: unknown): DocumentationError | undefined {
160200}
161201
162202/**
163- * The first failure in this one's cause graph that `select` recognises.
203+ * A failure whose own causes the current question does not extend to. The node
204+ * is still offered to `select`; what lies beneath it is out of scope.
205+ */
206+ type OpaqueFailure = ( error : object ) => boolean ;
207+
208+ /**
209+ * A content failure ends documentation discovery.
210+ *
211+ * A `ContentError` reached in a cause graph is recovered context rather than a
212+ * failure still looking for a policy: it was delivered to a component that
213+ * caught it and chose a failure of its own, and that choice is what the document
214+ * has to report. Walking through it would resurrect the decision the component
215+ * replaced — the component's contextual diagnostic would be built and then
216+ * discarded in favour of the child's.
217+ *
218+ * Durability discovery looks straight through it. Only the engine's own
219+ * projection failures are known to carry a documentation failure and nothing
220+ * else; this class is public, so an author constructs and subclasses it and may
221+ * put anything underneath — and a durability failure stays fatal however it is
222+ * wrapped (§6.11). Recovery decides which failure the document *reports*, and a
223+ * durability failure is not one of the things a document reports.
224+ */
225+ function isRecoveredContent ( error : object ) : boolean {
226+ return error instanceof ContentError ;
227+ }
228+
229+ /**
230+ * The first failure in this one's cause graph that `select` recognises, skipping
231+ * whatever `opaque` declares out of scope.
164232 *
165233 * Cause graphs are arbitrary — nothing stops `error.cause` from pointing back
166234 * at `error` — so traversal remembers what it has seen. Recursing forever would
167235 * turn an ordinary diagnostic into a stack overflow, which is exactly the
168236 * failure this traversal exists to prevent. Every question asked of a failure
169- * shares it, so no two can drift on what counts as a wrapper.
237+ * shares the traversal, so no two can drift on what counts as a wrapper; each
238+ * names its own reach, so a rule that belongs to one question cannot silence the
239+ * other.
170240 */
171241function firstCause < T > (
172242 error : unknown ,
173243 select : ( candidate : unknown ) => T | undefined ,
244+ opaque ?: OpaqueFailure ,
174245) : T | undefined {
175- return walkCauses ( error , select , new Set ( ) ) ;
246+ return walkCauses ( error , select , opaque , new Set ( ) ) ;
176247}
177248
178249function walkCauses < T > (
179250 error : unknown ,
180251 select : ( candidate : unknown ) => T | undefined ,
252+ opaque : OpaqueFailure | undefined ,
181253 seen : Set < unknown > ,
182254) : T | undefined {
183255 const selected = select ( error ) ;
@@ -187,9 +259,12 @@ function walkCauses<T>(
187259 if ( typeof error !== "object" || error === null || seen . has ( error ) ) {
188260 return undefined ;
189261 }
262+ if ( opaque !== undefined && opaque ( error ) ) {
263+ return undefined ;
264+ }
190265 seen . add ( error ) ;
191266 for ( const cause of causesOf ( error ) ) {
192- const found = walkCauses ( cause , select , seen ) ;
267+ const found = walkCauses ( cause , select , opaque , seen ) ;
193268 if ( found !== undefined ) {
194269 return found ;
195270 }
@@ -205,17 +280,6 @@ function causesOf(error: object): unknown[] {
205280 if ( error instanceof AggregateError ) {
206281 return error . errors ;
207282 }
208- // A `ContentError` reached in a cause graph is recovered context rather than a
209- // failure still looking for a policy: it was delivered to a component that
210- // caught it and chose a failure of its own, and that choice is what the
211- // document has to report. Walking through it would resurrect the decision the
212- // component replaced — the component's contextual diagnostic would be built
213- // and then discarded in favour of the child's. Nothing fatal hides behind it:
214- // failed content carries a documentation failure and nothing else, and a
215- // durability failure crosses `content()` unwrapped.
216- if ( error instanceof ContentError ) {
217- return [ ] ;
218- }
219283 if ( error instanceof Error && error . cause !== undefined ) {
220284 return [ error . cause ] ;
221285 }
0 commit comments