Skip to content

Commit 6451b53

Browse files
committed
🧾 Hold a retained switch result to the identity and transition it claims
Review of 787dca5 found three ways a retained result or a failure could still say something this run cannot have produced. **A Worktree's name and its path are one identity.** The protocol checked that a named Worktree used a non-primary path containing the working directory, which a result naming one Worktree at another's path satisfies. Placement is a function of identity and the function is the provider's, so the shared protocol cannot decide it and now does not pretend to: it parses the structure and the agreement with the request, and the Deno provider holds the parsed identity to `placedCheckout()` — recomputed, so a replayed result is checked without reading anything. **Switching to the branch you are on moves nothing.** The transition rules required an unchanged commit and HEAD tree for that case but let the index digest change, which describes a staging this component does not do. The index tree is now held unchanged too. **No enclosing `<Repository>` is missing authority, not a refusal.** It raised a printable `GitOperationError`, so an authored `<PrintErrors>` region could settle it as data and run the siblings after it as though a branch had moved. It now raises `GitOperationAuthorityError` like every other authority failure, travels past every printing boundary, and `no-repository-context` leaves the Git refusal vocabulary. The component header described the working-directory failures as printable refusals; it now describes both kinds and which is which. Three regressions, each mutation-checked against the correction it covers: a linked-Worktree replay whose retained name no longer matches its placement, one whose path is given to no name, and a no-op transition whose retained index changed — all fail closed with no Git — plus the missing-Repository failure asserted through an authored region.
1 parent 787dca5 commit 6451b53

9 files changed

Lines changed: 214 additions & 32 deletions

File tree

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

Lines changed: 19 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -22,14 +22,21 @@
2222
* a document already wrote would only invite reading it back as though it were
2323
* an answer.
2424
*
25-
* Failure policy is `<Repository>`'s. A refusal this recognizes — no Repository
26-
* in scope, a working directory that is not one of this run's checkouts, a base
27-
* that names no commit, a branch another checkout holds, local changes Git would
28-
* overwrite — arrives as a fixed `GitOperationError` and then fails the operation
29-
* it is part of. An authored `<PrintErrors>` region decides otherwise, for its
30-
* whole region. A stale-state failure travels past every printing boundary,
31-
* because retained state disagreeing with what is there is not something the
32-
* document did.
25+
* ## Two kinds of failure, and only one of them is the document's
26+
*
27+
* A refusal is something the document asked for and did not get: a base that
28+
* names no commit, a branch another checkout holds, local changes Git would
29+
* overwrite. Each arrives as a fixed `GitOperationError` and then fails the
30+
* operation it is part of, and an authored `<PrintErrors>` region decides
31+
* otherwise for its whole region.
32+
*
33+
* Authority is not that. No Repository in scope, a Repository this run does not
34+
* retain, a working directory inside none of its checkouts, retained state that
35+
* has stopped agreeing with the identity naming it — none of these is an outcome
36+
* a document could have avoided by asking for something else, and continuing
37+
* past one would run later siblings as though a branch had moved. They travel as
38+
* `GitOperationAuthorityError`, past every printing boundary, and nothing is
39+
* published for them.
3340
*/
3441

3542
import { cwd } from "@executablemd/runtime";
@@ -38,7 +45,7 @@ import type { Operation } from "effection";
3845
import type { Json } from "@executablemd/durable-streams";
3946
import { GitComposition } from "../git-api.ts";
4047
import { currentRepository } from "../context.ts";
41-
import { GitOperationError } from "../errors.ts";
48+
import { GitOperationAuthorityError, GitOperationError } from "../errors.ts";
4249

4350
/** The component name, as a document writes it and as a refusal names it. */
4451
export const SWITCH = "<Git.Switch>";
@@ -83,11 +90,10 @@ export default function* GitSwitch(props: Record<string, Json>): Operation<strin
8390

