Skip to content

Commit 687b1ca

Browse files
committed
🐛 Keep the recovered content failure reachable through the cause chain
Per the product-owner decision on <File>: a component that recovers a content failure and reports its own contextual failure keeps the original reachable structurally. FileAccessError now carries the caught ContentError as its cause; the generic function-component failure branch threads the thrown error into the contextual DocumentationError under a throwing policy, so the outward failure is the component's own with the caught ContentError and the original child DocumentationError beneath it, each by identity. ContentError is opaque to cause traversal: a recovered failure in a cause graph must not resurrect the decision the component replaced, so causesOf() does not walk through it. Uncaught restoration of the original DocumentationError moves into the private transport branch, still after fatal selection; durability precedence is unchanged because durability never travels inside the transport. Committed regressions the review required: FL12b/FL12c (File cause contract under throw and collect), CE24 (an author-thrown ContentError has no transport authority), CE25/CE26 (durability crosses content() unwrapped, by identity, under both policies), FC12 (a compiled component catches ContentError through the package barrel and recovers).
1 parent 75ad789 commit 687b1ca

7 files changed

Lines changed: 431 additions & 14 deletions

File tree

‎packages/core/src/components/File.ts‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -88,8 +88,8 @@ export const props = {
8888

8989
/** A path that leaves the working directory, or a target that cannot be text. */
9090
export class FileAccessError extends Error {
91-
constructor(message: string) {
92-
super(message);
91+
constructor(message: string, options?: ErrorOptions) {
92+
super(message, options);
9393
this.name = "FileAccessError";
9494
}
9595
}
@@ -150,6 +150,12 @@ export default function* (props: Record<string, Json>): Operation<string> {
150150
* The original messages come along, because `<File>` renders nothing: this
151151
* diagnostic is the only place the reader would learn what actually went wrong.
152152
* Anything else thrown is not a content failure and passes through untouched.
153+
*
154+
* The content failure itself stays in this failure's cause chain. What is
155+
* reported is this component's own diagnostic — the write is what the document
156+
* asked for, and that it did not happen is the fact a reader needs — while the
157+
* failure it was translated from, and the error segments it carries, remain
158+
* reachable underneath for a host inspecting what ended the execution.
153159
*/
154160
function* rendered(requested: string): Operation<string> {
155161
try {
@@ -161,6 +167,7 @@ function* rendered(requested: string): Operation<string> {
161167
const failures = error.errors.map((segment) => segment.message);
162168
throw new FileAccessError(
163169
`did not write "${requested}": its content failed to expand. ${failures.join(" ")}`,
170+
{ cause: error },
164171
);
165172
}
166173
}

‎packages/core/src/errors.ts‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,12 @@ export class DocumentationError extends Error {
6565
* code does not branch on the ambient policy. Left uncaught, normal
6666
* continuation stops and the invocation boundary reports the original errors
6767
* under the consumer's policy.
68+
*
69+
* A component that recovers and then fails on its own terms keeps this error in
70+
* the cause chain of the failure it reports, so the content failure it recovered
71+
* 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`).
6874
*/
6975
export class ContentError extends Error {
7076
readonly errors: readonly ErrorSegment[];
@@ -199,6 +205,17 @@ function causesOf(error: object): unknown[] {
199205
if (error instanceof AggregateError) {
200206
return error.errors;
201207
}
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+
}
202219
if (error instanceof Error && error.cause !== undefined) {
203220
return [error.cause];
204221
}

‎packages/core/src/expand.ts‎

Lines changed: 50 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1777,6 +1777,34 @@ function errorSegments(segments: Segment[]): ErrorSegment[] {
17771777
return segments.filter((segment) => segment.type === "error");
17781778
}
17791779

1780+
/**
1781+
* Report a diagnostic built from a failure, keeping that failure reachable
1782+
* underneath whatever settlement produces.
1783+
*
1784+
* The diagnostic is what the document says, and under a throwing policy the
1785+
* `DocumentationError` carrying it is what the execution fails with. The failure
1786+
* it was built from is the structural account of how the component got there —
1787+
* 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.
1792+
*/
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+
}
1806+
}
1807+
17801808
/**
17811809
* Expand a function component (.ts file).
17821810
*
@@ -1936,11 +1964,18 @@ function* expandFunctionComponent(
19361964
if (fatal !== undefined) {
19371965
throw fatal;
19381966
}
1939-
// The content the component asked for failed and it did not recover: the
1940-
// invocation is replaced by the errors the projection already reported
1941-
// (§6.9), which the consumer boundary then settles under the caller's
1942-
// policy. Reporting them again here would double-observe them.
1967+
// The content the component asked for failed and it did not recover, so the
1968+
// invocation is replaced by what the projection already reported (§6.9) and
1969+
// reporting it again here would double-observe it. Under a throwing policy
1970+
// that is the original `DocumentationError`, by identity; under a collecting
1971+
// 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`).
19431975
if (error instanceof ContentExpansionFailure) {
1976+
if (error.cause instanceof DocumentationError) {
1977+
throw error.cause;
1978+
}
19441979
return [...error.errors];
19451980
}
19461981
// A return that failed its schema already names the component and carries
@@ -1949,14 +1984,17 @@ function* expandFunctionComponent(
19491984
return [yield* raise(schemaValidationErrorSegment(error, name))];
19501985
}
19511986
return [
1952-
yield* raise({
1953-
type: "error",
1954-
message:
1955-
error instanceof Error
1956-
? `Function component ${name} error: ${error.message}`
1957-
: `Function component ${name} error: ${String(error)}`,
1958-
source: name,
1959-
}),
1987+
yield* raiseFrom(
1988+
{
1989+
type: "error",
1990+
message:
1991+
error instanceof Error
1992+
? `Function component ${name} error: ${error.message}`
1993+
: `Function component ${name} error: ${String(error)}`,
1994+
source: name,
1995+
},
1996+
error,
1997+
),
19601998
];
19611999
}
19622000
}

‎packages/core/tests/capture-errors.test.ts‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,7 @@ import { describe, it } from "@executablemd/test-support/bdd";
22
import { expect } from "@executablemd/test-support/expect";
33
import { ensure, scoped, sleep, spawn, suspend, withResolvers } from "effection";
44
import type { Operation } from "effection";
5+
import { StaleInputError } from "@executablemd/durable-streams";
56
import { expandSegments } from "../src/expand.ts";
67
import { Component, content, raise } from "../src/component-api.ts";
78
import { useContent } from "../src/content-context.ts";
@@ -150,6 +151,26 @@ function recovering(
150151
};
151152
}
152153

154+
/**
155+
* An author who constructs and throws the public `ContentError` themselves.
156+
*
157+
* The segment it carries was never reported, so it is not transport: the effect
158+
* recorded before the throw is what shows the function body ran and fabricated
159+
* it rather than receiving it from a content failure.
160+
*/
161+
function forging(name: string, log: Trace, fabricated: ErrorSegment): FunctionComponentDefinition {
162+
return {
163+
kind: "function",
164+
name,
165+
path: `${name}.ts`,
166+
props: OPEN_SCHEMA,
167+
*fn(_props) {
168+
yield* recordEntry(log.effects, name);
169+
throw new ContentError([fabricated]);
170+
},
171+
};
172+
}
173+
153174
/**
154175
* An unresolvable component is the cheapest way to plant an ErrorSegment
155176
* inside a captured subtree: the import failure is reported by the body's own
@@ -176,6 +197,23 @@ function useBroken(): Operation<void> {
176197
});
177198
}
178199

200+
/**
201+
* Claims `<Stale />` and fails its expansion with the planted durability
202+
* failure. The journal no longer describes this run, so nothing between the
203+
* projection and the document may translate it into a diagnostic or present it
204+
* as a content failure.
205+
*/
206+
function useStale(planted: StaleInputError): Operation<void> {
207+
return Component.around({
208+
*expand([element], next) {
209+
if (element.name === "Stale") {
210+
throw planted;
211+
}
212+
return yield* next(element);
213+
},
214+
});
215+
}
216+
179217
/**
180218
* Claims `<Spawner />` and spawns ordinary suspended work inside the expansion
181219
* that projects it. Nothing retains it, so it belongs to the projection's task
@@ -209,6 +247,8 @@ interface RunOptions {
209247
functions?: Record<string, FunctionComponentDefinition>;
210248
values?: Record<string, unknown>;
211249
trace?: Trace;
250+
/** Fail `<Stale />` expansion with this durability failure. */
251+
stale?: StaleInputError;
212252
}
213253

