Skip to content

Commit 07d60c4

Browse files
committed
🔒 Let the document decide what a composition failure means
`<Repository>`, `<Worktree>` and `<Dir>` each declared `printErrors`, which is a statement about an entire invocation rather than about the refusals they own. The settled contract asks them for fixed, sanitized diagnostics; it does not authorize them to recover from every nonfatal exception that passes through them. Under that declaration a document could carry on after invalid props, a provider that was not installed, or a protocol answer that would not parse — running later siblings as though a checkout existed. The rule is now one rule: these components describe known refusals, and document-authored regions decide whether to print and continue. A recognized refusal is still a failed durable outcome against the unchanged Workspace root and still surfaces as the same sanitized `RepositoryCompositionError` or `WorktreeCompositionError` — it simply fails the operation it is part of, like any other Effection work, unless an authored `<PrintErrors>` region says otherwise for its whole region. Nothing selective was added in its place. Unchanged in both directions: `RepositoryStaleStateError` is a durability failure and stays fatal through every printing boundary, and a failure of projected content stays the caller's, decided by the region that text is written in. The regressions now discriminate policy rather than diagnostic text. Each pair puts a marker after the failing element and asserts on the marker: plain, the run fails and the marker never renders; inside `<PrintErrors>`, exactly one error is printed and the marker does render. That covers the invalid `<Dir>`, the Repository refusal, the Worktree refusal with and without an enclosing Repository, and — on the durable side — that a plain refusal leaves one `err` outcome, publishes no root and retains nothing, while the printed one continues without repeating the effect. Three more prove what these components must never convert: a missing provider, an unexpected host failure, and a projected-content failure through all three boundaries. Schema v1, persistence layout, Git identity checks, target selection, core error semantics and #294 behavior are untouched. Refs #293
1 parent 071baee commit 07d60c4

8 files changed

Lines changed: 445 additions & 96 deletions

File tree

‎packages/workflow/src/composition/components/Dir.ts‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -15,11 +15,13 @@
1515
*
1616
* Self-closing `<Dir />` is invalid. A working directory installed for no
1717
* content is a directory nothing runs in, and silently rendering nothing would
18-
* hide a document that meant to write children.
18+
* hide a document that meant to write children. Being invalid, it fails the
19+
* operation it is part of; an authored `<PrintErrors>` region may recover from
20+
* that explicitly, and nothing here decides it on an author's behalf.
1921
*/
2022

2123
import { API, cwd } from "@executablemd/runtime";
22-
import { content, hasContent, printErrors } from "@executablemd/core";
24+
import { content, hasContent } from "@executablemd/core";
2325
import type { Operation } from "effection";
2426
import type { Json } from "@executablemd/durable-streams";
2527

@@ -36,7 +38,7 @@ export class DirInvocationError extends Error {
3638
override name = "DirInvocationError";
3739
}
3840

39-
export default printErrors(function* Dir(props: Record<string, Json>): Operation<string> {
41+
export default function* Dir(props: Record<string, Json>): Operation<string> {
4042
const path = props.path;
4143
if (typeof path !== "string" || path === "") {
4244
throw new DirInvocationError("<Dir> needs a non-empty path.");
@@ -70,4 +72,4 @@ export default printErrors(function* Dir(props: Record<string, Json>): Operation
7072
{ at: "min" },
7173
);
7274
return yield* content();
73-
});
75+
}

‎packages/workflow/src/composition/components/Repository.ts‎

Lines changed: 23 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -15,16 +15,30 @@
1515
* binds the returned string, which is what keeps `as` one rule rather than a
1616
* Repository-shaped exception to one.
1717
*
18-
* `printErrors` covers what this component does on its own — admitting the
19-
* locator, resolving the base, retaining the checkout, attaching to it. It does
20-
* not cover the content a caller projected: that text is the caller's, and the
21-
* region it is written in decides what a failure of it means. Nor does it cover
22-
* a stale-state failure, which is a durability failure and travels past every
23-
* printing boundary by construction.
18+
* ## Who decides what a failure means
19+
*
20+
* This component describes what went wrong; it does not decide what the
21+
* document does about it. A refusal it recognizes — a locator it will not use,
22+
* a base that names no commit, a name already this run's for another url —
23+
* arrives as a fixed `RepositoryCompositionError` and then fails the operation
24+
* it is part of, like any other Effection work. An authored `<PrintErrors>`
25+
* region is what says otherwise, and it says so for everything inside it rather
26+
* than for this component alone.
27+
*
28+
* Declaring `printErrors` here would have made that decision for every author,
29+
* for every failure this invocation owns: invalid props, a provider that is not
30+
* installed, a protocol answer that will not parse. None of those is a refusal
31+
* a document asked for, and continuing past one would run later siblings as
32+
* though a checkout existed.
33+
*
34+
* Two things are unaffected, in opposite directions. A stale-state failure is a
35+
* durability failure and travels past every printing boundary, authored or not.
36+
* A failure of the content a caller projected is the caller's, decided by the
37+
* region that text is written in.
2438
*/
2539

2640
import { API } from "@executablemd/runtime";
27-
import { content, hasContent, printErrors } from "@executablemd/core";
41+
import { content, hasContent } from "@executablemd/core";
2842
import type { Operation } from "effection";
2943
import type { Json } from "@executablemd/durable-streams";
3044
import { RepositoryComposition } from "../api.ts";
@@ -68,7 +82,7 @@ export function parseRepositoryProps(props: Record<string, Json>): RepositoryCre
6882
};
6983
}
7084

