Skip to content

Commit e84c0a7

Browse files
authored
🌱 Hold a generated admission to a retained root basis, not the run's frozen past (#597)
* 🧬 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. * 🌱 Hold a generated admission to a retained root basis, not the run's frozen past (#589) A continuation now asks for the admission's Workspace roots by membership — every admission root and its selected root still retained, the current root retained — while classes, pinned identities, forms and request ceilings keep comparing whole and exactly. The run's own root publications and an advanced current root no longer refuse the resume the run itself recorded. GX18a/b replay under an added, newly current root; GX22/GX22b prove the progression resumes and reaches the generated component; GX22c/GX22d prove root loss refuses before it runs. WGAC16 goes green through real start, answer and resume, holding journal counts, the ordered durable subsequence, the root-publication count and the current root identical across all three — an API.Files call is deliberately not once-only evidence, since re-expansion enters that boundary before the durable effect restores. architecture.md, workflow-workspace-spec §§8.4/9, executable-mdx-spec and DEC-015 record the basis semantics and the non-causal DEC-034 conformance of the Operation evaluator. * 🎨 Wrap the new generated-XMD cases the way oxfmt wants them Mechanical only: line-wrapping in the two suites this stack added cases to. No assertion, fixture or behavior changes. * 📝 Say why the retained root order is deterministic WGAC4 justified the sorted-order assertion by a continuation comparing roots positionally. It no longer does — the basis is asked for by membership — so the order is record stability rather than what the comparison turns on. The assertion is unchanged; only its reason was untrue. --------- Co-authored-by: Taras Mankovski <[email protected]>
1 parent 46786f8 commit e84c0a7

13 files changed

Lines changed: 848 additions & 119 deletions

‎architecture.md‎

Lines changed: 41 additions & 16 deletions
Large diffs are not rendered by default.

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

Lines changed: 256 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -861,8 +861,14 @@ function productionHost(root: string, calls: AgentCalls, events: string[] = []):
861861
};
862862
}
863863

