Skip to content

Commit 2c18a18

Browse files
authored
๐Ÿ—‘๏ธ Let a generated fragment remove one file it names (#574)
* ๐Ÿ—‘๏ธ Admit <File.Delete> to the standard generated write table Adds core's exact self-closing `File.Delete` definition to the standard Deno workflow profile's generated-XMD `write` table, as `pinnedFileDelete()`. A write-enabled generated fragment may now remove one file through the ordinary component and the run's existing effect transaction. The constructor takes the definition object core's registry holds โ€” not a same-shaped copy โ€” and is exported through `@executablemd/core/host` alone. It is appended after core's paired `File:write` and the workflow package's lexical `Dir`, and before any host extension: the table's order is retained identity, so a continuation admitted under the former two-entry table is intentionally refused before any generated effect. A read-only admission never selected the write table and is unaffected. The evaluator adds nothing. A deletion contributes no observation and no receipt, so a fragment that only deletes still binds `{ observations: [], output: "" }`, and its `workspace_file` effect stays the authoritative account of the removal. * ๐Ÿงน Make the directory with ensureDir rather than a Node primitive --------- Co-authored-by: Taras Mankovski <74687+taras@users.noreply.github.com>
1 parent 60b08bb commit 2c18a18

8 files changed

Lines changed: 302 additions & 62 deletions

File tree

โ€Žarchitecture.mdโ€Ž

Lines changed: 25 additions & 11 deletions
Large diffs are not rendered by default.

โ€Žpackages/core/host.tsโ€Ž

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,7 @@ export {
8181
GeneratedXmdError,
8282
pinnedComponent,
8383
pinnedFetch,
84+
pinnedFileDelete,
8485
pinnedFileRead,
8586
pinnedFileWrite,
8687
pinnedMutation,

โ€Žpackages/core/src/generated-xmd.tsโ€Ž

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -399,6 +399,38 @@ export function pinnedFileWrite(): GeneratedMutation {
399399
};
400400
}
401401

402+
/**
403+
* The pinned core `<File.Delete>` identity, in the one form it has.
404+
*
405+
* Core's own default definition, and its self-closing spelling. One name, one
406+
* identity: unlike `<File>`, whose two spellings do different things, this
407+
* component answers the self-closing form and refuses the paired one, so the
408+
* form stated here names what the identity is rather than narrowing it to part
409+
* of it. Stating it anyway is what puts the decision in preflight, before the
410+
* first effect of the fragment โ€” a paired spelling costs an earlier admitted
411+
* element nothing.
412+
*
413+
* An admitted deletion invokes the ordinary `<File.Delete>` component and
414+
* therefore the installed Files provider, which under a workflow run is the
415+
* transaction-bound one, so the removal crosses the run's ordinary effect
416+
* transaction rather than a path of the evaluator's own. What it did is
417+
* retained by the `workspace_file` effect it publishes there, and the evaluator
418+
* collects nothing beside it: a mutation contributes no observation, and a
419+
* deletion has no outcome for one to carry.
420+
*/
421+
export function pinnedFileDelete(): GeneratedMutation {
422+
const definition = CORE_REGISTRY.get("File.Delete")?.default?.definition;
423+
if (definition === undefined || definition.kind !== "function") {
424+
throw new GeneratedXmdError("core supplies no File.Delete component to admit.");
425+
}
426+
return {
427+
name: "File.Delete",
428+
identity: `${CORE_ORIGIN}#File.Delete`,
429+
definition,
430+
form: "self-closing",
431+
};
432+
}
433+
402434
/**
403435
* One host-owned mutation component, by the exact definition the host holds and
404436
* the exact form it admits.

โ€Žpackages/core/tests/generated-xmd.test.tsโ€Ž

Lines changed: 42 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -27,7 +27,7 @@ import { beforeAll, describe, it } from "@executablemd/test-support/bdd";
2727
import { expect } from "@executablemd/test-support/expect";
2828
import { ensure, resource, scoped, sleep, spawn, suspend, until, withResolvers } from "effection";
2929
import type { Operation } from "effection";
30-
import { exists, readTextFile, rm, writeTextFile } from "@effectionx/fs";
30+
import { ensureDir, exists, readTextFile, rm, writeTextFile } from "@effectionx/fs";
3131
import { API, useHostFiles } from "@executablemd/runtime";
3232
import type { FetchInit, RuntimeFetchResponse } from "@executablemd/runtime";
3333
import { InMemoryStream, serializeDurableEvent } from "@executablemd/durable-streams";
@@ -37,6 +37,7 @@ import { tmpdir } from "node:os";
3737
import { join } from "node:path";
3838

3939
import { Component, content, hasContent } from "../src/component-api.ts";
40+
import { CORE_REGISTRY } from "../src/components/registry.ts";
4041
import { collect } from "../src/collect.ts";
4142
import { retainedSource } from "../src/root-source.ts";
4243
import { useTempFileCompiler } from "../src/temp-file-compiler.ts";
@@ -47,6 +48,7 @@ import {
4748
evaluateGeneratedXmd,
4849
pinnedComponent,
4950
pinnedFetch,
51+
pinnedFileDelete,
5052
pinnedFileRead,
5153
pinnedFileWrite,
5254
pinnedMutation,
@@ -1138,6 +1140,10 @@ function* useWorkspaceFiles(root: string): Operation<Reads> {
11381140
performed.push(`write:${input.path}`);
11391141
return yield* next(input);
11401142
},
1143+
*deleteFile([input], next) {
1144+
performed.push(`delete:${input.path}`);
1145+
return yield* next(input);
1146+
},
11411147
});
11421148
return { performed };
11431149
}
@@ -1168,6 +1174,24 @@ describe("Tier WGAC โ€” the pinned read-only File", () => {
11681174
expect(pinnedFileRead().selfClosing).toBe(true);
11691175
});
11701176

1177+
it("WGAC13: the pinned deletion is core's own definition, in its one form", function* () {
1178+
const deletion = pinnedFileDelete();
1179+
1180+
expect(deletion.name).toBe("File.Delete");
1181+
// What a retained admission is compared against, and what a continuation
1182+
// that selected the write table is held to.
1183+
expect(deletion.identity).toBe("@executablemd/core#File.Delete");
1184+
// One name, one identity: the component answers the self-closing spelling
1185+
// and refuses the paired one, so this states what the identity is rather
1186+
// than narrowing it โ€” and stating it is what decides a paired spelling in
1187+
// preflight, before the fragment's first effect.
1188+
expect(deletion.form).toBe("self-closing");
1189+
// The exact object core's registry holds, not one shaped like it. Expansion
1190+
// invokes a copy of this, and a same-shaped substitute is a different
1191+
// implementation behind a name the host already granted.
1192+
expect(deletion.definition).toBe(CORE_REGISTRY.get("File.Delete")?.default?.definition);
1193+
});
1194+
11711195
it("WGAC8: the result carries each observation's value, in order, beside the rendering", function* () {
11721196
const root = yield* useWorkspace();
11731197
yield* writeTextFile(join(root, "notes.md"), "the retained note\n");
@@ -1513,20 +1537,29 @@ describe("Tier GXC โ€” a name is not a form", () => {
15131537
});
15141538
}
15151539

1516-
it("GXC5: neither form is answered by a same-name repository component", function* () {
1540+
it("GXC5: no admitted name is answered by a same-name repository component", function* () {
15171541
const workspace = yield* useWorkspace();
15181542
yield* writeTextFile(join(workspace, "File.md"), "the repository File ran.\n");
15191543
yield* writeTextFile(join(workspace, "Nest.md"), "the repository Nest ran.\n");
1544+
// A dotted name is a nested path to selection, so this is where a
1545+
// repository component called `File.Delete` would be found.
1546+
yield* ensureDir(join(workspace, "File"));
1547+
yield* writeTextFile(join(workspace, "File", "Delete.md"), "the repository File.Delete ran.\n");
15201548
const root = yield* useWorkspace();
15211549
yield* writeTextFile(join(root, "notes.md"), "the retained note\n");
1550+
yield* writeTextFile(join(root, "stale.md"), "the note an earlier step left\n");
15221551

15231552
const attempt = yield* scoped(function* () {
15241553
const files = yield* useWorkspaceFiles(root);
15251554
const evaluated = yield* evaluate(
15261555
selecting(
1527-
`<File path="notes.md" />\n\n<File path="proposed.md">written</File>\n\n<Nest>held</Nest>\n`,
1556+
`<File path="notes.md" />\n\n<File path="proposed.md">written</File>\n\n` +
1557+
`<Nest>held</Nest>\n\n<File.Delete path="stale.md" />\n`,
15281558
[pinnedFileRead()],
1529-
{ allow: ["read", "write"], mutations: [pinnedFileWrite(), nest()] },
1559+
{
1560+
allow: ["read", "write"],
1561+
mutations: [pinnedFileWrite(), nest(), pinnedFileDelete()],
1562+
},
15301563
),
15311564
{ componentDirs: [workspace] },
15321565
);
@@ -1536,15 +1569,18 @@ describe("Tier GXC โ€” a name is not a form", () => {
15361569
expect(attempt.evaluated.failure).toBe(undefined);
15371570
expect(attempt.evaluated.output).not.toContain("the repository File ran");
15381571
expect(attempt.evaluated.output).not.toContain("the repository Nest ran");
1539-
expect(attempt.files).toEqual(["notes.md", "write:proposed.md"]);
1572+
expect(attempt.evaluated.output).not.toContain("the repository File.Delete ran");
1573+
expect(attempt.files).toEqual(["notes.md", "write:proposed.md", "delete:stale.md"]);
1574+
// The pinned component removed the file; the repository one would have
1575+
// rendered prose and removed nothing.
1576+
expect(yield* exists(join(root, "stale.md"))).toBe(false);
15401577
});
15411578

15421579
const EXCLUDED: Array<[string, string]> = [
15431580
["a local Git push", `<Git.Push remote="origin" />`],
15441581
["a Git-host pull request", `<PullRequest title="t" body="b" />`],
15451582
["an issue upsert", `<Issue title="t" body="b" />`],
15461583
["a repository", `<Repository name="api" />`],
1547-
["a file deletion", `<File.Delete path="notes.md" />`],
15481584
["a glob", `<Glob pattern="**/*" />`],
15491585
];
15501586

