Skip to content

Commit 193b681

Browse files
committed
🔀 Switch a retained checkout's branch inside a workflow run
The first slice of #294. `<Git.Switch>` moves the branch of a checkout this run already retains, as one durable Workspace effect: ```md <Repository name="project" url={props.repository}> <Worktree name="implementation" branch={props.branch} as="worktree" /> <Dir path={worktree}> <Git.Switch branch="release/1.4" base="main" /> </Dir> </Repository> ``` There is no path prop and no repository prop. Which checkout moves is decided by where the element is written — the enclosing `<Repository>` names the repository and the contextual working directory names the checkout inside it — and neither observation carries authority. The provider rereads this run's own rows, holds each to the identity that names it, and refuses a working directory that is not one of them without running Git at all, so a replaced context selects nothing rather than selecting something else. Everything native Git sees is a disposable materialization exported from the Workspace inside the effect's own transaction. The Repository and every Worktree it retains are exported together, because Git decides what a repository's worktrees are by reading its own record of them and consults that record to refuse a branch another checkout holds. Retained identity is proven against what was exported — placement, origin, object format, creation commit, and a linked worktree's reciprocal administration — before the branch moves, and the family is canonicalized and imported back afterwards. What the run retains is evidence rather than a summary: the checkout it ran in, the requested and resolved branch, the requested base and the commit a created branch actually started from, and the branch, commit, HEAD tree and index tree the checkout held on both sides. It is parsed exactly on the way back in, so a retained result that is missing a member or carries an extra one stops a replay rather than being read around. An existing branch is switched to and its base is not consulted, because a base is what a branch is created from. A branch the remote published counts as existing, on the same terms `<Worktree>` already uses. Changes Git would overwrite and a branch checked out elsewhere are refusals — nothing is discarded, stashed, moved or forced — and each becomes the effect's failed durable result against a Workspace root that did not move. A host that cannot run Git, a Workspace that cannot retain what it produced, and retained state that disagrees with what is there are none of those, and stay fatal. The component is an ordinary registered default installed only where a Workspace is attached, so ordinary `xmd run` has neither the name nor a provider, and a repository-local component shadows it exactly as it would any other package's default. Schema, retained rows and the journal route are unchanged: a switch adds no table, no column and no second append.
1 parent f3d777d commit 193b681

25 files changed

Lines changed: 2582 additions & 56 deletions