8491
const repository = yield* currentRepository();
8592
if (repository === undefined) {
86-
throw new GitOperationError(
93+
throw new GitOperationAuthorityError(
8794
SWITCH,
88-
"no-repository-context",
89-
`${SWITCH} is invalid outside a lexical <Repository>: a branch is a branch of one, and ` +
90-
"there is none in scope here.",
95+
"it is written outside a lexical <Repository>, so there is no repository in scope for a " +
96+
"branch to be a branch of",
9197
);
9298
}
9399

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

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -131,7 +131,6 @@ export class RepositoryCompositionProtocolError extends WorkflowStorageError {
131131
* what it printed.
132132
*/
133133
export type GitFailureReason =
134-
| "no-repository-context"
135134
| "invalid-invocation"
136135
| "invalid-branch"
137136
| "unresolved-base"

‎packages/workflow/src/composition/git-records.ts‎

Lines changed: 13 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -172,7 +172,12 @@ export interface GitSwitchExpectation {
172172
* branch or base is not the one the request asked for, and whose two readings do
173173
* not describe a switch: a created branch ends at the commit it was created
174174
* from and cannot be the branch the checkout was already on, and a checkout that
175-
* ends on the branch it began on cannot have moved.
175+
* ends on the branch it began on cannot have moved — not its commit, not its
176+
* HEAD tree, and not its index.
177+
*
178+
* What it cannot decide is where a name is placed. A checkout path is a function
179+
* of identity, and whose function it is belongs to the provider, so the caller
180+
* holds the parsed identity to its own placement before using it.
176181
*/
177182
export function parseGitSwitchResult(
178183
value: unknown,
@@ -225,10 +230,16 @@ export function parseGitSwitchResult(
225230
if (created && (after.commit !== resolvedBase || before.branch === after.branch)) {
226231
return undefined;
227232
}
233+
// Switching to the branch a checkout is already on moves nothing: no reset,
234+
// no reference change, and nothing staged or unstaged. A retained result whose
235+
// commit, HEAD tree or index tree changed across it describes a transition
236+
// Switch does not make.
228237
if (
229238
!created &&
230239
before.branch === after.branch &&
231-
(before.commit !== after.commit || before.headTree !== after.headTree)
240+
(before.commit !== after.commit ||
241+
before.headTree !== after.headTree ||
242+
before.indexTree !== after.indexTree)
232243
) {
233244
return undefined;
234245
}

‎packages/workflow/src/deno/composition/identity.ts‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
*/
1111
import { RepositoryStaleStateError } from "../../composition/errors.ts";
1212
import type { RepositoryRecord, WorktreeRecord } from "../../composition/records.ts";
13+
import type { GitCheckoutIdentity } from "../../composition/git-records.ts";
1314
import type { StoredRepository } from "../workspace/repositories.ts";
1415
import { admitLocator, locatorFingerprint } from "./locator.ts";
1516
import { repositoryCheckoutPath, worktreeCheckoutPath } from "./placement.ts";
@@ -110,6 +111,35 @@ export function agreedStored(stored: StoredRepository, subject: string): StoredR
110111
return stored;
111112
}
112113

114+
/**
115+
* Whether this checkout identity is the one this run's placement gives that name.
116+
*
117+
* The half of a retained result the shared protocol cannot check. Placement is a
118+
* function of identity and the function is this provider's, so a name and a path
119+
* that arrive together have to still be the pair placement produces: a result
120+
* naming one Worktree at another's path, or naming a Worktree at all where the
121+
* path is the Repository's own, is describing a checkout this run never had.
122+
*
123+
* Recomputed rather than looked up, so a replayed result is held to it without
124+
* reading anything — which is what makes it answerable on the path that performs
125+
* no effect at all.
126+
*/
127+
export function placedCheckout(
128+
identity: GitCheckoutIdentity,
129+
repository: RepositoryRecord,
130+
): boolean {
131+
if (
132+
identity.repositoryName !== repository.name ||
133+
repository.checkoutPath !== repositoryCheckoutPath(repository.name)
134+
) {
135+
return false;
136+
}
137+
return identity.worktreeName === null
138+
? identity.checkoutPath === repositoryCheckoutPath(identity.repositoryName)
139+
: identity.checkoutPath ===
140+
worktreeCheckoutPath(identity.repositoryName, identity.worktreeName);
141+
}
142+
113143
export function repositorySubject(name: string): string {
114144
return `repository ${JSON.stringify(name)}`;
115145
}

‎packages/workflow/src/deno/composition/refusals.ts‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,6 @@ const GIT_REASONS: ReadonlyMap<string, GitFailureReason> = new Map([
4949
] as const);
5050

5151
const GIT_SENTENCES: ReadonlyMap<GitFailureReason, string> = new Map([
52-
["no-repository-context", "there is no enclosing <Repository>."],
5352
["invalid-invocation", "it is not written the way that component is written."],
5453
["invalid-branch", "the branch it names cannot be used as one."],
5554
["unresolved-base", "its base does not name a commit in that repository."],

‎packages/workflow/src/deno/composition/switch.ts‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,7 @@ import {
3636
} from "./effects.ts";
3737
import { gitRefused } from "./refusals.ts";
3838
import { performGitOperation, type GitCheckout } from "./operations.ts";
39+
import { placedCheckout } from "./identity.ts";
3940

4041
/** The effect type one branch change is recorded under. */
4142
export const WORKSPACE_GIT_SWITCH = "workspace_git_switch";
@@ -160,9 +161,11 @@ export function* createGitSwitch(
160161
);
161162
// Read for this request rather than merely read: a result that does not
162163
// describe the checkout, branch, base and transition this invocation asked for
163-
// is not this invocation's result, whatever else it is.
164+
// is not this invocation's result, whatever else it is. The identity it names
165+
// is then held to this provider's own placement, which is the half of it the
166+
// shared protocol has no way to decide.
164167
const result = parseGitSwitchResult(outcome, request);
165-
if (result === undefined) {
168+
if (result === undefined || !placedCheckout(result.checkout, request.repository)) {
166169
throw new GitOperationProtocolError(SWITCH);
167170
}
168171
return result;

‎packages/workflow/tests/git-switch-durability.test.ts‎

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -65,6 +65,33 @@ function source(locator: string): string {
6565
].join("\n");
6666
}
6767

68+
/** A switch of a linked Worktree, so a suite can damage the pairing it retains. */
69+
function worktreeSource(locator: string): string {
70+
return [
71+
`<Repository name="project" url="${locator}">`,
72+
`<Worktree name="implementation" branch="feature/new" as="worktree" />`,
73+
"<Dir path={worktree}>",
74+
`<Git.Switch branch="release" />`,
75+
`<File path="which.txt" as="which" />`,
76+
"",
77+
"after: {which}",
78+
"</Dir>",
79+
"</Repository>",
80+
].join("\n");
81+
}
82+
83+
/** A switch to the branch the checkout is already on, which moves nothing. */
84+
function unchangedSource(locator: string): string {
85+
return [
86+
`<Repository name="project" url="${locator}">`,
87+
`<Git.Switch branch="main" />`,
88+
`<File path="which.txt" as="which" />`,
89+
"",
90+
"after: {which}",
91+
"</Repository>",
92+
].join("\n");
93+
}
94+
6895
function isProtocolFailure(value: unknown): value is GitOperationProtocolError {
6996
return value instanceof GitOperationProtocolError;
7097
}
@@ -239,6 +266,89 @@ describe("workflow Git.Switch durability", () => {
239266
});
240267
}
241268

269+
/**
270+
* A retained Worktree identity is a name *and* the place that name is given.
271+
*
272+
* Placement is a function of identity, so the two travel together and have to
273+
* still be the pair placement produces. A result naming one Worktree at
274+
* another's path, or at a path no name is given, describes a checkout this run
275+
* never had — and nothing about the shape of it says so.
276+
*/
277+
const WORKTREE_DAMAGE: { name: string; damage: (record: Record<string, unknown>) => void }[] = [
278+
{
279+
name: "names a Worktree that is not the one placed at its path",
280+
damage: (record) => {
281+
Object(record.checkout).worktreeName = "forged";
282+
},
283+
},
284+
{
285+
name: "names a path this run's placement gives no Worktree",
286+
damage: (record) => {
287+
Object(record.checkout).checkoutPath = "/worktrees";
288+
},
289+
},
290+
];
291+
292+
for (const { name, damage } of WORKTREE_DAMAGE) {
293+
it(`fails a replay whose retained result ${name}`, function* () {
294+
const root = yield* useStorageRoot();
295+
const remote = yield* useBareRemote(REMOTE);
296+
const path = runPath(root, "release-1.4");
297+
298+
yield* withStorage(root, function* () {
299+
const database = yield* createRun();
300+
expect(String(yield* runDocument(database, worktreeSource(remote.locator)))).toContain(
301+
"after: release",
302+
);
303+
304+
dropRootClose(path);
305+
damageSwitchResult(path, damage);
306+
307+
const counting = countingHost();
308+
const failure = yield* raised(
309+
runDocument(database, worktreeSource(remote.locator), countingOptions(counting)),
310+
);
311+
312+
expect(causedBy(failure, isProtocolFailure)).toBeInstanceOf(GitOperationProtocolError);
313+
expect(subcommands(counting.counters)).not.toContain("switch");
314+
});
315+
});
316+
}
317+
318+
it("fails a replay whose no-op transition staged something", function* () {
319+
const root = yield* useStorageRoot();
320+
const remote = yield* useBareRemote(REMOTE);
321+
const path = runPath(root, "release-1.4");
322+
323+
yield* withStorage(root, function* () {
324+
const database = yield* createRun();
325+
// Switching to the branch the checkout is already on moves nothing, so a
326+
// retained index digest that changed across it is describing a transition
327+
// this component does not make.
328+
expect(String(yield* runDocument(database, unchangedSource(remote.locator)))).toContain(
329+
"after: main",
330+
);
331+
const [outcome] = yield* gitOutcomes(database);
332+
const before = Object(Reflect.get(Object(outcome?.record), "before"));
333+
const after = Object(Reflect.get(Object(outcome?.record), "after"));
334+
expect(before.branch).toBe(after.branch);
335+
expect(before.indexTree).toBe(after.indexTree);
336+
337+
dropRootClose(path);
338+
damageSwitchResult(path, (record) => {
339+
Object(record.after).indexTree = "0".repeat(40);
340+
});
341+
342+
const counting = countingHost();
343+
const failure = yield* raised(
344+
runDocument(database, unchangedSource(remote.locator), countingOptions(counting)),
345+
);
346+
347+
expect(causedBy(failure, isProtocolFailure)).toBeInstanceOf(GitOperationProtocolError);
348+
expect(subcommands(counting.counters)).not.toContain("switch");
349+
});
350+
});
351+
242352
it("leaves the frontier untouched when a blocked switch is halted", function* () {
243353
const root = yield* useStorageRoot();
244354
const remote = yield* useBareRemote(REMOTE);

‎packages/workflow/tests/git-switch.test.ts‎

Lines changed: 22 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -86,6 +86,9 @@ const REMOTE = {
8686
],
8787
} as const;
8888

89+
/** Text a suite looks for to say whether work after a failure still ran. */
90+
const LATER = "later sibling ran";
91+
8992
function isGitFailure(value: unknown): value is GitOperationError {
9093
return value instanceof GitOperationError;
9194
}
@@ -644,16 +647,32 @@ describe("workflow Git.Switch selection", () => {
644647
});
645648
});
646649

647-
it("fails outside a Repository rather than choosing one", function* () {
650+
it("fails outside a Repository rather than choosing one, past every region", function* () {
648651
const root = yield* useStorageRoot();
649652

650653
yield* withStorage(root, function* () {
651654
const database = yield* createRun();
652655
const failure = yield* raised(runDocument(database, `<Git.Switch branch="release" />`));
653656

654-
const refusal = causedBy(failure, isGitFailure);
655-
expect(refusal?.reason).toBe("no-repository-context");
657+
// No repository in scope is missing authority, not an outcome a document
658+
// asked for and did not get.
659+
expect(causedBy(failure, isAuthorityFailure)).toBeInstanceOf(GitOperationAuthorityError);
660+
expect(causedBy(failure, isGitFailure)).toBe(undefined);
656661
expect(yield* gitEvents(database)).toHaveLength(0);
662+
663+
// And an authored region cannot decide otherwise: a printed one would let
664+
// the siblings after it run as though a branch had moved.
665+
const printing = yield* createRun({ runId: "printing" });
666+
const printed = yield* raised(
667+
runDocument(
668+
printing,
669+
["<PrintErrors>", `<Git.Switch branch="release" />`, "", LATER, "</PrintErrors>"].join(
670+
"\n",
671+
),
672+
),
673+
);
674+
expect(causedBy(printed, isAuthorityFailure)).toBeInstanceOf(GitOperationAuthorityError);
675+
expect(yield* gitEvents(printing)).toHaveLength(0);
657676
});
658677
});
659678

‎specs/workflow-workspace-spec.md‎

Lines changed: 15 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -780,20 +780,25 @@ directory belongs to, and that directory is only where the operation runs.
780780
Neither observation carries authority. The Repository is compared with the row
781781
the run retained under that name, member for member, and the working directory
782782
has to be a real directory inside one of the checkouts the run retains for it.
783-
A Repository that is not the retained one, a directory inside no retained
784-
checkout, and retained state that no longer agrees with the identity naming it
785-
are failures of the run rather than outcomes: no Git runs, nothing is published,
786-
and `<PrintErrors>` cannot print them. The same is true of a native Git failure
787-
the provider has no word for — the refusals are a closed set, and an
788-
unrecognized one is infrastructure rather than the nearest word.
783+
No enclosing `<Repository>` at all, a Repository that is not the retained one, a
784+
directory inside no retained checkout, and retained state that no longer agrees
785+
with the identity naming it are failures of the run rather than outcomes: no Git
786+
runs, nothing is published, and `<PrintErrors>` cannot print them. The same is
787+
true of a native Git failure the provider has no word for — the refusals are a
788+
closed set, and an unrecognized one is infrastructure rather than the nearest
789+
word.
789790

790791
Switch renders nothing, binds nothing and takes no content. What it retains is
791792
evidence: the checkout it ran in, the requested and resolved branch, the
792793
requested base and the commit a created branch actually started from, and the
793-
branch, commit, HEAD tree and index tree the checkout held before and after. A
794-
retained result is read back for the invocation that recorded it, and one whose
795-
identity, branch, base or transition does not describe that invocation is
796-
damage rather than history.
794+
branch, commit, HEAD tree and index tree the checkout held before and after.
795+
796+
A retained result is read back for the invocation that recorded it, and one whose
797+
identity, branch, base or transition does not describe that invocation is damage
798+
rather than history. A Worktree's name and its path are one identity, held to the
799+
placement that produced them; and switching to the branch a checkout is already
800+
on moves nothing, so a result whose commit, HEAD tree or index tree changed
801+
across it describes a transition Switch does not make.
797802

798803
### 7.2 Add
799804

0 commit comments

Comments
 (0)