Skip to content

Commit 7f8ac03

Browse files
committed
🧬 Put the generated evaluator on the owning Operation path (#589)
Retype persistAdmission/evaluateGeneratedXmd, the workflow wrappers and the host <Evaluate> admit() as Operations, remove the ephemeral() bridge around preflight and expansion, and describe the production path through the host-declared <Evaluate> component instead of DurablePreparation. Adds GX18a-d inline-order/partial-replay regressions (green) and WGAC16, the extracted PR #181 AC4 read/write reproducer through real start, answer and resume. WGAC16 is red on this base and with this correction alike: the resume refuses at the retained admission's ceiling comparison because the run's own Workspace root growth changes the policy <Evaluate> restates from live storage. Evidence and the refuted root-cause attribution are recorded in issue-589-implementor-report.md beside this worktree.
1 parent 6b11ce8 commit 7f8ac03

7 files changed

Lines changed: 501 additions & 46 deletions

File tree

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

Lines changed: 253 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,7 @@ import { until } from "effection";
3535
import { join } from "node:path";
3636
import { tmpdir } from "node:os";
3737
import { DatabaseSync } from "node:sqlite";
38+
import { API } from "@executablemd/runtime";
3839
import { collect, execute, inlineSource, registerComponents } from "@executablemd/core";
3940
import { executeInstalled } from "@executablemd/core/host";
4041
import { durableCall, InMemoryStream } from "@executablemd/durable-streams";
@@ -836,7 +837,12 @@ function* useStubAgent(calls: AgentCalls): Operation<void> {
836837
* cases depend on is installed by the code that installs it in production
837838
* rather than by this suite.
838839
*/
839-
function productionHost(root: string, calls: AgentCalls, events: string[] = []): WorkflowHost {
840+
function productionHost(
841+
root: string,
842+
calls: AgentCalls,
843+
events: string[] = [],
844+
performed?: string[],
845+
): WorkflowHost {
840846
return {
841847
useRunHost(): Operation<WorkflowExecutionTransitions> {
842848
return useWorkflowRunHost({ root });
@@ -853,6 +859,21 @@ function productionHost(root: string, calls: AgentCalls, events: string[] = []):
853859
yield* ensure(function* () {
854860
events.push("released");
855861
});
862+
if (performed !== undefined) {
863+
// A pass-through observer around the ordinary Files boundary, so a
864+
// case can count what a document execution actually performed there
865+
// rather than inferring it from the rows a replay restored.
866+
yield* API.Files.around({
867+
*readTextFile([input], next) {
868+
performed.push(`read:${input.path}`);
869+
return yield* next(input);
870+
},
871+
*writeTextFile([input], next) {
872+
performed.push(`write:${input.path}`);
873+
return yield* next(input);
874+
},
875+
});
876+
}
856877
return yield* withWorkflowWorkspace(database, operation, {
857878
agent: () => useStubAgent(calls),
858879
});
@@ -861,8 +882,14 @@ function productionHost(root: string, calls: AgentCalls, events: string[] = []):
861882
};
862883
}
863884

864-
/** A committed definition whose root document is `source`. */
865-
function useCheckpointFixture(source: string): Operation<Fixture> {
885+
/**
886+
* A committed definition whose root document is `source`, beside any bundled
887+
* Markdown components the root declares — every file from the same commit.
888+
*/
889+
function useCheckpointFixture(
890+
source: string,
891+
components: Record<string, string> = {},
892+
): Operation<Fixture> {
866893
return resource<Fixture>(function* (provide) {
867894
const repository = yield* until(mkdtemp(join(tmpdir(), "xmd-ckx-repo-")));
868895
yield* ensure(function* () {
@@ -873,12 +900,48 @@ function useCheckpointFixture(source: string): Operation<Fixture> {
873900
yield* git(repository, ["config", "user.name", "CKX"]);
874901
yield* writeTextFile(join(repository, "workflow.md"), source);
875902
yield* git(repository, ["add", "workflow.md"]);
903+
for (const [name, content] of Object.entries(components)) {
904+
yield* writeTextFile(join(repository, `${name}.md`), content);
905+
yield* git(repository, ["add", `${name}.md`]);
906+
}
876907
yield* git(repository, ["-c", "commit.gpgsign=false", "commit", "--quiet", "-m", "definition"]);
877908
const objectId = (yield* git(repository, ["rev-parse", "HEAD:workflow.md"])).trim();
878909
yield* provide({ repository, objectId, contents: source });
879910
});
880911
}
881912

913+
/**
914+
* The Git capability answered from the fixture repository itself.
915+
*
916+
* A bundled definition reads more than one object — the root and each declared
917+
* component, each pinned by its own blob id — so the single-object `useGit`
918+
* stub cannot answer for it. Every question shells to the fixture repository,
919+
* which is what the production capability does from the run's own directory.
920+
*/
921+
function useRepositoryGit(repository: string): Operation<void> {
922+
return Git.around(
923+
{
924+
// deno-lint-ignore require-yield
925+
*repositoryRoot(): Operation<string> {
926+
return repository;
927+
},
928+
*revParse([revision]): Operation<string> {
929+
return (
930+
yield* git(repository, ["rev-parse", "--verify", "--end-of-options", revision])
931+
).trim();
932+
},
933+
*readObject([commit, path]): Operation<string> {
934+
return yield* git(repository, ["cat-file", "blob", `${commit}:${path}`]);
935+
},
936+
// deno-lint-ignore require-yield
937+
*objectFormat(): Operation<"sha1" | "sha256"> {
938+
return "sha1";
939+
},
940+
},
941+
{ at: "min" },
942+
);
943+
}
944+
882945
/** What `xmd workflow start` establishes, through the command's own module. */
883946
function* startFor(fixture: Fixture): Operation<WorkflowStart> {
884947
const established = yield* establishDefinition(join(fixture.repository, "workflow.md"));
@@ -991,6 +1054,28 @@ function journalled(path: string, type: string): number {
9911054
}
9921055
}
9931056

1057+
/** Every durable yield this run retained, in journal order, as type and name. */
1058+
function orderedEffects(path: string): { type: string; name: string }[] {
1059+
const database = new DatabaseSync(path, { readOnly: true });
1060+
try {
1061+
const effects: { type: string; name: string }[] = [];
1062+
for (const row of database
1063+
.prepare("SELECT record FROM journal_events ORDER BY sequence")
1064+
.all()) {
1065+
const parsed = JSON.parse(String(row["record"]));
1066+
if (parsed?.type === "yield") {
1067+
effects.push({
1068+
type: String(parsed.description?.type),
1069+
name: String(parsed.description?.name),
1070+
});
1071+
}
1072+
}
1073+
return effects;
1074+
} finally {
1075+
database.close();
1076+
}
1077+
}
1078+
9941079
/** Every distinct effect type this run journaled, for naming what it performed. */
9951080
function effectTypes(path: string): string[] {
9961081
const database = new DatabaseSync(path, { readOnly: true });
@@ -1208,3 +1293,168 @@ describe("Tier CKX — a checkpoint a document asked for", () => {
12081293
expect(yield* storageDigest(path)).toEqual(afterAccepted);
12091294
});
12101295
});
1296+
1297+
/**
1298+
* Tier WGAC — a generated effect inside a bundled component resumes through a
1299+
* later wait (specs/workflow-workspace-spec.md §§8.4, 9).
1300+
*
1301+
* The extracted equivalent of PR #181's AC4: `<Evaluate>` sits inside a
1302+
* committed bundled Markdown component, and a later parent durable effect and
1303+
* the real workflow `<Elicit>` follow outside it. The admission and every
1304+
* durable effect the admitted fragment performs belong to the owning document
1305+
* expansion's sequence, so a resume offers them in authored order and restores
1306+
* each completed one without entering its provider again — which the existing
1307+
* root-level checkpoint above does not discriminate.
1308+
*/
1309+
describe("Tier WGAC — generated effects in a bundled component resume through a later wait", () => {
1310+
/** One root declaring one bundled component, with the wait after both. */
1311+
function bundledRoot(setup: string, componentName: string): string {
1312+
return `---
1313+
workflow:
1314+
components:
1315+
${componentName}: ./${componentName}.md
1316+
---
1317+
${setup}
1318+
<${componentName} />
1319+
1320+
<File path="after.md">
1321+
parent marker
1322+
</File>
1323+
1324+
<Elicit schema={${CHECKPOINT_SCHEMA}} as="decision">
1325+
Proceed with the change?
1326+
</Elicit>
1327+
1328+
decision: {decision.proceed}
1329+
`;
1330+
}
1331+
1332+
const CASES = [
1333+
{
1334+
what: "read",
1335+
componentName: "Observe",
1336+
component:
1337+
`<Evaluate source={"<File path=\\"notes.md\\" />"} allow={["read"]} as="observed" />\n`,
1338+
setup: `
1339+
<File path="notes.md">
1340+
the retained note
1341+
</File>
1342+
`,
1343+
// What the fragment performs at the Files boundary, exactly once.
1344+
live: (call: string) => call.startsWith("read:") && call.endsWith("notes.md"),
1345+
nested: [{ operation: "read", target: "notes.md" }],
1346+
files: 3,
1347+
},
1348+
{
1349+
what: "write",
1350+
componentName: "Propose",
1351+
component:
1352+
`<Evaluate source={"<File path=\\"proposed.md\\">a generated proposal</File>"} allow={["write"]} as="observed" />\n`,
1353+
setup: "",
1354+
live: (call: string) => call.startsWith("write:") && call.endsWith("proposed.md"),
1355+
nested: [{ operation: "write", target: "proposed.md" }],
1356+
files: 2,
1357+
},
1358+
] as const;
1359+
1360+
for (const bundled of CASES) {
1361+
it(`WGAC16: a generated ${bundled.what} inside a bundled component resumes through the later wait`, function* () {
1362+
const store = yield* useRunStore();
1363+
const fixture = yield* useCheckpointFixture(
1364+
bundledRoot(bundled.setup, bundled.componentName),
1365+
{ [bundled.componentName]: bundled.component },
1366+
);
1367+
yield* useRepositoryGit(fixture.repository);
1368+
1369+
const calls: AgentCalls = { prompts: [] };
1370+
const performed: string[] = [];
1371+
const rendered: string[] = [];
1372+
const started = yield* invoke(
1373+
{ ...REQUEST, action: "start" },
1374+
yield* startFor(fixture),
1375+
productionHost(store, calls, [], performed),
1376+
pinnedBody(rendered),
1377+
);
1378+
expect(started.exitCode).toBe(2);
1379+
1380+
const runId = String(started.written.err.find((line) => line.startsWith("workflow run: ")))
1381+
.slice("workflow run: ".length)
1382+
.trim();
1383+
const path = workflowRunPath(store, runId);
1384+
1385+
// The start settled suspended, with the nested effect and the later
1386+
// parent effect committed ahead of the wait — and the fragment reached
1387+
// the Files boundary exactly once.
1388+
const suspended = retained(path);
1389+
expect(suspended.status).toBe("suspended");
1390+
expect(suspended.requests).toHaveLength(1);
1391+
expect(rendered).toEqual([]);
1392+
const atSuspension = counts(path);
1393+
expect(atSuspension).toEqual({
1394+
[PROMPT_EFFECT]: 0,
1395+
[EVALUATION_EFFECT]: 1,
1396+
[FILE_EFFECT]: bundled.files,
1397+
});
1398+
expect(performed.filter(bundled.live)).toHaveLength(1);
1399+
1400+
// The relevant ordered subsequence, exactly: the admission, the nested
1401+
// generated effect in authored order, the later parent effect, then the
1402+
// suspension request. Component imports journal beside these and are not
1403+
// part of the ordering under test.
1404+
const relevant = new Set([PROMPT_EFFECT, EVALUATION_EFFECT, FILE_EFFECT, SUSPENSION_REQUEST]);
1405+
const effects = orderedEffects(path).filter((effect) => relevant.has(effect.type));
1406+
const admission = effects.findIndex((effect) => effect.type === EVALUATION_EFFECT);
1407+
expect(admission).toBeGreaterThanOrEqual(0);
1408+
const sequence = effects.slice(admission);
1409+
expect(sequence.map((effect) => effect.type)).toEqual([
1410+
EVALUATION_EFFECT,
1411+
FILE_EFFECT,
1412+
FILE_EFFECT,
1413+
SUSPENSION_REQUEST,
1414+
]);
1415+
for (const [index, expected] of bundled.nested.entries()) {
1416+
expect(sequence[1 + index]?.name.startsWith(`${expected.operation}:`)).toBe(true);
1417+
expect(sequence[1 + index]?.name.endsWith(`:/${expected.target}`)).toBe(true);
1418+
}
1419+
const parent = sequence[1 + bundled.nested.length];
1420+
expect(parent?.name.startsWith("write:")).toBe(true);
1421+
expect(parent?.name.endsWith(":/after.md")).toBe(true);
1422+
1423+
// The delivery retains the answer and executes nothing.
1424+
const suspensionId = suspended.requests[0] ?? "";
1425+
const delivered = yield* manage(
1426+
{ action: "answer", runId, suspensionId, value: { proceed: true }, secretDetection: true },
1427+
productionHost(store, calls, [], performed),
1428+
);
1429+
expect(delivered.exitCode).toBe(0);
1430+
expect(retained(path)).toEqual(suspended);
1431+
expect(performed.filter(bundled.live)).toHaveLength(1);
1432+
1433+
// The resume completes, restores every committed effect, and performs
1434+
// the fragment's work no second time: one live call at the Files
1435+
// boundary across both document executions.
1436+
const resumed = yield* invoke(
1437+
{ ...REQUEST, action: "resume", target: runId },
1438+
undefined,
1439+
productionHost(store, calls, [], performed),
1440+
pinnedBody(rendered),
1441+
);
1442+
expect(resumed.exitCode).toBe(0);
1443+
1444+
const completed = retained(path);
1445+
expect(completed.status).toBe("completed");
1446+
expect(counts(path)).toEqual(atSuspension);
1447+
expect(performed.filter(bundled.live)).toHaveLength(1);
1448+
expect(
1449+
orderedEffects(path)
1450+
.filter((effect) => relevant.has(effect.type))
1451+
.slice(admission, admission + sequence.length),
1452+
).toEqual(sequence);
1453+
1454+
// The delivered value reaches the document after the wait.
1455+
expect(rendered).toHaveLength(1);
1456+
expect(rendered[0]).toContain("decision: true");
1457+
expect(answers(path)[0]?.state).toBe("consumed");
1458+
});
1459+
}
1460+
});

‎packages/core/host.ts‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,8 +25,11 @@
2525
* execute, and what was admitted is recorded as one ordinary durable event
2626
* before the first generated effect. The host states a `read` table and a
2727
* `write` table and the caller selects between them, so admitting an
28-
* observation is not admitting a mutation. It is reached from a preparation,
29-
* because what it performs belongs in the run's journal.
28+
* observation is not admitting a mutation. It is an `Operation`: the
29+
* production workflow reaches it through its host-declared `<Evaluate>`
30+
* component inside the owning authored expansion — not through a
31+
* `DurablePreparation` — so the admission and every durable effect the
32+
* admitted fragment performs belong to that expansion's own durable sequence.
3033
*
3134
* Both stop at the first refusal, and a refusal stops only what has not
3235
* happened yet: durable effects an earlier preparation completed stay

‎packages/core/src/generated-xmd.ts‎

Lines changed: 14 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -94,8 +94,8 @@
9494
* without asking anyone anything a second time.
9595
*/
9696

97-
import { createDurableOperation, ephemeral } from "@executablemd/durable-streams";
98-
import type { Json as DurableJson, Workflow } from "@executablemd/durable-streams";
97+
import { createDurableOperation } from "@executablemd/durable-streams";
98+
import type { Json as DurableJson } from "@executablemd/durable-streams";
9999
import { scoped } from "effection";
100100
import type { Operation } from "effection";
101101

@@ -1248,7 +1248,7 @@ function* persistAdmission(
12481248
table: ReadonlyMap<string, Entry[]>,
12491249
ceilings: ReadonlyMap<string, FetchRequest[]>,
12501250
policy: Policy,
1251-
): Workflow<Json> {
1251+
): Operation<Json> {
12521252
const stored = yield createDurableOperation<DurableJson>(
12531253
{ type: GENERATED_XMD, name: `generated:${id}`, input: policyRecord(policy) },
12541254
() => admitSource(source, table, ceilings, policy),
@@ -1348,18 +1348,21 @@ function expand(
13481348
/**
13491349
* Admit one generated fragment and perform what it asks for.
13501350
*
1351-
* A `Workflow`, because what it records belongs in the run's journal: a trusted
1352-
* host reaches it from a `DurablePreparation`, and a partial continuation
1353-
* restores the admission and every observation that already committed rather
1354-
* than performing them again.
1351+
* An `Operation`, so its durable records belong to the caller's own durable
1352+
* sequence: the production workflow reaches it through the host-declared
1353+
* `<Evaluate>` component inside the owning document expansion, and the
1354+
* admission together with every durable effect the admitted fragment performs
1355+
* is offered inline there, in authored order. A partial continuation offers
1356+
* the same sequence and restores the admission and every observation that
1357+
* already committed rather than performing them again.
13551358
*/
13561359
export function* evaluateGeneratedXmd(
13571360
request: GeneratedXmdRequest,
1358-
): Workflow<GeneratedObservationResult> {
1361+
): Operation<GeneratedObservationResult> {
13591362
const allow = selection(request.allow);
13601363
const entries = selectedEntries(request, allow);
13611364
const table = admitted(entries);
1362-
const ceilings = yield* ephemeral(normalizedCeilings(entries));
1365+
const ceilings = yield* normalizedCeilings(entries);
13631366
const policy = currentPolicy(request, allow, entries, ceilings);
13641367

13651368
const stored = yield* persistAdmission(request.id, request.source, table, ceilings, policy);
@@ -1379,6 +1382,6 @@ export function* evaluateGeneratedXmd(
13791382

13801383
// The retained source is what expands, so a continuation runs the fragment
13811384
// this run admitted rather than whatever a later caller happens to hold.
1382-
const restored = yield* ephemeral(preflight(decided.source, table, ceilings));
1383-
return yield* ephemeral(expand(request.id, restored.segments, restored.named));
1385+
const restored = yield* preflight(decided.source, table, ceilings);
1386+
return yield* expand(request.id, restored.segments, restored.named);
13841387
}

0 commit comments

Comments
 (0)