864-
/** A committed definition whose root document is `source`. */
865-
function useCheckpointFixture(source: string): Operation<Fixture> {
864+
/**
865+
* A committed definition whose root document is `source`, beside any bundled
866+
* Markdown components the root declares — every file from the same commit.
867+
*/
868+
function useCheckpointFixture(
869+
source: string,
870+
components: Record<string, string> = {},
871+
): Operation<Fixture> {
866872
return resource<Fixture>(function* (provide) {
867873
const repository = yield* until(mkdtemp(join(tmpdir(), "xmd-ckx-repo-")));
868874
yield* ensure(function* () {
@@ -873,12 +879,51 @@ function useCheckpointFixture(source: string): Operation<Fixture> {
873879
yield* git(repository, ["config", "user.name", "CKX"]);
874880
yield* writeTextFile(join(repository, "workflow.md"), source);
875881
yield* git(repository, ["add", "workflow.md"]);
882+
for (const [name, content] of Object.entries(components)) {
883+
yield* writeTextFile(join(repository, `${name}.md`), content);
884+
yield* git(repository, ["add", `${name}.md`]);
885+
}
876886
yield* git(repository, ["-c", "commit.gpgsign=false", "commit", "--quiet", "-m", "definition"]);
877887
const objectId = (yield* git(repository, ["rev-parse", "HEAD:workflow.md"])).trim();
878888
yield* provide({ repository, objectId, contents: source });
879889
});
880890
}
881891

892+
/**
893+
* The Git capability answered from the fixture repository itself.
894+
*
895+
* A bundled definition reads more than one object — the root and each declared
896+
* component, each pinned by its own blob id — so the single-object `useGit`
897+
* stub cannot answer for it. Every question shells to the fixture repository,
898+
* which is what the production capability does from the run's own directory.
899+
*/
900+
function useRepositoryGit(repository: string): Operation<void> {
901+
return Git.around(
902+
{
903+
// deno-lint-ignore require-yield
904+
*repositoryRoot(): Operation<string> {
905+
return repository;
906+
},
907+
*revParse([revision]): Operation<string> {
908+
return (yield* git(repository, [
909+
"rev-parse",
910+
"--verify",
911+
"--end-of-options",
912+
revision,
913+
])).trim();
914+
},
915+
*readObject([commit, path]): Operation<string> {
916+
return yield* git(repository, ["cat-file", "blob", `${commit}:${path}`]);
917+
},
918+
// deno-lint-ignore require-yield
919+
*objectFormat(): Operation<"sha1" | "sha256"> {
920+
return "sha1";
921+
},
922+
},
923+
{ at: "min" },
924+
);
925+
}
926+
882927
/** What `xmd workflow start` establishes, through the command's own module. */
883928
function* startFor(fixture: Fixture): Operation<WorkflowStart> {
884929
const established = yield* establishDefinition(join(fixture.repository, "workflow.md"));
@@ -991,6 +1036,46 @@ function journalled(path: string, type: string): number {
9911036
}
9921037
}
9931038

1039+
/** The Workspace roots this run has published, and the one it stands on. */
1040+
function workspaceRootState(path: string): { retained: number; current: string } {
1041+
const database = new DatabaseSync(path, { readOnly: true });
1042+
try {
1043+
const retained = Number(
1044+
database.prepare("SELECT COUNT(*) AS count FROM workspace_roots").get()?.["count"],
1045+
);
1046+
const current = String(
1047+
database
1048+
.prepare("SELECT current_root_id FROM workspace_state WHERE singleton_id = 1")
1049+
.get()?.["current_root_id"],
1050+
);
1051+
return { retained, current };
1052+
} finally {
1053+
database.close();
1054+
}
1055+
}
1056+
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,172 @@ 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 another live execution or root publication —
1307+
* which the existing root-level checkpoint above does not discriminate.
1308+
*
1309+
* The once-only proof here is stability: the exact journal counts, the ordered
1310+
* durable subsequence, the Workspace root-publication count, and the
1311+
* authoritative current root are captured at suspension and must survive
1312+
* answer delivery and the completed resume unchanged. An `API.Files` call is
1313+
* deliberately not evidence — document re-expansion legitimately enters that
1314+
* boundary again before the durable `workspace_file` effect underneath
1315+
* restores, so a call count there sits above the live/restore decision.
1316+
*/
1317+
describe("Tier WGAC — generated effects in a bundled component resume through a later wait", () => {
1318+
/** One root declaring one bundled component, with the wait after both. */
1319+
function bundledRoot(setup: string, componentName: string): string {
1320+
return `---
1321+
workflow:
1322+
components:
1323+
${componentName}: ./${componentName}.md
1324+
---
1325+
${setup}
1326+
<${componentName} />
1327+
1328+
<File path="after.md">
1329+
parent marker
1330+
</File>
1331+
1332+
<Elicit schema={${CHECKPOINT_SCHEMA}} as="decision">
1333+
Proceed with the change?
1334+
</Elicit>
1335+
1336+
decision: {decision.proceed}
1337+
`;
1338+
}
1339+
1340+
const CASES = [
1341+
{
1342+
what: "read",
1343+
componentName: "Observe",
1344+
component: `<Evaluate source={"<File path=\\"notes.md\\" />"} allow={["read"]} as="observed" />\n`,
1345+
setup: `
1346+
<File path="notes.md">
1347+
the retained note
1348+
</File>
1349+
`,
1350+
nested: [{ operation: "read", target: "notes.md" }],
1351+
files: 3,
1352+
},
1353+
{
1354+
what: "write",
1355+
componentName: "Propose",
1356+
component: `<Evaluate source={"<File path=\\"proposed.md\\">a generated proposal</File>"} allow={["write"]} as="observed" />\n`,
1357+
setup: "",
1358+
nested: [{ operation: "write", target: "proposed.md" }],
1359+
files: 2,
1360+
},
1361+
] as const;
1362+
1363+
for (const bundled of CASES) {
1364+
it(`WGAC16: a generated ${bundled.what} inside a bundled component resumes through the later wait`, function* () {
1365+
const store = yield* useRunStore();
1366+
const fixture = yield* useCheckpointFixture(
1367+
bundledRoot(bundled.setup, bundled.componentName),
1368+
{ [bundled.componentName]: bundled.component },
1369+
);
1370+
yield* useRepositoryGit(fixture.repository);
1371+
1372+
const calls: AgentCalls = { prompts: [] };
1373+
const rendered: string[] = [];
1374+
const started = yield* invoke(
1375+
{ ...REQUEST, action: "start" },
1376+
yield* startFor(fixture),
1377+
productionHost(store, calls),
1378+
pinnedBody(rendered),
1379+
);
1380+
expect(started.exitCode).toBe(2);
1381+
1382+
const runId = String(started.written.err.find((line) => line.startsWith("workflow run: ")))
1383+
.slice("workflow run: ".length)
1384+
.trim();
1385+
const path = workflowRunPath(store, runId);
1386+
1387+
// The start settled suspended, with the nested effect and the later
1388+
// parent effect committed ahead of the wait. The journal counts and the
1389+
// Workspace root publications captured here are the once-only baseline
1390+
// everything after the suspension is held to.
1391+
const suspended = retained(path);
1392+
expect(suspended.status).toBe("suspended");
1393+
expect(suspended.requests).toHaveLength(1);
1394+
expect(rendered).toEqual([]);
1395+
const atSuspension = counts(path);
1396+
expect(atSuspension).toEqual({
1397+
[PROMPT_EFFECT]: 0,
1398+
[EVALUATION_EFFECT]: 1,
1399+
[FILE_EFFECT]: bundled.files,
1400+
});
1401+
const rootsAtSuspension = workspaceRootState(path);
1402+
1403+
// The relevant ordered subsequence, exactly: the admission, the nested
1404+
// generated effect in authored order, the later parent effect, then the
1405+
// suspension request. Component imports journal beside these and are not
1406+
// part of the ordering under test.
1407+
const relevant = new Set([PROMPT_EFFECT, EVALUATION_EFFECT, FILE_EFFECT, SUSPENSION_REQUEST]);
1408+
const effects = orderedEffects(path).filter((effect) => relevant.has(effect.type));
1409+
const admission = effects.findIndex((effect) => effect.type === EVALUATION_EFFECT);
1410+
expect(admission).toBeGreaterThanOrEqual(0);
1411+
const sequence = effects.slice(admission);
1412+
expect(sequence.map((effect) => effect.type)).toEqual([
1413+
EVALUATION_EFFECT,
1414+
FILE_EFFECT,
1415+
FILE_EFFECT,
1416+
SUSPENSION_REQUEST,
1417+
]);
1418+
for (const [index, expected] of bundled.nested.entries()) {
1419+
expect(sequence[1 + index]?.name.startsWith(`${expected.operation}:`)).toBe(true);
1420+
expect(sequence[1 + index]?.name.endsWith(`:/${expected.target}`)).toBe(true);
1421+
}
1422+
const parent = sequence[1 + bundled.nested.length];
1423+
expect(parent?.name.startsWith("write:")).toBe(true);
1424+
expect(parent?.name.endsWith(":/after.md")).toBe(true);
1425+
1426+
// The delivery retains the answer and executes nothing.
1427+
const suspensionId = suspended.requests[0] ?? "";
1428+
const delivered = yield* manage(
1429+
{ action: "answer", runId, suspensionId, value: { proceed: true }, secretDetection: true },
1430+
productionHost(store, calls),
1431+
);
1432+
expect(delivered.exitCode).toBe(0);
1433+
expect(retained(path)).toEqual(suspended);
1434+
expect(counts(path)).toEqual(atSuspension);
1435+
expect(workspaceRootState(path)).toEqual(rootsAtSuspension);
1436+
1437+
// The resume completes and restores every committed effect: the same
1438+
// journal counts, the same ordered durable subsequence, the same root
1439+
// publications, and the same authoritative current root.
1440+
const resumed = yield* invoke(
1441+
{ ...REQUEST, action: "resume", target: runId },
1442+
undefined,
1443+
productionHost(store, calls),
1444+
pinnedBody(rendered),
1445+
);
1446+
expect(resumed.exitCode).toBe(0);
1447+
1448+
const completed = retained(path);
1449+
expect(completed.status).toBe("completed");
1450+
expect(counts(path)).toEqual(atSuspension);
1451+
expect(workspaceRootState(path)).toEqual(rootsAtSuspension);
1452+
expect(
1453+
orderedEffects(path)
1454+
.filter((effect) => relevant.has(effect.type))
1455+
.slice(admission, admission + sequence.length),
1456+
).toEqual(sequence);
1457+
1458+
// The delivered value reaches the document after the wait.
1459+
expect(rendered).toHaveLength(1);
1460+
expect(rendered[0]).toContain("decision: true");
1461+
expect(answers(path)[0]?.state).toBe("consumed");
1462+
});
1463+
}
1464+
});

‎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

0 commit comments

Comments
 (0)