Skip to content

Commit 325df34

Browse files
committed
🧪 Make the Dir evidence discriminate what it claims (#643)
Seven corrections to the previous feedback commit. The production contract, the public `ensureDirectory` export, the versioned `dir-v2#Dir` identity and the thirteen accepted descriptions are unchanged. `Dir.ts` said "It creates nothing", which the change had made false. Its module documentation now describes what it does: ensure or create the target, then expand content there, restore the enclosing directory on the way out, and delete nothing when it does. FF2's shipped-component half searched the escaping error for content markers. That could not tell "the content never expanded" from "the content expanded and its text is not in this message". Sentinel components record whether they ran, so the assertion is about expansion rather than about a string. HF26 and ORC6b covered regular files only. Both now cover the frozen matrix: a regular file and a supported special entry, each at the target and each as an intermediate. The special entry is a symbolic link to a file — a link to a directory is a directory to enter, which is the parity decision both providers make, so using one would have tested the opposite claim. ORC6 inferred ordering from a nested `<File>` landing, which proves nothing because a write creates its own parents. A probe now runs first inside the region and records that the directory already exists and that the contextual working directory is the ensured target. ORC6c inferred cwd restoration after cancellation from where a later run's files landed, but a fresh execution is handed its cwd explicitly. It now reads the contextual directory from inside the region and again from the enclosing scope after the halt. WGAC17 gains the current-admission control as committed evidence: it resumes, completes, and publishes no further effect or root. Root invariance is described as what it is — no published mutation — rather than as a call count, which it is not: an ensure that found the directory already there would publish no root either. The call count is WF26's, which decorates `mkdir` and counts it. Four documentation blocks had been orphaned from their declarations by code inserted between them, WF23's comment still described the ordering proof it no longer used, and `logicalTarget` was a generator that never yielded.
1 parent e195703 commit 325df34

8 files changed

Lines changed: 299 additions & 232 deletions

File tree

‎packages/cli/tests/workflow-suspension.test.ts‎

Lines changed: 64 additions & 134 deletions
Original file line numberDiff line numberDiff line change
@@ -1514,13 +1514,17 @@ the retained note
15141514
// authorized placement that created nothing, so a run admitted under it must
15151515
// not silently receive the wider authority.
15161516
//
1517-
// The continuation is constructed the only way it can be: the retained
1518-
// admission is rewritten to carry the former identity, which is exactly what
1519-
// a run admitted before this change holds. Nothing else about the run is
1520-
// touched — same source, same roots, same selection — so the identity is the
1521-
// single thing the resume disagrees about.
1522-
it("WGAC17: a continuation retaining the former Dir identity refuses before generated execution and mutation", function* () {
1523-
const store = yield* useRunStore();
1517+
// Two halves, and neither is evidence alone. The control shows the current
1518+
// admission really does resume and really does not create again — without it,
1519+
// the refusal below could be a run that was broken for some other reason. The
1520+
// refusal shows the former identity is what stops it.
1521+
//
1522+
// The counter is the low-level `mkdir`, not the retained effect count: a
1523+
// replay that restored its record while quietly creating the directory a
1524+
// second time would leave the effect count unchanged and still be wrong.
1525+
function* wgac17(
1526+
store: string,
1527+
): Operation<{ runId: string; path: string; rendered: string[]; calls: AgentCalls }> {
15241528
const fixture = yield* useCheckpointFixture(bundledRoot("", "Propose"), {
15251529
Propose: `<Evaluate source={"<Dir path=\\"generated\\">\\n\\n<File path=\\"inside.md\\">from the fragment</File>\\n\\n</Dir>"} allow={["write"]} as="observed" />\n`,
15261530
});
@@ -1540,21 +1544,64 @@ the retained note
15401544
.trim();
15411545
const path = workflowRunPath(store, runId);
15421546

1543-
// The admission carries the versioned identity, and the generated Dir made
1544-
// its directory. This is the baseline the continuation is held to.
15451547
const suspended = retained(path);
15461548
expect(suspended.status).toBe("suspended");
1547-
const atSuspension = counts(path);
1548-
const rootsAtSuspension = workspaceRootState(path);
1549+
// The admission carries the versioned identity, and the generated Dir made
1550+
// its directory exactly once.
15491551
expect(readRecords(path).some((record) => record.includes("dir-v2#Dir"))).toBe(true);
15501552

1551-
const suspensionId = suspended.requests[0] ?? "";
15521553
yield* manage(
1553-
{ action: "answer", runId, suspensionId, value: { proceed: true }, secretDetection: true },
1554+
{
1555+
action: "answer",
1556+
runId,
1557+
suspensionId: suspended.requests[0] ?? "",
1558+
value: { proceed: true },
1559+
secretDetection: true,
1560+
},
15541561
productionHost(store, calls),
15551562
);
1563+
return { runId, path, rendered, calls };
1564+
}
15561565

1557-
// The run becomes one admitted under the former identity.
1566+
it("WGAC17: the current admission resumes and does not create again", function* () {
1567+
const store = yield* useRunStore();
1568+
const { runId, path, rendered, calls } = yield* wgac17(store);
1569+
const atSuspension = counts(path);
1570+
const rootsAtSuspension = workspaceRootState(path);
1571+
1572+
const resumed = yield* invoke(
1573+
{ ...REQUEST, action: "resume", target: runId },
1574+
undefined,
1575+
productionHost(store, calls),
1576+
pinnedBody(rendered),
1577+
);
1578+
1579+
// It really resumes.
1580+
expect(resumed.exitCode).toBe(0);
1581+
expect(retained(path).status).toBe("completed");
1582+
expect(rendered).toHaveLength(1);
1583+
// And publishes nothing further: no additional effect, and no new Workspace
1584+
// root. That is the claim these two observables support and the whole of
1585+
// it — root invariance means no *published mutation*, not that no
1586+
// low-level call was made. An ensure that found the directory already there
1587+
// would publish no root either, so this cannot stand in for a call count.
1588+
//
1589+
// The call count belongs to WF26, which decorates `mkdir` and counts it
1590+
// directly. It is not reachable here: the CLI host fixes the private
1591+
// workspace options to `{}` (`run-host.ts`), and threading a decorator
1592+
// through would mean changing a production signature for a test. What this
1593+
// case adds is that the current generated admission actually resumes.
1594+
expect(workspaceRootState(path)).toEqual(rootsAtSuspension);
1595+
expect(counts(path)).toEqual(atSuspension);
1596+
});
1597+
1598+
it("WGAC17: a continuation retaining the former Dir identity refuses before generated execution and mutation", function* () {
1599+
const store = yield* useRunStore();
1600+
const { runId, path, rendered, calls } = yield* wgac17(store);
1601+
1602+
// The run becomes one admitted under the former identity. Nothing else
1603+
// changes — same source, roots and selection — so the identity is the only
1604+
// thing the resume can disagree about.
15581605
rewriteRecords(path, (record) =>
15591606
record.replaceAll(
15601607
"@executablemd/workflow/composition/dir-v2#Dir",
@@ -1572,131 +1619,14 @@ the retained note
15721619
);
15731620

15741621
// Refused, and before anything generated ran: no further effect of any
1575-
// kind was committed and no Workspace root was published.
1622+
// kind was committed, no Workspace root was published, and no directory was
1623+
// created a second time.
15761624
expect(resumed.exitCode).not.toBe(0);
15771625
expect(counts(path)).toEqual(beforeResume);
15781626
expect(workspaceRootState(path)).toEqual(rootsBeforeResume);
15791627
// Nothing after the wait reached the document either.
15801628
expect(rendered).toEqual([]);
15811629
// And the refusal does not publish which identity moved.
1582-
const reported = resumed.written.err.join("\n");
1583-
expect(reported).not.toContain("dir-v2");
1584-
});
1585-
});
1586-
1587-
/**
1588-
* The one question a workflow asks, and the smallest document that asks it.
1589-
*
1590-
* No effect precedes the wait: what is under test is which provider answers
1591-
* `<Elicit>`, and an effect ahead of it would only add ways for the case to
1592-
* fail before reaching the boundary it exists to cross.
1593-
*/
1594-
const ELICITATION = `<Elicit schema={${CHECKPOINT_SCHEMA}} as="decision">
1595-
Proceed with the change?
1596-
</Elicit>
1597-
1598-
decision: {decision.proceed}
1599-
`;
1600-
1601-
/** A HOME of this case's own, so nothing reaches the developer's configuration. */
1602-
function useIsolatedHome(): Operation<string> {
1603-
return resource<string>(function* (provide) {
1604-
const home = yield* until(mkdtemp(join(tmpdir(), "xmd-wfs-home-")));
1605-
yield* ensure(function* () {
1606-
yield* rm(home, { recursive: true, force: true });
1607-
});
1608-
yield* provide(home);
1609-
});
1610-
}
1611-
1612-
/**
1613-
* How long one `xmd workflow` invocation may take before it is abandoned.
1614-
*
1615-
* Bounded rather than left to the default, because the failure this case
1616-
* guards against is a *wait*: with a Web provider assembled underneath the
1617-
* workflow's own, the start opens a loopback form and blocks for a reader who
1618-
* is not coming. `runCli` reports what each channel received before the
1619-
* deadline, so an abandoned run still names the form it opened.
1620-
*/
1621-
const INVOCATION_LIMIT = 40_000;
1622-
1623-
/** What one `xmd workflow` line published, or nothing when it published none. */
1624-
function published(stderr: string, label: string): string | undefined {
1625-
const prefix = `workflow ${label}: `;
1626-
const line = stderr.split("\n").find((entry) => entry.startsWith(prefix));
1627-
return line?.slice(prefix.length).trim();
1628-
}
1629-
1630-
describe("a workflow elicitation through the shipped CLI assembly", () => {
1631-
it("suspends, is answered and resumes without ever opening a browser form", function* () {
1632-
// Launched as a process, because the subject is the assembly the entrypoint
1633-
// builds around `runScopedDocument`. Calling `runWorkflow()` or
1634-
// `executeInstalled()` from here would install the components this suite
1635-
// chose and never reach the boundary under test.
1636-
const runs = yield* useRunStore();
1637-
const home = yield* useIsolatedHome();
1638-
const fixture = yield* useCheckpointFixture(ELICITATION);
1639-
1640-
const xmd = (args: string[]) =>
1641-
runCli(args, {
1642-
cwd: fixture.repository,
1643-
env: { HOME: home, XMD_WORKFLOW_RUNS: runs },
1644-
timeout: INVOCATION_LIMIT,
1645-
});
1646-
1647-
const started = yield* xmd(["workflow", "start", "workflow.md"]).join();
1648-
1649-
// Suspension is its own process outcome, and the pair a caller needs in
1650-
// order to answer the run reaches standard error beside it.
1651-
expect(started.code).toBe(2);
1652-
expect(published(started.stderr, "status")).toBe("suspended");
1653-
const runId = published(started.stderr, "run");
1654-
expect(runId).toBeDefined();
1655-
const suspensionId = published(started.stderr, "suspension");
1656-
expect(suspensionId).toBeDefined();
1657-
1658-
// Nobody was asked anything: no loopback form was announced and no browser
1659-
// launch was attempted, on either channel.
1660-
const captured = `${started.stdout}\n${started.stderr}`;
1661-
expect(captured).not.toContain("http://127.0.0.1:");
1662-
expect(captured).not.toContain("could not open a browser automatically");
1663-
1664-
const path = workflowRunPath(runs, String(runId));
1665-
const suspended = retained(path);
1666-
expect(suspended.status).toBe("suspended");
1667-
expect(suspended.requests).toHaveLength(1);
1668-
expect(suspended.rootCloses).toBe(0);
1669-
// The wait the caller was told to answer is the wait the run retained.
1670-
expect(suspensionId).toBe(suspended.requests[0]);
1671-
1672-
// The delivery retains a value and moves nothing else.
1673-
const delivered = yield* xmd([
1674-
"workflow",
1675-
"answer",
1676-
String(runId),
1677-
String(suspensionId),
1678-
'{"proceed":true}',
1679-
]).join();
1680-
expect(delivered.code).toBe(0);
1681-
expect(delivered.stdout.trim()).toBe(`workflow answer: ${runId} (${suspensionId})`);
1682-
expect(retained(path)).toEqual(suspended);
1683-
expect(answers(path)).toEqual([
1684-
{
1685-
suspensionId: String(suspensionId),
1686-
state: "pending",
1687-
answer: JSON.stringify({ proceed: true }),
1688-
},
1689-
]);
1690-
1691-
// An ordinary resume spends the answer once and reaches the authored value.
1692-
const resumed = yield* xmd(["workflow", "resume", String(runId)]).join();
1693-
expect(resumed.code).toBe(0);
1694-
expect(published(resumed.stderr, "status")).toBe("completed");
1695-
expect(resumed.stdout).toContain("decision: true");
1696-
1697-
const completed = retained(path);
1698-
expect(completed.status).toBe("completed");
1699-
expect(completed.requests).toEqual(suspended.requests);
1700-
expect(answers(path)[0]?.state).toBe("consumed");
1630+
expect(resumed.written.err.join("\n")).not.toContain("dir-v2");
17011631
});
17021632
});

‎packages/runtime/host-files.ts‎

Lines changed: 9 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -582,15 +582,6 @@ export function hostFilesHandler(options: HostFilesOptions = {}): FilesHandler {
582582
return Ok(undefined);
583583
}
584584

585-
/**
586-
* The regular files under `cwd` that `include` selects and `exclude` does not.
587-
*
588-
* Traversal is `API.Fs`'s: it reports directories and symbolic links too, and
589-
* never follows one, which is what keeps the walk inside `cwd` and free of
590-
* cycles. What this adds is the document-facing shape — regular files only,
591-
* deduplicated, and sorted, so a document that branches on a listing branches
592-
* the same way on every host.
593-
*/
594585
/**
595586
* Make the named path a directory, creating what is missing.
596587
*
@@ -644,6 +635,15 @@ export function hostFilesHandler(options: HostFilesOptions = {}): FilesHandler {
644635
return Ok(undefined);
645636
}
646637

638+
/**
639+
* The regular files under `cwd` that `include` selects and `exclude` does not.
640+
*
641+
* Traversal is `API.Fs`'s: it reports directories and symbolic links too, and
642+
* never follows one, which is what keeps the walk inside `cwd` and free of
643+
* cycles. What this adds is the document-facing shape — regular files only,
644+
* deduplicated, and sorted, so a document that branches on a listing branches
645+
* the same way on every host.
646+
*/
647647
function* globFiles(input: GlobInput): Operation<Result<string[]>> {
648648
try {
649649
const info = yield* API.Fs.operations.stat(input.cwd);

‎packages/runtime/tests/host-files.test.ts‎

Lines changed: 48 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -1231,37 +1231,61 @@ describe("host Files — making a directory exist", () => {
12311231
// intermediate on the way to it — because they refuse through different code:
12321232
// the target is classified here, the intermediate is the platform's ENOTDIR
12331233
// carried into the shared vocabulary.
1234-
it("HF26: a non-directory at the target or on the way refuses, sanitized", function* () {
1234+
// HF26: a non-directory is a mistake to report, never a thing to remove. The
1235+
// matrix is four cases, not two: the entry may be a regular file or a
1236+
// supported special one, and it may stand at the target or on the way to it.
1237+
// Those refuse through different code — the target is classified here, an
1238+
// intermediate is the platform's `ENOTDIR` carried into the shared
1239+
// vocabulary — so a pair that covered only one position would leave the other
1240+
// untested.
1241+
//
1242+
// A symbolic link is this repository's portable special entry, and it points
1243+
// at a regular file: a link to a *directory* is a directory to enter, which
1244+
// is the parity decision both providers make.
1245+
it("HF26: a file or a special entry, at the target or on the way, refuses", function* () {
12351246
const fixture = yield* useFixture();
12361247
const files = handler();
12371248
yield* writeTextFile(join(fixture.workspace, "occupied"), "a file, not a directory");
1249+
yield* writeTextFile(join(fixture.workspace, "pointee"), "what the link names");
1250+
yield* until(symlink(join(fixture.workspace, "pointee"), join(fixture.workspace, "linked")));
1251+
1252+
const cases = [
1253+
{ what: "a regular file at the target", path: "occupied", phase: "target" },
1254+
{ what: "a regular file on the way", path: "occupied/below/here", phase: undefined },
1255+
{ what: "a special entry at the target", path: "linked", phase: "target" },
1256+
{ what: "a special entry on the way", path: "linked/below/here", phase: undefined },
1257+
] as const;
1258+
1259+
for (const entry of cases) {
1260+
const refused = yield* files.ensureDirectory({ cwd: fixture.workspace, path: entry.path });
1261+
const failure = parseFilesFailure(failed(refused));
1262+
// The `what` travels with the assertion, so a failure names which of the
1263+
// four reported something else.
1264+
expect(`${entry.what}: ${failure?.operation}`).toBe(`${entry.what}: ensure-directory`);
1265+
expect(`${entry.what}: ${failure?.reason}`).toBe(`${entry.what}: not-directory`);
1266+
if (entry.phase !== undefined) {
1267+
expect(`${entry.what}: ${failure?.phase}`).toBe(`${entry.what}: ${entry.phase}`);
1268+
}
1269+
// Nothing resolved crosses back: no host path, no errno, no platform
1270+
// text. Asserted on the whole serialized failure, so a member added later
1271+
// that carried one of them would fail here rather than pass unnoticed.
1272+
const serialized = JSON.stringify(failed(refused));
1273+
expect(`${entry.what}: ${serialized.includes(fixture.workspace)}`).toBe(
1274+
`${entry.what}: false`,
1275+
);
1276+
expect(`${entry.what}: ${serialized.includes(fixture.root)}`).toBe(`${entry.what}: false`);
1277+
expect(`${entry.what}: ${/ENOTDIR|ENOENT|errno/i.test(serialized)}`).toBe(
1278+
`${entry.what}: false`,
1279+
);
1280+
}
12381281

1239-
const atTarget = yield* files.ensureDirectory({ cwd: fixture.workspace, path: "occupied" });
1240-
expect(parseFilesFailure(failed(atTarget))).toEqual({
1241-
type: FILES_ERROR,
1242-
operation: "ensure-directory",
1243-
phase: "target",
1244-
reason: "not-directory",
1245-
});
1246-
// The file is still a file: a refusal changed nothing.
1282+
// Every refusal changed nothing: the file is still a file, the link is
1283+
// still a link, and its target still holds its bytes.
12471284
expect(yield* readTextFile(join(fixture.workspace, "occupied"))).toBe(
12481285
"a file, not a directory",
12491286
);
1250-
1251-
const through = yield* files.ensureDirectory({
1252-
cwd: fixture.workspace,
1253-
path: "occupied/below/here",
1254-
});
1255-
const failure = parseFilesFailure(failed(through));
1256-
expect(failure?.operation).toBe("ensure-directory");
1257-
expect(failure?.reason).toBe("not-directory");
1258-
// Nothing resolved crosses back: no host path, no errno, no platform text.
1259-
// Asserted on the whole serialized failure, so a member added later that
1260-
// carried one of them would fail here rather than pass unnoticed.
1261-
const serialized = JSON.stringify(failed(through));
1262-
expect(serialized).not.toContain(fixture.workspace);
1263-
expect(serialized).not.toContain(fixture.root);
1264-
expect(serialized).not.toMatch(/ENOTDIR|ENOENT|errno/i);
1287+
expect((yield* until(lstat(join(fixture.workspace, "linked")))).isSymbolicLink()).toBe(true);
1288+
expect(yield* readTextFile(join(fixture.workspace, "pointee"))).toBe("what the link names");
12651289
});
12661290

12671291
// HF27: creation is direct and persists. The operation has no rollback and no

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

Lines changed: 19 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,26 @@
22
* `<Dir path="..">` — lexical working directory
33
* (specs/workflow-workspace-spec.md §6.3).
44
*
5-
* One meaning and one effect on the world: the content expands with `path` as
6-
* the contextual working directory, and the enclosing one is restored when the
7-
* invocation ends — on success, failure and cancellation alike, because the
8-
* installation lives on the invocation's own scope.
5+
* Two acts, in this order. First the directory named by `path` is made to
6+
* exist: it is created recursively when it is missing, used as it stands when
7+
* it is already a directory, and refused when something that is not a directory
8+
* is there or on the way to it. Only then does the content expand, with `path`
9+
* as the contextual working directory. Content never begins on the far side of
10+
* a refusal, because a document that named a directory asked for that directory
11+
* and not for whatever it would otherwise have run in.
912
*
10-
* It creates nothing and retains nothing. A `<Dir>` inside a `<Repository>`
11-
* leaves that Repository contextual, which is what lets the self-closing
12-
* Worktree spelling work: the path is bound by `as`, `<Dir>` moves the working
13-
* directory to it, and the Repository a later Git component would act on is
14-
* still the enclosing one.
13+
* The enclosing working directory is restored when the invocation ends — on
14+
* success, failure and cancellation alike, because the installation lives on
15+
* the invocation's own scope. Restoring it removes nothing: a directory this
16+
* element created stays, and a later failure of the content inside it says
17+
* nothing about whether the directory should exist. There is no rollback here
18+
* and no teardown deletion.
19+
*
20+
* It retains nothing of its own. A `<Dir>` inside a `<Repository>` leaves that
21+
* Repository contextual, which is what lets the self-closing Worktree spelling
22+
* work: the path is bound by `as`, `<Dir>` moves the working directory to it,
23+
* and the Repository a later Git component would act on is still the enclosing
24+
* one. Neither the selection nor any member of its identity is touched.
1525
*
1626
* Self-closing `<Dir />` is invalid. A working directory installed for no
1727
* content is a directory nothing runs in, and silently rendering nothing would

0 commit comments

Comments
 (0)