โ€Žpackages/workflow/src/deno/workspace/evaluate.tsโ€Ž

Lines changed: 30 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,9 @@
2020
* from the captured run storage, read at invocation;
2121
* - the read-only `<File>` observation comes from core's pinned constructor;
2222
* - `<Fetch>` is admitted only when the captured request ceiling is non-empty;
23-
* - the write table is core's paired `<File>` and workflow's own lexical
24-
* `<Dir>`, built from the same definition the ordinary registration owns; and
23+
* - the write table is core's paired `<File>`, workflow's own lexical `<Dir>`
24+
* built from the same definition the ordinary registration owns, and core's
25+
* self-closing `<File.Delete>`; and
2526
* - any further read or write comes from the captured host option.
2627
*
2728
* No prop, binding, context, contextual API answer, middleware return value or
@@ -35,9 +36,15 @@
3536
* `allow` names an effect *class*, and the class resolves to the table this
3637
* host installed before any document existed. Omitting it asks for `read`,
3738
* which is what this component has always done. Asking for `write` reaches
38-
* core's paired `<File>` and workflow's `<Dir>` and nothing else โ€” no Git, no
39-
* Git host, no Issue, no process, no credential โ€” and a host that installed no
40-
* write table refuses the selection before the candidate is parsed.
39+
* core's paired `<File>`, workflow's `<Dir>` and core's self-closing
40+
* `<File.Delete>` and nothing else โ€” no Git, no Git host, no Issue, no process,
41+
* no credential โ€” and a host that installed no write table refuses the
42+
* selection before the candidate is parsed.
43+
*
44+
* A deletion is admitted on the same terms as the other two, and accounted for
45+
* the same way: it invokes the ordinary component, crosses the run's existing
46+
* effect transaction, and is retained by the `workspace_file` effect that
47+
* transaction publishes. Nothing about it reaches the value below.
4148
*
4249
* `allow` and `as` are independent. `as` grants nothing: it is the ordinary
4350
* caller-owned binding for the value this component returns, and that value has
@@ -67,7 +74,12 @@
6774

