Skip to content

Commit 343bda6

Browse files
committed
🐛 Split durability traversal from documentation opacity at ContentError
Durability failures stay fatal however wrapped: durabilityFailure() walks the entire cause graph, including through ContentError nodes an author constructed or subclassed. Documentation discovery alone stops at a ContentError — a component that recovered and reported its own contextual failure decided what the document reports, and traversal does not resurrect the child decision. The opacity moved from causesOf() into a per-question predicate on the traversal, so wrapper contracts stay in one place. The contextual DocumentationError a thrown function-component failure translates into now carries the original thrown value as its cause from construction — installed via a segment-keyed channel read by the DocumentationError constructor itself, so raise middleware observes the complete failure and the value-root construction site is covered too. This is the general rule for ordinary function-component failures, not a <File> special case. Regressions: FA15-FA19 (durability through author ContentError forms, deep wrapper composition, no-resurrection, precedence with both present, cyclic termination) and OBS22 (middleware sees the cause inside its catch).
1 parent 687b1ca commit 343bda6

5 files changed

Lines changed: 319 additions & 45 deletions

File tree

‎packages/core/src/errors.ts‎

Lines changed: 82 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -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
*/
4572
export 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
*/
75107
export 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
*/
128164
export 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
*/
142182
export 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
*/
171241
function 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

178249
function 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
}

‎packages/core/src/expand.ts‎

Lines changed: 14 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ import {
4242
} from "./component-api.ts";
4343
import {
4444
AmbientErrorPolicy,
45+
attributeCause,
4546
ContentError,
4647
DocumentationError,
4748
durabilityFailure,
@@ -1785,24 +1786,17 @@ function errorSegments(segments: Segment[]): ErrorSegment[] {
17851786
* `DocumentationError` carrying it is what the execution fails with. The failure
17861787
* it was built from is the structural account of how the component got there —
17871788
* a component that recovered from failed content and then reported a failure of
1788-
* its own is the only place the original content failure survives. The link is
1789-
* made inside the observation chain's throw, so no observer downstream of
1790-
* settlement ever sees the failure without it, and only for the segment this
1791-
* call raised.
1789+
* its own is the only place the original content failure survives.
1790+
*
1791+
* The link is attributed to the segment before it is raised, so settlement
1792+
* constructs a failure that already carries it: middleware that catches what
1793+
* `raise` throws is an observer like any other, and there is no moment in which
1794+
* this diagnostic exists without its account. The observation itself is still the
1795+
* single `raise` of the segment.
17921796
*/
1793-
function* raiseFrom(segment: ErrorSegment, from: unknown): Operation<ErrorSegment> {
1794-
try {
1795-
return yield* raise(segment);
1796-
} catch (failure) {
1797-
if (
1798-
failure instanceof DocumentationError &&
1799-
failure.segment === segment &&
1800-
failure.cause === undefined
1801-
) {
1802-
failure.cause = from;
1803-
}
1804-
throw failure;
1805-
}
1797+
function raiseFrom(segment: ErrorSegment, from: unknown): Operation<ErrorSegment> {
1798+
attributeCause(segment, from);
1799+
return raise(segment);
18061800
}
18071801

18081802
/**
@@ -1969,9 +1963,9 @@ function* expandFunctionComponent(
19691963
// reporting it again here would double-observe it. Under a throwing policy
19701964
// that is the original `DocumentationError`, by identity; under a collecting
19711965
// one it is the segments, which the consumer boundary then settles under the
1972-
// caller's policy. Restored here rather than by `fatalCause`, which stops at
1973-
// a content failure so that a component reporting a failure of its own keeps
1974-
// it (see `causesOf`).
1966+
// caller's policy. Restored here by identity rather than by `fatalCause`,
1967+
// whose documentation search stops at a content failure so that a component
1968+
// reporting a failure of its own keeps it (see `isRecoveredContent`).
19751969
if (error instanceof ContentExpansionFailure) {
19761970
if (error.cause instanceof DocumentationError) {
19771971
throw error.cause;

‎packages/core/tests/error-observation.test.ts‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -200,6 +200,20 @@ function echoComponent(name: string): FunctionComponentDefinition {
200200
};
201201
}
202202

203+
/** Fails on its own terms, without asking for content. */
204+
function throwingComponent(name: string, failure: unknown): FunctionComponentDefinition {
205+
return {
206+
kind: "function",
207+
name,
208+
path: `${name}.ts`,
209+
props: OPEN_SCHEMA,
210+
// deno-lint-ignore require-yield
211+
*fn(_props) {
212+
throw failure;
213+
},
214+
};
215+
}
216+
203217
/**
204218
* Recovers from a failed projection and hands the caught `ContentError` to the
205219
* test scope, which is the only way to read the errors it carries: recovery
@@ -510,4 +524,68 @@ describe("Tier OBS — construct error observation", () => {
510524
expect(errorSegments(probe.segments)).toHaveLength(0);
511525
expect(probe.output).toBe("recovered");
512526
});
527+
528+
// OBS22: where the cause is attached, measured from inside the observation
529+
// chain. Raise middleware that catches what `next` throws is the earliest any
530+
// observer can see the DocumentationError — settlement constructs it at the end
531+
// of the chain — so a failure that is complete there is complete everywhere.
532+
it("OBS22: a contextual failure carries its cause where the chain throws it", function* () {
533+
const exploded = new Error("component exploded");
534+
const observed: ErrorSegment[] = [];
535+
// The cause is read where the middleware catches, not afterwards: a link
536+
// attached once the chain has unwound would be invisible to a test that
537+
// inspected the same object at the end of the run.
538+
const caught: Array<{ failure: DocumentationError; cause: unknown }> = [];
539+
let thrown: unknown;
540+
541+
yield* scoped(function* () {
542+
yield* AmbientErrorPolicy.set("throw");
543+
yield* Component.around({
544+
*raise([error], next) {
545+
observed.push(error);
546+
try {
547+
return yield* next(error);
548+
} catch (failure) {
549+
if (failure instanceof DocumentationError) {
550+
caught.push({ failure, cause: failure.cause });
551+
}
552+
throw failure;
553+
}
554+
},
555+
});
556+
yield* Component.around(
557+
{
558+
env: () => ({ values: {} }),
559+
// deno-lint-ignore require-yield
560+
*importComponent([name], _next) {
561+
if (name !== "Boom") {
562+
throw new Error(`Component not found: ${name}`);
563+
}
564+
return throwingComponent("Boom", exploded);
565+
},
566+
},
567+
{ at: "min" },
568+
);
569+
try {
570+
yield* expandSegments(scanSegments("<Boom />"), {}, {}, new Set());
571+
} catch (error) {
572+
thrown = error;
573+
}
574+
});
575+
576+
expect(caught).toHaveLength(1);
577+
const [{ failure, cause }] = caught;
578+
expect(cause).toBe(exploded);
579+
expect(failure.message).toContain("Function component Boom error: component exploded");
580+
581+
// The same object leaves the expansion, with the same cause.
582+
expect(thrown).toBe(failure);
583+
expect(thrown).toBeInstanceOf(DocumentationError);
584+
expect(failure.cause).toBe(exploded);
585+
586+
// One observation of the contextual segment, and it is the one the failure
587+
// carries.
588+
expect(observed).toHaveLength(1);
589+
expect(observed[0]).toBe(failure.segment);
590+
});
513591
});

0 commit comments

Comments
 (0)