71-
export default printErrors(function* Repository(props: Record<string, Json>): Operation<string> {
85+
export default function* Repository(props: Record<string, Json>): Operation<string> {
7286
const record = yield* RepositoryComposition.operations.createRepository(
7387
parseRepositoryProps(props),
7488
);
@@ -89,4 +103,4 @@ export default printErrors(function* Repository(props: Record<string, Json>): Op
89103
{ at: "min" },
90104
);
91105
return yield* content();
92-
});
106+
}

‎packages/workflow/src/composition/components/Worktree.ts‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -22,10 +22,16 @@
2222
* rendered descendants are captured and suppressed. It does not bind the
2323
* checkout path while also rendering them, and nothing here makes an exception
2424
* so that it could.
25+
*
26+
* Failure policy is `<Repository>`'s, for the same reason: a refusal this
27+
* recognizes — no Repository in scope, a branch another checkout holds, a name
28+
* already this Repository's for another branch — is described with a fixed
29+
* `WorktreeCompositionError` and then fails the operation it is part of. An
30+
* authored `<PrintErrors>` region decides otherwise, for its whole region.
2531
*/
2632

2733
import { API } from "@executablemd/runtime";
28-
import { content, hasContent, printErrors } from "@executablemd/core";
34+
import { content, hasContent } from "@executablemd/core";
2935
import type { Operation } from "effection";
3036
import type { Json } from "@executablemd/durable-streams";
3137
import { RepositoryComposition } from "../api.ts";
@@ -55,7 +61,7 @@ function required(props: Record<string, Json>, prop: string): string {
5561
return value;
5662
}
5763

58-
export default printErrors(function* Worktree(props: Record<string, Json>): Operation<string> {
64+
export default function* Worktree(props: Record<string, Json>): Operation<string> {
5965
const name = required(props, "name");
6066
const branch = required(props, "branch");
6167
const base = typeof props.base === "string" && props.base !== "" ? props.base : undefined;
@@ -92,4 +98,4 @@ export default printErrors(function* Worktree(props: Record<string, Json>): Oper
9298
{ at: "min" },
9399
);
94100
return yield* content();
95-
});
101+
}

‎packages/workflow/src/composition/errors.ts‎

Lines changed: 9 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,15 @@
1111
* Two kinds of failure live here and they are not interchangeable. An ordinary
1212
* refusal is something the document asked for and did not get — a locator that
1313
* cannot be admitted, a base that resolves to nothing, a branch already checked
14-
* out somewhere else. It is printable, and the component declares that about
15-
* itself. A stale-state failure is the retained authoritative state disagreeing
16-
* with what attachment found, which is not something the document did and not
17-
* something printing could make safe.
14+
* out somewhere else. Describing it is this package's job; deciding what the
15+
* document does about it is not. It fails the operation it is part of like any
16+
* other Effection work, and an authored `<PrintErrors>` region is what says
17+
* otherwise — for everything inside that region rather than for these
18+
* components alone.
19+
*
20+
* A stale-state failure is the retained authoritative state disagreeing with
21+
* what attachment found. That is not something the document did, and not
22+
* something an authored region may decide either.
1823
*/
1924

2025
import { StaleInputError } from "@executablemd/durable-streams";

0 commit comments

Comments
 (0)