‎architecture.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2083,7 +2083,7 @@ Status is measured against main.
20832083
| `xmd workflow start` / `xmd workflow resume` | starts or resumes a workflow run from the CLI, under the Deno entrypoints only | built on the #366 stack; both acquire #367's executor lock before any lifecycle transition |
20842084
| implicit workflow Workspace | retains provider-neutral filesystem, repository and attachment state by run ID | document filesystem built on the #366 stack and Repository/Worktree composition on the #293 stack; process capabilities unbuilt (#218) |
20852085
| `<Repository>` / `<Worktree>` / `<Dir>` composition | names a Git repository and its linked checkouts inside the run-owned Workspace, installs each as contextual working directory, and retains creation identity beside the retained Git bytes | built on the #293 stack, Deno provider only |
2086-
| transactional Git effects (`Git.Switch` / `Git.Add` / `Git.Commit`) | publish local Git mutations with their journal result | defined in `specs/workflow-workspace-spec.md`, unbuilt (#294) |
2086+
| transactional Git effects (`Git.Switch` / `Git.Add` / `Git.Commit`) | publish local Git mutations with their journal result; the enclosing Repository and the contextual working directory select which retained checkout one runs in, and neither observation carries authority over it | `Git.Switch` built on the #294 stack, Deno provider only; `Git.Add` and `Git.Commit` defined in `specs/workflow-workspace-spec.md`, unbuilt (#294) |
20872087
| workflow lifecycle inspection and control | reads status/list/history without advancing a run, enforces the executor lock, refuses live cancellation, cancels non-live runs under that lock and deletes retained state | built on the #367 stack |
20882088
| historical authored source | retains an authored durable operation's normalized `SourcePosition` beside its identity, and history parses it or refuses the entry | built on the #367 stack |
20892089
| history fork | creates a new run from one compatible checkpoint and retained Workspace root | defined in `specs/workflow-workspace-spec.md`, unbuilt (#368) |

‎packages/workflow/deno.ts‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,11 @@ export { hashRunId, workflowRunLock, workflowRunPath } from "./src/deno/path.ts"
3939
export { APPLICATION_ID, SCHEMA_VERSION } from "./src/deno/schema.ts";
4040
export { withWorkflowWorkspace } from "./src/deno/workspace/host.ts";
4141
export type { WorkflowWorkspaceOptions } from "./src/deno/workspace/host.ts";
42-
export { WORKSPACE_REPOSITORY, WORKSPACE_WORKTREE } from "./src/deno/composition/provider.ts";
42+
export {
43+
WORKSPACE_GIT_SWITCH,
44+
WORKSPACE_REPOSITORY,
45+
WORKSPACE_WORKTREE,
46+
} from "./src/deno/composition/provider.ts";
4347
export type {
4448
CompositionObserver,
4549
CompositionProviderOptions,

‎packages/workflow/mod.ts‎

Lines changed: 22 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -46,13 +46,20 @@ export type { RepositoryCompositionApi } from "./src/composition/api.ts";
4646
export { currentRepository, RepositoryContext } from "./src/composition/context.ts";
4747
export type { RepositoryContextApi } from "./src/composition/context.ts";
4848
export {
49+
GitCompositionProviderError,
50+
GitOperationError,
51+
GitOperationProtocolError,
4952
RepositoryCompositionError,
5053
RepositoryCompositionProtocolError,
5154
RepositoryCompositionProviderError,
5255
RepositoryStaleStateError,
5356
WorktreeCompositionError,
5457
} from "./src/composition/errors.ts";
55-
export type { RepositoryFailureReason, WorktreeFailureReason } from "./src/composition/errors.ts";
58+
export type {
59+
GitFailureReason,
60+
RepositoryFailureReason,
61+
WorktreeFailureReason,
62+
} from "./src/composition/errors.ts";
5663
export {
5764
parseRepositoryRecord,
5865
parseWorktreeRecord,
@@ -67,6 +74,20 @@ export type {
6774
WorktreeCreationRequest,
6875
WorktreeRecord,
6976
} from "./src/composition/records.ts";
77+
export { GitComposition } from "./src/composition/git-api.ts";
78+
export type { GitCompositionApi } from "./src/composition/git-api.ts";
79+
export {
80+
gitSwitchResultJson,
81+
parseGitCheckoutIdentity,
82+
parseGitCheckoutState,
83+
parseGitSwitchResult,
84+
} from "./src/composition/git-records.ts";
85+
export type {
86+
GitCheckoutIdentity,
87+
GitCheckoutState,
88+
GitSwitchRequest,
89+
GitSwitchResult,
90+
} from "./src/composition/git-records.ts";
7091
export { useCompositionComponents } from "./src/composition/installation.ts";
7192

7293
export { WorkspaceCoordination, WorkspaceCoordinationProviderError } from "./src/workspace/api.ts";
Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
/**
2+
* `<Git.Switch>` — put the contextual checkout on a named branch
3+
* (specs/workflow-workspace-spec.md §7.1).
4+
*
5+
* ```md
6+
* <Repository name="project" url={props.repository}>
7+
* <Git.Switch branch="release/1.4" base="main" />
8+
* </Repository>
9+
* ```
10+
*
11+
* There is no path prop, and there is no repository prop. Which checkout this
12+
* moves is decided by where it is written: the enclosing `<Repository>` names
13+
* the repository, and the contextual working directory names the checkout
14+
* inside it, so the same element inside a `<Dir path={worktree}>` moves that
15+
* linked worktree instead. Both are observations. This component holds no
16+
* authority over either, and the installed provider rereads what this run
17+
* retained rather than believing what it was handed.
18+
*
19+
* It renders nothing and binds nothing. A switch is a state change, not a value
20+
* a later element reads; what the run retains about it is journal evidence
21+
* rather than something a document could have used, and returning a branch name
22+
* a document already wrote would only invite reading it back as though it were
23+
* an answer.
24+
*
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.
33+
*/
34+
35+
import { cwd } from "@executablemd/runtime";
36+
import { hasContent } from "@executablemd/core";
37+
import type { Operation } from "effection";
38+
import type { Json } from "@executablemd/durable-streams";
39+
import { GitComposition } from "../git-api.ts";
40+
import { currentRepository } from "../context.ts";
41+
import { GitOperationError } from "../errors.ts";
42+
43+
/** The component name, as a document writes it and as a refusal names it. */
44+
export const SWITCH = "<Git.Switch>";
45+
46+
export const props = {
47+
type: "object",
48+
properties: {
49+
branch: { type: "string", minLength: 1 },
50+
base: { type: "string", minLength: 1 },
51+
},
52+
required: ["branch"],
53+
additionalProperties: false,
54+
};
55+
56+
function required(props: Record<string, Json>, prop: string): string {
57+
const value = props[prop];
58+
if (typeof value !== "string" || value === "") {
59+
throw new GitOperationError(
60+
SWITCH,
61+
"invalid-invocation",
62+
`${SWITCH} needs a non-empty ${prop}.`,
63+
);
64+
}
65+
return value;
66+
}
67+
68+
export default function* GitSwitch(props: Record<string, Json>): Operation<string> {
69+
const branch = required(props, "branch");
70+
const base = typeof props.base === "string" && props.base !== "" ? props.base : undefined;
71+
72+
// Content would have nowhere to go: this element renders nothing, so children
73+
// written inside it would expand into a result nobody reads. Refusing says so
74+
// where a document can still be corrected.
75+
if (yield* hasContent()) {
76+
throw new GitOperationError(
77+
SWITCH,
78+
"invalid-invocation",
79+
`${SWITCH} renders nothing, so it takes no content. Write it as ` +
80+
`<Git.Switch branch=${JSON.stringify(branch)} />.`,
81+
);
82+
}
83+
84+
const repository = yield* currentRepository();
85+
if (repository === undefined) {
86+
throw new GitOperationError(
87+
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.",
91+
);
92+
}
93+
94+
yield* GitComposition.operations.switchBranch({
95+
repositoryName: repository.name,
96+
checkoutPath: yield* cwd(),
97+
branch,
98+
base,
99+
});
100+
return "";
101+
}

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

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -121,3 +121,60 @@ export class RepositoryCompositionProtocolError extends WorkflowStorageError {
121121
);
122122
}
123123
}
124+
125+
/**
126+
* A word from the fixed vocabulary a Git operation's refusal is reported under.
127+
*
128+
* The same closed-set discipline the two composition components speak. A
129+
* document learns that its base named no commit, or that the branch it asked for
130+
* is checked out somewhere else — never which Git version said so, and never
131+
* what it printed.
132+
*/
133+
export type GitFailureReason =
134+
| "no-repository-context"
135+
| "invalid-invocation"
136+
| "not-a-checkout"
137+
| "invalid-branch"
138+
| "unresolved-base"
139+
| "branch-checked-out-elsewhere"
140+
| "overwrites-local-changes"
141+
| "unusable-repository";
142+
143+
/** A Git operation the document asked for and did not get. */
144+
export class GitOperationError extends Error {
145+
override name = "GitOperationError";
146+
147+
/** The component that was written, as a document writes it. */
148+
readonly operation: string;
149+
readonly reason: GitFailureReason;
150+
151+
constructor(operation: string, reason: GitFailureReason, sentence: string) {
152+
super(sentence);
153+
this.operation = operation;
154+
this.reason = reason;
155+
}
156+
}
157+
158+
/** No Git composition provider is installed in this scope. */
159+
export class GitCompositionProviderError extends WorkflowStorageError {
160+
override name = "GitCompositionProviderError";
161+
162+
constructor(operation: string) {
163+
super(
164+
`no Git composition provider is installed, so ${operation} cannot answer. A workflow ` +
165+
"host installs one for a live or partial execution.",
166+
);
167+
}
168+
}
169+
170+
/** The provider answered with something that is not a Git operation result. */
171+
export class GitOperationProtocolError extends WorkflowStorageError {
172+
override name = "GitOperationProtocolError";
173+
174+
constructor(operation: string) {
175+
super(
176+
`the Git composition provider answered ${operation} with a value that is not the result ` +
177+
"that operation retains.",
178+
);
179+
}
180+
}
Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
/**
2+
* The provider-neutral Api a transactional Git component asks for work through.
3+
*
4+
* `<Git.Switch>` names no subprocess and reaches no filesystem. It observes two
5+
* things a document can see — the enclosing `<Repository>` and the contextual
6+
* working directory — and asks whoever is installed to do the rest. Neither
7+
* observation carries authority: a replaced context can misname a Repository,
8+
* and the provider's answer is what decides which retained checkout, if any,
9+
* those two select.
10+
*
11+
* The default handler throws. There is no host-less fallback, because a Git
12+
* operation that "ran" without a provider would report a branch this run never
13+
* moved — and ordinary `xmd run` installs none, so a document written for a
14+
* workflow fails there rather than quietly touching a checkout in the caller's
15+
* own filesystem.
16+
*/
17+
18+
import { type Api, createApi } from "@effectionx/context-api";
19+
import type { Operation } from "effection";
20+
import { GitCompositionProviderError } from "./errors.ts";
21+
import type { GitSwitchRequest, GitSwitchResult } from "./git-records.ts";
22+
23+
export interface GitCompositionApi {
24+
/**
25+
* Put the selected checkout on a named branch, as one durable effect.
26+
*
27+
* A completed one restores its retained result: replay changes no branch and
28+
* spawns no Git.
29+
*/
30+
switchBranch(request: GitSwitchRequest): Operation<GitSwitchResult>;
31+
}
32+
33+
export const GitComposition: Api<GitCompositionApi> = createApi<GitCompositionApi>(
34+
"executablemd.workflow.composition.git",
35+
{
36+
// deno-lint-ignore require-yield
37+
*switchBranch(_request: GitSwitchRequest): Operation<GitSwitchResult> {
38+
throw new GitCompositionProviderError("<Git.Switch>");
39+
},
40+
},
41+
);

0 commit comments

Comments
 (0)