214254
function run(source: string, opts: RunOptions = {}): Operation<CaptureRun> {
@@ -234,6 +274,10 @@ function run(source: string, opts: RunOptions = {}): Operation<CaptureRun> {
234274
});
235275
yield* useBroken();
236276
yield* useSpawner(log);
277+
const planted = opts.stale;
278+
if (planted) {
279+
yield* useStale(planted);
280+
}
237281
yield* Component.around(
238282
{
239283
// deno-lint-ignore require-yield
@@ -629,4 +673,90 @@ describe("capture error propagation", () => {
629673
expect(log.effects).toEqual([]);
630674
expect("cap" in values).toBe(false);
631675
});
676+
677+
it("CE24: an author-thrown ContentError is an ordinary function-component error", function* () {
678+
const log = trace();
679+
const fabricated: ErrorSegment = {
680+
type: "error",
681+
message: "author fabricated",
682+
source: "Forge",
683+
};
684+
const result = yield* run("<Forge>body</Forge>TAIL", {
685+
functions: { Forge: forging("Forge", log, fabricated) },
686+
trace: log,
687+
});
688+
689+
// The body ran and threw its own ContentError, so the transport path was
690+
// never entered — the engine reports the component's failure instead.
691+
expect(log.effects).toEqual(["Forge"]);
692+
const reported = errors(result.segments);
693+
expect(reported).toHaveLength(1);
694+
expect(reported[0]).not.toBe(fabricated);
695+
expect(reported[0].source).toBe("Forge");
696+
expect(reported[0].message).toBe("Function component Forge error: author fabricated");
697+
// The fabricated segment is reported by nothing and reaches nothing: the one
698+
// observation is the engine's own diagnostic, and the document renders only
699+
// that, with the author's message quoted inside it.
700+
expect(log.raised).toHaveLength(1);
701+
expect(log.raised[0]).toBe(reported[0]);
702+
expect(log.raised.includes(fabricated)).toBe(false);
703+
expect(result.segments.includes(fabricated)).toBe(false);
704+
expect(result.output).toBe(
705+
"<!-- ERROR: Function component Forge error: author fabricated -->TAIL",
706+
);
707+
});
708+
709+
it("CE25: a durability failure crossing content() is neither a ContentError nor a diagnostic", function* () {
710+
const log = trace();
711+
const planted = new StaleInputError("PLANTED_DURABILITY_FAILURE");
712+
let thrown: unknown;
713+
try {
714+
yield* run("<Recover><Stale /></Recover>TAIL", {
715+
functions: { Recover: recovering("Recover", log) },
716+
stale: planted,
717+
trace: log,
718+
});
719+
} catch (error) {
720+
thrown = error;
721+
}
722+
723+
// The catch at `yield* content()` saw the durability failure itself, so the
724+
// `instanceof ContentError` branch could not match and rethrew it.
725+
expect(log.caught).toHaveLength(1);
726+
expect(log.caught[0]).toBe(planted);
727+
expect(log.caught[0]).not.toBeInstanceOf(ContentError);
728+
expect(log.recoveries).toEqual([]);
729+
// It left expansion by identity rather than becoming an ErrorSegment: a
730+
// collecting policy renders whatever was reported, and nothing was.
731+
expect(thrown).toBe(planted);
732+
expect(log.raised).toEqual([]);
733+
expect(log.failures).toEqual([]);
734+
});
735+
736+
it("CE26: a durability failure at the content boundary outranks the throwing policy", function* () {
737+
const log = trace();
738+
const planted = new StaleInputError("PLANTED_DURABILITY_FAILURE");
739+
let thrown: unknown;
740+
try {
741+
yield* run("<Recover><Stale /></Recover>TAIL", {
742+
functions: { Recover: recovering("Recover", log) },
743+
stale: planted,
744+
throwing: true,
745+
trace: log,
746+
});
747+
} catch (error) {
748+
thrown = error;
749+
}
750+
751+
// Same source, opposite policy: the object that escapes is still the planted
752+
// failure, and no DocumentationError was constructed for it to outrank.
753+
expect(thrown).toBe(planted);
754+
expect(thrown).not.toBeInstanceOf(DocumentationError);
755+
expect(thrown).not.toBeInstanceOf(ContentError);
756+
expect(log.caught).toHaveLength(1);
757+
expect(log.caught[0]).toBe(planted);
758+
expect(log.recoveries).toEqual([]);
759+
expect(log.raised).toEqual([]);
760+
expect(log.failures).toEqual([]);
761+
});
632762
});

0 commit comments

Comments
 (0)