6875
import type { Operation } from "effection";
6976
import { hasContent } from "@executablemd/core";
70-
import { pinnedFileRead, pinnedFileWrite, pinnedMutation } from "@executablemd/core/host";
77+
import {
78+
pinnedFileDelete,
79+
pinnedFileRead,
80+
pinnedFileWrite,
81+
pinnedMutation,
82+
} from "@executablemd/core/host";
7183
import type {
7284
GeneratedEffectClass,
7385
GeneratedMutation,
@@ -219,16 +231,23 @@ function createEvaluate(
219231
// invocation is bounded by, whatever happens to the object it passed.
220232
const requests: GeneratedRequest[] = [...(options.requests ?? [])];
221233
// The standard profile, captured with them. Core's read-only `<File>` is the
222-
// read table; core's paired `<File>` and workflow's own lexical `<Dir>` are
223-
// the write table, and the Dir identity is built from the same definition the
224-
// ordinary registration owns so the two cannot drift. Both tables are stated
225-
// whether or not a document asks for the class โ€” `allow` selects from what
226-
// this host already installed, and can add nothing to it.
234+
// read table; core's paired `<File>`, workflow's own lexical `<Dir>` and
235+
// core's self-closing `<File.Delete>` are the write table, and the Dir
236+
// identity is built from the same definition the ordinary registration owns so
237+
// the two cannot drift. Both tables are stated whether or not a document asks
238+
// for the class โ€” `allow` selects from what this host already installed, and
239+
// can add nothing to it.
240+
//
241+
// The order is the retained policy, so it is stated once and kept: a
242+
// continuation compares what it was granted under against what this profile
243+
// holds now, and a host extension arriving last is what keeps a profile that
244+
// took none comparable to itself.
227245
const dir = dirDefinition();
228246
const reads: GeneratedObservation[] = [pinnedFileRead(), ...(options.reads ?? [])];
229247
const writes: GeneratedMutation[] = [
230248
pinnedFileWrite(),
231249
pinnedMutation(dir.name, `${COMPOSITION_ORIGIN}#Dir`, dir, "paired"),
250+
pinnedFileDelete(),
232251
...(options.writes ?? []),
233252
];
234253

โ€Žpackages/workflow/tests/generated-agent-component.test.tsโ€Ž

Lines changed: 114 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -163,6 +163,19 @@ function reads(events: DurableEvent[]): DurableEvent[] {
163163
);
164164
}
165165

166+
/** Every Workspace deletion this run actually performed. */
167+
function deletions(events: DurableEvent[]): DurableEvent[] {
168+
return reads(events).filter((event) => nameOf(event).startsWith("delete:"));
169+
}
170+
171+
/** What one Workspace file effect recorded, as the journal holds its result. */
172+
function outcomeOf(event: DurableEvent): Json | undefined {
173+
if (event.type !== "yield" || event.result.status !== "ok") {
174+
return undefined;
175+
}
176+
return event.result.value;
177+
}
178+
166179
/** The fragment one admission recorded, as the journal holds its result. */
167180
function admittedSource(event: DurableEvent): string | undefined {
168181
const result: unknown = event.result;
@@ -177,6 +190,15 @@ function admittedSource(event: DurableEvent): string | undefined {
177190
return typeof source === "string" ? source : undefined;
178191
}
179192

193+
/** The pinned identities one admission recorded for the elements it named. */
194+
function recordedNames(event: DurableEvent): Json | undefined {
195+
const value = outcomeOf(event);
196+
if (typeof value !== "object" || value === null || Array.isArray(value)) {
197+
return undefined;
198+
}
199+
return value.named;
200+
}
201+
180202
/** The durable name one admission was recorded under. */
181203
function nameOf(event: DurableEvent): string {
182204
return event.type === "yield" ? event.description.name : "";
@@ -993,10 +1015,24 @@ describe("Tier WGAC โ€” the standard write table", () => {
9931015
// of the mutation. The evaluator adds no receipt of its own.
9941016
expect(reads(attempt.events).length).toBeGreaterThanOrEqual(1);
9951017

996-
// Two identities, each for the form its element was written in.
1018+
// The standard table, whole and in the order the policy retains โ€” which
1019+
// is load-bearing rather than cosmetic: a continuation compares the
1020+
// entries position by position, so what this profile installs is what a
1021+
// resumed run is held to.
9971022
const policy = policyOf(admissions(attempt.events)[0]!);
998-
expect(JSON.stringify(policy)).toContain("File:write");
999-
expect(JSON.stringify(policy)).toContain("@executablemd/workflow/composition#Dir");
1023+
expect(policy?.allowed).toEqual([
1024+
{ name: "File", identity: "@executablemd/core#File:write", forms: ["paired"] },
1025+
{
1026+
name: "Dir",
1027+
identity: "@executablemd/workflow/composition#Dir",
1028+
forms: ["paired"],
1029+
},
1030+
{
1031+
name: "File.Delete",
1032+
identity: "@executablemd/core#File.Delete",
1033+
forms: ["self-closing"],
1034+
},
1035+
]);
10001036
});
10011037
});
10021038

@@ -1015,6 +1051,81 @@ describe("Tier WGAC โ€” the standard write table", () => {
10151051
});
10161052
});
10171053

