Skip to content

Commit 7b393a2

Browse files
authored
📥 Stage exactly the paths a document names (#477)
* 📥 Stage exactly the paths a document names The second slice of #294. `<Git.Add>` stages the pathspecs a document writes, in the checkout it writes them in, as one durable Workspace effect: ```md <Repository name="project" url={props.repository}> <File path="release/notes.md">…</File> <Git.Add paths={["release/notes.md", "deno.lock"]} /> </Repository> ``` `paths` is a Git pathspec and nothing else. It does not choose a checkout — that is decided the way every Git operation's place is decided, by the enclosing `<Repository>` and the contextual working directory — and it is never optional: omitting it does not mean everything, and `"."` is how a document says everything *here*. "Here" is the directory the element was written in, so a staging inside `<Dir path="nested">` reaches that directory and not the checkout above it. What a document wrote is what Git receives. One string is the one-entry array, and an array keeps its order, its repetitions, its spelling and its pathspec magic, because each of those changes what is staged. The whole array is one command and one effect: Git decides what a pathspec matches, and staging entry by entry would be several transitions where the document wrote one. Git applies the command or none of it, so a refused pathspec leaves the index exactly as it was. The retained result is evidence: the checkout, the pathspecs as given, and both readings of the checkout. Staging moves the index and nothing else, so a result whose branch, commit or HEAD tree changed across it is damage — while its index tree may have moved or not, because staging what is already staged changes nothing. What Git matched is deliberately not enumerated: naming files it discovered would put content beyond the document's own pathspecs into retained history. Everything the substrate already owned is reused rather than re-decided: the whole observed Repository record is authenticated against the retained row, the working directory selects the longest matching checkout and is proven to be a real directory inside it, the family is materialized and imported together, and the effect's identity uses the injective Git-operation fingerprint over every record member, the working directory and each pathspec in turn. Native staging failures are infrastructure for now. The conditions a document could act on — a pathspec that matched nothing, one the repository ignores, one outside the checkout, one whose magic is invalid — are recognizable and their evidence is recorded in the handoff, but which of them becomes a durable refusal is a product decision this slice does not make on an author's behalf. * 🚫 Refuse the four pathspec conditions a document can act on The Planner settled the classification PR B left open. A pathspec that matched no files, one that selects an ignored path, one that leaves the checkout and one whose Git pathspec magic is invalid are each deterministic, authored and actionable, so each is now a `GitOperationError` outcome — one failed durable result against a Workspace root that did not move, replayed exactly — rather than a run-ending infrastructure failure. Any other native exit stays infrastructure; the classifier matches the exit status and the message together, so a later Git version's unrelated failure cannot wear a word this run does not mean. The review's atomicity premise is correct and my earlier claim was not. Verified against real Git: `git add -- added.txt ignored.txt` stages `added.txt` and *then* exits 1, while the three exit-128 conditions stage nothing. So native Git does not give all-or-none semantics, and the comment saying it did is replaced by what actually provides them — the refusal is thrown before anything is imported, the disposable materialization goes with the scope, and the attempt is rolled back, so the Workspace never holds a partial staging. Nothing a refusal carries comes from Git. Each sentence names its condition and neither quotes stderr nor reports a path, a host directory, or a file Git discovered. Five new rows drive the four conditions through real Git and assert their exact public reasons; two more prove the mixed ignored-path case retains none of the partial staging, that its failed result stands against the unchanged root, and that replaying it reproduces the same sentence with no Git, no second event and no new root. The ignored-path classification is mutation-checked. * 🎯 Classify an Add refusal by Git's frame, not by a phrase in it Git puts the pathspec it is complaining about inside its own diagnostic, so the message this reads contains a document's own text. Searching that message for a phrase let the text answer the question: `paths="../did not match any files"` produced an outside-repository diagnostic that contains the unmatched phrase and was reported as `unmatched-pathspec`, and `:(did not match any files)which.txt` did the same through the invalid-magic diagnostic. Both are confirmed against real Git. Nothing searches now. Each condition has a fixed frame Git builds around the pathspec, and the pathspecs are what this provider just sent, so the frame is reconstructed for each of them and compared: fatal: pathspec '<sent>' did not match any files fatal: <sent>: '<sent>' is outside repository at '<root>' fatal: Invalid pathspec magic '<magic>' in '<sent>' plus the ignored advisory, which names no path at all. A document may put any text it likes inside a frame; it cannot make one condition's diagnostic take another condition's shape around its own text. The exit status is still part of the match, only the line Git led with is read, and a diagnostic that fits no frame remains infrastructure. Both reproducers are regressions, and restoring the substring classifier fails exactly those two. * 📏 Read a Git diagnostic as a message, not as a line A pathspec is any non-empty string, newlines included, and Git embeds it verbatim — so the frame comparison read only as far as the pathspec's own first newline. Confirmed against real Git: `git add -- $'missing\nfile'` exits 128 and writes fatal: pathspec 'missing file' did not match any files which truncation reduced to `fatal: pathspec 'missing`. That fits no frame, so a known refusal became an infrastructure failure: the run ended, and no failed durable result was published or replayable. The whole of what Git wrote is now compared, less the single newline it ends with — trimming further would take characters a pathspec is allowed to end with. The ignored advisory keeps its own rule: it leads the message and the paths Git found follow it, so what is matched is that first line and nothing after it, none of which is Git's own words. Nothing about the component changes. A newline-bearing pathspec is accepted, passed to Git unchanged, retained in the result exactly as written, and refused under the word its condition earns. The regression drives it through real Git, and restoring first-line truncation fails exactly that row while every other refusal keeps passing. * 🔤 Refuse a pathspec this host cannot hand to Git as written A JavaScript string is UTF-16 code units and need not be well-formed text, but the way to Git is UTF-8: an unpaired surrogate becomes U+FFFD in the argument list. Confirmed directly — `"\ud800"` reaches a child process as `ef bf bd`. So a document asking for `"\ud800"` had a checkout's U+FFFD-named file staged, while the effect identity and the retained result still said `"\ud800"`: one history, another index. The settled contract is that an accepted pathspec's spelling is exactly what Git receives, and this host cannot keep that promise for ill-formed UTF-16. Such a pathspec is therefore malformed input, refused before an identity is built and before anything is spawned. `admitPathspecs()` is applied where a document writes a request *and* inside the provider, because the composition Api is public and a caller reaching it directly is subject to the same boundary. Nothing is normalized, respelled or dropped: every well-formed string — U+FFFD included, along with newlines, separators, repetitions and pathspec magic — still reaches Git exactly as written. Four regressions, with the checkout really holding a U+FFFD-named file so the substitution would have been observable: a leading surrogate and a trailing one each refused with no Git, no journal entry and nothing staged; the same refusal through a direct Api call; and a positive control staging that file for an actual U+FFFD pathspec. Disabling the check fails the three refusals and leaves the control passing. `stagedPaths()` now reads `-z` output, because Git quotes a path holding anything outside ASCII and a suite has to compare the name the Workspace holds. * 🧊 Run a staging on the request it admitted, not on the caller's objects `admitPathspecs()` returned a frozen snapshot and the operation threw it away, carrying on with the caller's own array. A `string[]` is assignable to `readonly string[]`, and this operation suspends several times before Git is spawned — a command, a transaction, an import — so whoever handed the array over could still change it. The effect could then identify one pathspec sequence, hand Git a second and retain a third, and a pathspec mutated to an unpaired surrogate would walk straight back into the substitution that was refused a commit ago. `createGitAdd()` now builds one admitted request and everything runs on it: the description, the effect, the Git arguments, the result and its parse, and the placement check. The Repository record is snapshotted with it, for the same reason and against the same hazard — a caller's record could otherwise change between the identity that names an effect and the authentication that admits it. `describeAdd()` and `performGitAdd()` are no longer exported, so `createGitAdd()` is the only door and nothing downstream can be handed values that still move. The regression drives the direct Api with a mutable array and mutates it from the host at the point Git reads the index tree — the last command before staging, long after the identity was built — with a U+FFFD-named file present so a substitution would stage something. Git receives `original.txt`, only that file is staged, and the retained result and the effect's own configuration fingerprint both say `original.txt`. Returning to validation-only fails exactly that test. --------- Co-authored-by: Taras Mankovski <[email protected]>
1 parent de3068e commit 7b393a2

23 files changed

Lines changed: 2666 additions & 67 deletions

‎architecture.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2108,7 +2108,7 @@ Status is measured against main.
21082108
| `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 |
21092109
| 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) |
21102110
| `<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 |
2111-
| 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 — the observed record is compared with the retained row and the directory with the checkouts that row holds, so a failure of authority, of retained state or of an unrecognized native condition fails the run instead of publishing a result | `Git.Switch` built on the #294 stack, Deno provider only; `Git.Add` and `Git.Commit` defined in `specs/workflow-workspace-spec.md`, unbuilt (#294) |
2111+
| 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 — the observed record is compared with the retained row and the directory with the checkouts that row holds, so a failure of authority, of retained state or of an unrecognized native condition fails the run instead of publishing a result | `Git.Switch` and `Git.Add` built on the #294 stack, Deno provider only; `Git.Commit` defined in `specs/workflow-workspace-spec.md`, unbuilt (#294) |
21122112
| 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 |
21132113
| 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 |
21142114
| 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: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ 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";
4242
export {
43+
WORKSPACE_GIT_ADD,
4344
WORKSPACE_GIT_SWITCH,
4445
WORKSPACE_REPOSITORY,
4546
WORKSPACE_WORKTREE,

‎packages/workflow/mod.ts‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,14 +77,21 @@ export type {
7777
export { GitComposition } from "./src/composition/git-api.ts";
7878
export type { GitCompositionApi } from "./src/composition/git-api.ts";
7979
export {
80+
gitAddResultJson,
8081
gitSwitchResultJson,
82+
parseGitAddResult,
8183
parseGitCheckoutIdentity,
8284
parseGitCheckoutState,
8385
parseGitSwitchResult,
8486
} from "./src/composition/git-records.ts";
8587
export type {
88+
GitAddExpectation,
89+
GitAddRequest,
90+
GitAddResult,
91+
GitCheckoutExpectation,
8692
GitCheckoutIdentity,
8793
GitCheckoutState,
94+
GitSwitchExpectation,
8895
GitSwitchRequest,
8996
GitSwitchResult,
9097
} from "./src/composition/git-records.ts";
Lines changed: 150 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,150 @@
1+
/**
2+
* `<Git.Add>` — stage exactly the paths a document names
3+
* (specs/workflow-workspace-spec.md §7.2).
4+
*
5+
* ```md
6+
* <Repository name="project" url={props.repository}>
7+
* <Git.Add paths="release/notes.md" />
8+
* <Git.Add paths={["packages/core", "deno.lock"]} />
9+
* </Repository>
10+
* ```
11+
*
12+
* `paths` is a Git pathspec, and that is all it is. It does not choose a
13+
* checkout — where this stages is decided the way every Git operation's place is
14+
* decided, by the enclosing `<Repository>` and the contextual working directory
15+
* — and it is never optional. Omitting it does not mean everything; `"."` is how
16+
* a document says everything here, and "here" is the directory the element was
17+
* written in, so `<Git.Add paths="." />` inside a `<Dir path="packages">` stages
18+
* that directory rather than the checkout.
19+
*
20+
* What a document wrote is what Git receives. One string is the one-entry array,
21+
* and an array keeps its order, its repetitions, its spelling and its pathspec
22+
* magic, because each of those changes what Git stages. The whole array is one
23+
* command and one effect: Git decides what a pathspec matches, and staging entry
24+
* by entry would be several transitions where the document wrote one.
25+
*
26+
* It renders nothing, binds nothing and takes no content. What the run retains
27+
* is journal evidence — the pathspecs, and the checkout on both sides — rather
28+
* than anything a later element could read.
29+
*
30+
* Failure policy is `<Git.Switch>`'s. An invocation this cannot read is a fixed
31+
* `GitOperationError`; no Repository in scope is missing authority and travels
32+
* past every printing boundary, because a document that continued past one would
33+
* run later siblings as though something had been staged.
34+
*/
35+
36+
import { cwd } from "@executablemd/runtime";
37+
import { hasContent } from "@executablemd/core";
38+
import type { PropsSchema } from "@executablemd/core";
39+
import type { Operation } from "effection";
40+
import type { Json } from "@executablemd/durable-streams";
41+
import { GitComposition } from "../git-api.ts";
42+
import { currentRepository } from "../context.ts";
43+
import { GitOperationAuthorityError, GitOperationError } from "../errors.ts";
44+
import { wellFormedText } from "../parse.ts";
45+
46+
/** The component name, as a document writes it and as a failure names it. */
47+
export const ADD = "<Git.Add>";
48+
49+
// Annotated rather than inferred: a heterogeneous `anyOf` widens to member
50+
// types carrying `undefined`, which is not JSON.
51+
export const props: PropsSchema = {
52+
type: "object",
53+
properties: {
54+
paths: {
55+
anyOf: [
56+
{ type: "string", minLength: 1 },
57+
{ type: "array", minItems: 1, items: { type: "string", minLength: 1 } },
58+
],
59+
},
60+
},
61+
required: ["paths"],
62+
additionalProperties: false,
63+
};
64+
65+
function invalid(sentence: string): never {
66+
throw new GitOperationError(ADD, "invalid-invocation", `${ADD} ${sentence}`);
67+
}
68+
69+
/**
70+
* The pathspec array this invocation names.
71+
*
72+
* A string is the one-entry array and nothing else is inferred: an empty string,
73+
* an empty array and an empty entry are all refused rather than read as "here"
74+
* or as "everything", because both are things a document says explicitly.
75+
*/
76+
export function canonicalPaths(value: Json | undefined): readonly string[] {
77+
if (typeof value === "string") {
78+
return admitPathspecs([value]);
79+
}
80+
if (!Array.isArray(value)) {
81+
return invalid("needs a paths pathspec, as one string or an array of them.");
82+
}
83+
if (value.length === 0) {
84+
return invalid("needs at least one pathspec. Omitting paths never means every path.");
85+
}
86+
const paths: string[] = [];
87+
for (const entry of value) {
88+
if (typeof entry !== "string") {
89+
return invalid("needs every pathspec to be a non-empty string.");
90+
}
91+
paths.push(entry);
92+
}
93+
return admitPathspecs(paths);
94+
}
95+
96+
/**
97+
* The pathspecs, once each is one a host can hand to Git unchanged.
98+
*
99+
* Every entry keeps its spelling — that is the whole contract — so an entry no
100+
* boundary can carry without changing it is refused rather than sent. A string
101+
* holding an unpaired surrogate is the case: a process argument list is UTF-8,
102+
* and what Git would receive is U+FFFD while the run's history would still say
103+
* what the document wrote. Nothing is normalized, respelled or dropped to make
104+
* one fit.
105+
*
106+
* Applied wherever a request enters, not only where a document writes one: the
107+
* Api is public, and a caller reaching it directly is subject to the same
108+
* boundary.
109+
*/
110+
export function admitPathspecs(paths: readonly string[]): readonly string[] {
111+
if (paths.length === 0) {
112+
return invalid("needs at least one pathspec. Omitting paths never means every path.");
113+
}
114+
for (const path of paths) {
115+
if (path === "") {
116+
return invalid("needs every pathspec to be a non-empty string.");
117+
}
118+
if (!wellFormedText(path)) {
119+
return invalid(
120+
"needs every pathspec to be well-formed text. One of them holds an unpaired surrogate, " +
121+
"which this host cannot hand to Git as written.",
122+
);
123+
}
124+
}
125+
return Object.freeze([...paths]);
126+
}
127+
128+
export default function* GitAdd(props: Record<string, Json>): Operation<string> {
129+
const paths = canonicalPaths(props.paths);
130+
131+
if (yield* hasContent()) {
132+
invalid("renders nothing, so it takes no content. Write it as <Git.Add paths=… />.");
133+
}
134+
135+
const repository = yield* currentRepository();
136+
if (repository === undefined) {
137+
throw new GitOperationAuthorityError(
138+
ADD,
139+
"it is written outside a lexical <Repository>, so there is no repository in scope to " +
140+
"stage anything in",
141+
);
142+
}
143+
144+
yield* GitComposition.operations.addPaths({
145+
repository,
146+
workingDirectory: yield* cwd(),
147+
paths,
148+
});
149+
return "";
150+
}

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

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -135,7 +135,11 @@ export type GitFailureReason =
135135
| "invalid-branch"
136136
| "unresolved-base"
137137
| "branch-checked-out-elsewhere"
138-
| "overwrites-local-changes";
138+
| "overwrites-local-changes"
139+
| "unmatched-pathspec"
140+
| "ignored-pathspec"
141+
| "outside-checkout-pathspec"
142+
| "invalid-pathspec-magic";
139143

140144
/** A Git operation the document asked for and did not get. */
141145
export class GitOperationError extends Error {

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

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,12 @@
1818
import { type Api, createApi } from "@effectionx/context-api";
1919
import type { Operation } from "effection";
2020
import { GitCompositionProviderError } from "./errors.ts";
21-
import type { GitSwitchRequest, GitSwitchResult } from "./git-records.ts";
21+
import type {
22+
GitAddRequest,
23+
GitAddResult,
24+
GitSwitchRequest,
25+
GitSwitchResult,
26+
} from "./git-records.ts";
2227

2328
export interface GitCompositionApi {
2429
/**
@@ -28,6 +33,15 @@ export interface GitCompositionApi {
2833
* spawns no Git.
2934
*/
3035
switchBranch(request: GitSwitchRequest): Operation<GitSwitchResult>;
36+
37+
/**
38+
* Stage exactly the pathspecs this request names, as one durable effect.
39+
*
40+
* One command for the whole array rather than one per entry: Git decides what
41+
* a pathspec matches, and a per-entry loop would be several transitions where
42+
* the document wrote one.
43+
*/
44+
addPaths(request: GitAddRequest): Operation<GitAddResult>;
3145
}
3246

3347
export const GitComposition: Api<GitCompositionApi> = createApi<GitCompositionApi>(
@@ -37,5 +51,9 @@ export const GitComposition: Api<GitCompositionApi> = createApi<GitCompositionAp
3751
*switchBranch(_request: GitSwitchRequest): Operation<GitSwitchResult> {
3852
throw new GitCompositionProviderError("<Git.Switch>");
3953
},
54+
// deno-lint-ignore require-yield
55+
*addPaths(_request: GitAddRequest): Operation<GitAddResult> {
56+
throw new GitCompositionProviderError("<Git.Add>");
57+
},
4058
},
4159
);

0 commit comments

Comments
 (0)