1054+
it("WGAC14: an admitted deletion removes the file through the run's own transaction", function* () {
1055+
const root = yield* useStorageRoot();
1056+
yield* withStorage(root, function* () {
1057+
const database = yield* createRun();
1058+
yield* plant(database, "obsolete.md", "what an earlier step left\n");
1059+
const planted = reads(yield* database.journal.readAll()).length;
1060+
1061+
const attempt = yield* runDocument(
1062+
database,
1063+
`<Evaluate source={${JSON.stringify(`<File.Delete path="obsolete.md" />`)}} ` +
1064+
`allow={["write"]} as="applied" />\n\n<Json value={applied} />\n`,
1065+
);
1066+
1067+
expect(attempt.failure).toBe(undefined);
1068+
// The run's own Workspace, read back through its own transaction rather
1069+
// than from the records under test.
1070+
expect(yield* stored(database, "/obsolete.md")).toBe(undefined);
1071+
// One ordinary `workspace_file` effect, which is the authoritative
1072+
// account of the removal. The evaluator adds no receipt beside it.
1073+
const performed = deletions(attempt.events);
1074+
expect(performed).toHaveLength(1);
1075+
expect(outcomeOf(performed[0]!)).toEqual({ kind: "deleted" });
1076+
expect(reads(attempt.events)).toHaveLength(planted + 1);
1077+
1078+
// Admitted as the exact self-closing identity, and named by the fragment
1079+
// as the element was written.
1080+
const admission = admissions(attempt.events)[0]!;
1081+
expect(policyOf(admission)?.allowed).toContainEqual({
1082+
name: "File.Delete",
1083+
identity: "@executablemd/core#File.Delete",
1084+
forms: ["self-closing"],
1085+
});
1086+
expect(recordedNames(admission)).toEqual([
1087+
{
1088+
name: "File.Delete",
1089+
identity: "@executablemd/core#File.Delete",
1090+
form: "self-closing",
1091+
},
1092+
]);
1093+
// A mutation contributes nothing: the shape a document binds is the same
1094+
// one every selection binds, and a deletion puts no result in it.
1095+
expect(JSON.parse(reported(attempt))).toEqual({ observations: [], output: "" });
1096+
});
1097+
});
1098+
1099+
it("WGAC15: a later unadmitted construct keeps the earlier deletion from running", function* () {
1100+
const root = yield* useStorageRoot();
1101+
yield* withStorage(root, function* () {
1102+
const database = yield* createRun();
1103+
yield* plant(database, "obsolete.md", "what an earlier step left\n");
1104+
const planted = reads(yield* database.journal.readAll()).length;
1105+
1106+
const attempt = yield* runDocument(
1107+
database,
1108+
evaluates(`<File.Delete path="obsolete.md" />\n\n\`\`\`bash exec\nprintf ran\n\`\`\`\n`, [
1109+
"write",
1110+
]),
1111+
);
1112+
1113+
// Whole-fragment preflight wins: the construct after the admitted element
1114+
// is read before the element ahead of it runs.
1115+
//
1116+
// The second construct is a code block rather than an unadmitted
1117+
// component, and that is what makes this discriminating. A refusal names
1118+
// its class and nothing else, so "did not admit" would read the same
1119+
// whether the block was refused or the deletion itself was never in the
1120+
// table โ€” and a fragment whose first element was refused would prove
1121+
// nothing about preflight reaching past it.
1122+
expect(reported(attempt)).toContain("executable code block");
1123+
expect(yield* stored(database, "/obsolete.md")).toBe("what an earlier step left\n");
1124+
expect(deletions(attempt.events)).toEqual([]);
1125+
expect(reads(attempt.events)).toHaveLength(planted);
1126+
});
1127+
});
1128+
10181129
it("WGAC10: a self-closing File is not admitted by the write table", function* () {
10191130
const root = yield* useStorageRoot();
10201131
yield* withStorage(root, function* () {

0 commit comments

Comments
ย (0)