@elaraai/e3-api-tests 1.0.83 → 1.0.85

package/dist/src/suites/dataflow.js

@@ -5,16 +5,35 @@
 /**
  * Dataflow execution test suite.
  *
- * Tests: start, execute (blocking), poll for completion, logs
+ * Tests: start, execute (blocking), poll for completion, logs, and failures.
+ * A failing task fails in East, which every server runs: it is recorded
+ * `failed`, exit code 1, with its message in its stderr log. One case runs a
+ * command, a custom task's, which a server that runs no commands records
+ * `error` ({@link TestContext.commands}).
  */
 import { describe, it } from 'node:test';
 import assert from 'node:assert/strict';
 import { readFileSync } from 'node:fs';
-import { IntegerType, StringType, encodeBeast2For, decodeBeast2For, variant } from '@elaraai/east';
-import { packageImport, workspaceCreate, workspaceDeploy, workspaceStatus, dataflowExecuteLaunch, dataflowExecute, dataflowExecutePoll, dataflowCancel, dataflowGraph, datasetSet, datasetGet, taskLogs, taskExecutionList, ApiError, } from '@elaraai/e3-api-client';
-import { createPackageZip, createDiamondPackageZip, createFailingPackageZip, createSlowPackageZip, createParallelMixedPackageZip, createFailingDiamondPackageZip, createWideParallelPackageZip, createSlowDiamondPackageZip, } from '../fixtures.js';
-import { assertDataflowSucceeded } from '../assertions.js';
+import { IntegerType, StringType, encodeBeast2For, decodeBeast2For, isValueOf, lessFor, variant } from '@elaraai/east';
+import { TaskLogChunkType } from '@elaraai/e3-types';
+import { packageImport, workspaceCreate, workspaceDeploy, workspaceStatus, dataflowExecuteLaunch, dataflowExecute, dataflowExecutePoll, dataflowEventsRemain, dataflowCancel, dataflowGraph, datasetSet, datasetGet, taskLogs, taskExecutionList, ApiError, } from '@elaraai/e3-api-client';
+import { LOGGED_LINES, createPackageZip, createDiamondPackageZip, createFailingPackageZip, createLoggingPackageZip, createCommandPackageZip, createSlowPackageZip, createParallelMixedPackageZip, createFailingDiamondPackageZip, createWideParallelPackageZip, createSlowDiamondPackageZip, } from '../fixtures.js';
+import { MALFORMED_WORKSPACE_NAMES, assertDataflowSucceeded, describeDataflowResult, refusedAsWorkspaceName } from '../assertions.js';
 import { waitFor } from '../cli.js';
+/**
+ * Asserts a call is refused `bad_request`, with the message the server gives.
+ *
+ * @param call - The refused call
+ * @param message - The server's message, whole
+ */
+async function rejectsBadRequest(call, message) {
+    await assert.rejects(call, (err) => {
+        assert.ok(err instanceof ApiError, `Expected ApiError, got ${String(err)}`);
+        assert.strictEqual(err.code, 'bad_request');
+        assert.strictEqual(err.details, message);
+        return true;
+    });
+}
 /** Helper: import package, create workspace, deploy */
 function withDeployed(setup, createZip, pkgName, wsName) {
     return async (t) => {
@@ -55,6 +74,7 @@ export function dataflowTests(setup) {
     const withSimpleExec = withDeployed(setup, createPackageZip, 'exec-pkg', 'exec-ws');
     const withDiamond = withDeployed(setup, createDiamondPackageZip, 'diamond-pkg', 'diamond-ws');
     const withFailing = withDeployed(setup, createFailingPackageZip, 'fail-pkg', 'fail-ws');
+    const withCommand = withDeployed(setup, createCommandPackageZip, 'cmd-pkg', 'cmd-ws');
     const withMixed = withDeployed(setup, createParallelMixedPackageZip, 'mixed-pkg', 'mixed-ws');
     const withFailingDiamond = withDeployed(setup, createFailingDiamondPackageZip, 'fdiamond-pkg', 'fdiamond-ws');
     const withWideParallel = async (t) => {
@@ -90,8 +110,9 @@ export function dataflowTests(setup) {
     const withNoExec = withDeployed(setup, createPackageZip, 'noexec-pkg', 'noexec-ws');
     const withCache = withDeployed(setup, createPackageZip, 'cache-pkg', 'cache-ws');
     const withFilter = withDeployed(setup, createDiamondPackageZip, 'filter-pkg', 'filter-ws');
+    const withForced = withDeployed(setup, createDiamondPackageZip, 'forced-pkg', 'forced-ws');
     const withGraph = withDeployed(setup, createDiamondPackageZip, 'graph-pkg', 'graph-ws');
-    const withLogPag = withDeployed(setup, createPackageZip, 'logpag-pkg', 'logpag-ws');
+    const withLogPag = withDeployed(setup, createLoggingPackageZip, 'logpag-pkg', 'logpag-ws');
     const withEvtPag = withDeployed(setup, createDiamondPackageZip, 'evtpag-pkg', 'evtpag-ws');
     describe('dataflow', { concurrency: false }, () => {
         describe('simple execution', { concurrency: false }, () => {
@@ -115,21 +136,39 @@ export function dataflowTests(setup) {
                 assert.ok(outputDataset, 'Output dataset .tasks.compute.output should exist');
                 assert.strictEqual(outputDataset.status.type, 'up-to-date');
             });
-            it('taskExecutionList lists the latest attempt per inputs by default and every attempt with all', async (t) => {
+            it('taskExecutionList lists a task\'s runs the latest first, a page at a time, each naming its execution', async (t) => {
+                const ctx = await withSimpleExec(t);
+                const opts = await ctx.opts();
+                const list = (page = {}) => taskExecutionList(ctx.config.baseUrl, ctx.repoName, 'exec-ws', 'compute', opts, page);
+                // Three forced runs of the same inputs: three runs under one inputs hash.
+                for (let run = 0; run < 3; run++) {
+                    assertDataflowSucceeded(await dataflowExecute(ctx.config.baseUrl, ctx.repoName, 'exec-ws', { force: true }, opts));
+                }
+                const every = await list();
+                assert.strictEqual(every.length, 3, 'every run is listed');
+                assert.ok(every.every(e => e.inputsHash === every[0].inputsHash && e.status.type === 'success'), 'all runs share the inputs hash');
+                const ids = every.map(e => e.executionId);
+                assert.strictEqual(new Set(ids).size, ids.length, 'each run names its own execution');
+                assert.deepStrictEqual(ids, [...ids].sort().reverse(), 'the latest first');
+                // A page at a time, each from before the last run of the page before
+                const first = await list({ limit: 2 });
+                assert.deepStrictEqual(first.map(e => e.executionId), ids.slice(0, 2));
+                const next = await list({ limit: 2, before: first[1].executionId });
+                assert.deepStrictEqual(next.map(e => e.executionId), ids.slice(2), 'the next page holds the runs before it');
+                assert.deepStrictEqual(await list({ before: ids[2] }), [], 'and the page after it is empty');
+            });
+            it('refuses a page of a task\'s runs whose limit is not a positive integer, or whose cursor is no execution\'s id', async (t) => {
                 const ctx = await withSimpleExec(t);
                 const opts = await ctx.opts();
-                // Two forced runs of the same inputs: two attempts under one inputs hash.
-                assertDataflowSucceeded(await dataflowExecute(ctx.config.baseUrl, ctx.repoName, 'exec-ws', { force: true }, opts));
-                assertDataflowSucceeded(await dataflowExecute(ctx.config.baseUrl, ctx.repoName, 'exec-ws', { force: true }, opts));
-                const latest = await taskExecutionList(ctx.config.baseUrl, ctx.repoName, 'exec-ws', 'compute', opts);
-                assert.strictEqual(latest.length, 1, 'one item per distinct inputs hash');
-                assert.strictEqual(latest[0].status.type, 'success');
-                const every = await taskExecutionList(ctx.config.baseUrl, ctx.repoName, 'exec-ws', 'compute', opts, { all: true });
-                assert.ok(every.length >= 2, `every attempt is listed, got ${every.length}`);
-                assert.ok(every.every(e => e.inputsHash === latest[0].inputsHash), 'all attempts share the inputs hash');
-                assert.strictEqual(new Set(every.map(e => e.startedAt)).size, every.length, 'attempts are distinct runs');
-                const newest = every.map(e => e.startedAt).sort().at(-1);
-                assert.strictEqual(latest[0].startedAt, newest, 'the default item is the newest attempt');
+                const list = (page) => taskExecutionList(ctx.config.baseUrl, ctx.repoName, 'exec-ws', 'compute', opts, page);
+                await rejectsBadRequest(list({ limit: 0 }), 'limit must be a positive integer, got "0"');
+                await rejectsBadRequest(list({ limit: 1.5 }), 'limit must be a positive integer, got "1.5"');
+                await assert.rejects(list({ before: 'not-an-id' }), (err) => {
+                    assert.ok(err instanceof ApiError, `Expected ApiError, got ${String(err)}`);
+                    assert.strictEqual(err.code, 'invalid_name');
+                    assert.strictEqual(err.details?.kind, 'execution id');
+                    return true;
+                });
             });
             it('dataflowExecuteLaunch triggers execution (non-blocking)', async (t) => {
                 const ctx = await withSimpleExec(t);
@@ -185,12 +224,33 @@ export function dataflowTests(setup) {
                 await dataflowExecute(ctx.config.baseUrl, ctx.repoName, 'exec-ws', { force: true }, opts);
                 // Get logs
                 const logs = await taskLogs(ctx.config.baseUrl, ctx.repoName, 'exec-ws', 'compute', { stream: 'stdout' }, opts);
-                // Logs should be returned (may be empty for simple tasks)
-                assert.ok(typeof logs.data === 'string');
-                assert.ok(typeof logs.offset === 'bigint');
-                assert.ok(typeof logs.size === 'bigint');
-                assert.ok(typeof logs.totalSize === 'bigint');
-                assert.ok(typeof logs.complete === 'boolean');
+                // A chunk of its log, which may be empty for a simple task
+                assert.ok(isValueOf(logs, TaskLogChunkType), 'a TaskLogChunk');
+            });
+            it('taskLogs names the execution it reads, and whether it has ended, and reads the one a request names', async (t) => {
+                const ctx = await withLogPag(t);
+                const opts = await ctx.opts();
+                const read = (logOptions = {}) => taskLogs(ctx.config.baseUrl, ctx.repoName, 'logpag-ws', 'log', { stream: 'stdout', ...logOptions }, opts);
+                const latest = async () => (await taskExecutionList(ctx.config.baseUrl, ctx.repoName, 'logpag-ws', 'log', opts, { limit: 1 }))[0];
+                // A run's log names the run, which has ended
+                assertDataflowSucceeded(await dataflowExecute(ctx.config.baseUrl, ctx.repoName, 'logpag-ws', { force: true }, opts));
+                const first = await latest();
+                const logs = await read();
+                assert.deepStrictEqual([logs.inputsHash, logs.executionId, logs.ended], [first.inputsHash, first.executionId, true]);
+                // Another run is the task's current execution, and a request naming
+                // the first still reads the first
+                assertDataflowSucceeded(await dataflowExecute(ctx.config.baseUrl, ctx.repoName, 'logpag-ws', { force: true }, opts));
+                const second = await latest();
+                assert.notStrictEqual(second.executionId, first.executionId, 'the run is another execution');
+                assert.strictEqual((await read()).executionId, second.executionId);
+                const named = await read({ offset: 5, execution: { inputsHash: first.inputsHash, executionId: first.executionId } });
+                assert.deepStrictEqual([named.executionId, named.data], [first.executionId, LOGGED_LINES.slice(5)]);
+                // An execution the task does not record is none
+                await assert.rejects(read({ execution: { inputsHash: first.inputsHash, executionId: '0190a0b0-4444-7000-8000-000000000000' } }), (err) => {
+                    assert.ok(err instanceof ApiError, `Expected ApiError, got ${String(err)}`);
+                    assert.strictEqual(err.code, 'execution_not_found');
+                    return true;
+                });
             });
         });
         describe('diamond dependency execution', { concurrency: false }, () => {
@@ -234,15 +294,18 @@ export function dataflowTests(setup) {
                 const opts = await ctx.opts();
                 // Start execution
                 await dataflowExecuteLaunch(ctx.config.baseUrl, ctx.repoName, 'diamond-ws', { force: true }, opts);
-                // Poll and collect events
+                // Poll and collect events, each poll from the cursor the last gave
                 const events = [];
+                let since = 0n;
                 const maxWait = 60000;
                 const startTime = Date.now();
                 while (Date.now() - startTime < maxWait) {
-                    const state = await dataflowExecutePoll(ctx.config.baseUrl, ctx.repoName, 'diamond-ws', { offset: events.length }, opts);
+                    const state = await dataflowExecutePoll(ctx.config.baseUrl, ctx.repoName, 'diamond-ws', { since }, opts);
                     // Collect new events
                     events.push(...state.events);
-                    if (state.status.type === 'completed' || state.status.type === 'failed') {
+                    since = state.nextSeq;
+                    // The run's end is its last word once no event of it is left
+                    if ((state.status.type === 'completed' || state.status.type === 'failed') && !dataflowEventsRemain(state)) {
                         break;
                     }
                     await new Promise(r => setTimeout(r, 100));
@@ -265,7 +328,8 @@ export function dataflowTests(setup) {
                 assert.strictEqual(result.executed, 0n);
                 assert.strictEqual(result.tasks.length, 1);
                 assert.strictEqual(result.tasks[0].name, 'failing');
-                assert.strictEqual(result.tasks[0].state.type, 'failed');
+                // The body's own failure: its runner records it, and exits 1
+                assert.deepStrictEqual(result.tasks[0].state, variant('failed', { exitCode: 1n }));
             });
             it('dataflowExecutePoll shows failed status after task failure', async (t) => {
                 const ctx = await withFailing(t);
@@ -304,6 +368,33 @@ export function dataflowTests(setup) {
                 assert.strictEqual(result2.failed, 1n);
             });
         });
+        // The suites' one command: a custom task's. Every other task is East,
+        // which every server runs; a server that runs no commands — e3 in a page —
+        // records the task error, saying so.
+        describe('command task', { concurrency: false }, () => {
+            it('records a failing command failed, or error on a server that runs no commands', async (t) => {
+                const ctx = await withCommand(t);
+                const opts = await ctx.opts();
+                const result = await dataflowExecute(ctx.config.baseUrl, ctx.repoName, 'cmd-ws', { force: true }, opts);
+                assert.strictEqual(result.success, false);
+                assert.strictEqual(result.failed, 1n);
+                assert.strictEqual(result.executed, 0n);
+                assert.strictEqual(result.tasks.length, 1);
+                const task = result.tasks[0];
+                assert.strictEqual(task.name, 'command');
+                if (ctx.commands) {
+                    // The command ran, and exited 1
+                    assert.deepStrictEqual(task.state, variant('failed', { exitCode: 1n }), describeDataflowResult(result));
+                }
+                else {
+                    // Nothing ran, and the server says why
+                    if (task.state.type !== 'error') {
+                        assert.fail(`expected the command task recorded error on a server that runs no commands\n${describeDataflowResult(result)}`);
+                    }
+                    assert.match(task.state.value.message, /runs no commands/);
+                }
+            });
+        });
         describe('parallel task failures', { concurrency: false }, () => {
             describe('mixed success/failure', { concurrency: false }, () => {
                 it('parallel tasks with mixed success/failure complete without stalling', async (t) => {
@@ -313,10 +404,10 @@ export function dataflowTests(setup) {
                     // Dataflow should complete (not stall) and report failure
                     assert.strictEqual(result.success, false);
                     assert.strictEqual(result.failed, 1n);
-                    // The failing task must be reported
+                    // The failing task must be reported: its body's failure, exit code 1
                     const failC = result.tasks.find(t => t.name === 'fail_c');
                     assert.ok(failC, 'fail_c task should be in results');
-                    assert.strictEqual(failC.state.type, 'failed');
+                    assert.deepStrictEqual(failC.state, variant('failed', { exitCode: 1n }));
                     // Tasks that did execute should have succeeded
                     for (const task of result.tasks) {
                         if (task.name !== 'fail_c') {
@@ -331,18 +422,24 @@ export function dataflowTests(setup) {
                     await dataflowExecute(ctx.config.baseUrl, ctx.repoName, 'mixed-ws', { force: true }, opts);
                     // taskLogs for failed task should NOT throw
                     const logs = await taskLogs(ctx.config.baseUrl, ctx.repoName, 'mixed-ws', 'fail_c', { stream: 'stderr' }, opts);
-                    assert.ok(typeof logs.data === 'string', 'logs.data should be a string');
-                    assert.ok(typeof logs.complete === 'boolean', 'logs.complete should be a boolean');
+                    assert.ok(isValueOf(logs, TaskLogChunkType), 'a TaskLogChunk');
+                    // Its stderr holds the failure's message, which its body made from
+                    // its input as it ran
+                    assert.match(logs.data, /fail_c fails, given 3/);
                 });
                 it('workspace status reflects failed tasks correctly', async (t) => {
                     const ctx = await withMixed(t);
                     const opts = await ctx.opts();
                     await dataflowExecute(ctx.config.baseUrl, ctx.repoName, 'mixed-ws', { force: true }, opts);
                     const status = await workspaceStatus(ctx.config.baseUrl, ctx.repoName, 'mixed-ws', opts);
-                    // Failed task should show 'failed' status, not stuck as 'in-progress'
+                    // Failed task should show 'failed' status, not stuck as 'in-progress',
+                    // with the exit code its runner gave its body's failure
                     const failedTask = status.tasks.find(t => t.name === 'fail_c');
                     assert.ok(failedTask, 'fail_c task should be in workspace status');
-                    assert.strictEqual(failedTask.status.type, 'failed', 'Failed task should have failed status');
+                    if (failedTask.status.type !== 'failed') {
+                        assert.fail(`Failed task should have failed status, got ${failedTask.status.type}`);
+                    }
+                    assert.strictEqual(failedTask.status.value.exitCode, 1n);
                     // No task should be stuck as 'in-progress'
                     for (const task of status.tasks) {
                         assert.notStrictEqual(task.status.type, 'in-progress', `Task ${task.name} should not be stuck in-progress`);
@@ -365,7 +462,7 @@ export function dataflowTests(setup) {
                     assert.ok(rightTask, 'right task should be in results');
                     assert.ok(mergeTask, 'merge task should be in results');
                     assert.strictEqual(leftTask.state.type, 'success');
-                    assert.strictEqual(rightTask.state.type, 'failed');
+                    assert.deepStrictEqual(rightTask.state, variant('failed', { exitCode: 1n }));
                     assert.strictEqual(mergeTask.state.type, 'skipped');
                 });
                 it('taskLogs returns execution_not_found for skipped task', async (t) => {
@@ -461,18 +558,47 @@ export function dataflowTests(setup) {
                 }, 60000);
                 assert.strictEqual(finalStatus, 'aborted');
             });
+            it('serves why a cancelled run\'s task stopped, in the task\'s history and its status', async (t) => {
+                const ctx = await withSlow(t);
+                const opts = await ctx.opts();
+                const history = () => taskExecutionList(ctx.config.baseUrl, ctx.repoName, 'slow-ws', 'slow', opts);
+                await dataflowExecuteLaunch(ctx.config.baseUrl, ctx.repoName, 'slow-ws', { force: true }, opts);
+                // The task's attempt is recorded running before the cancel, so the
+                // cancel stops that attempt. Its log says it has not ended.
+                await waitFor(async () => (await history()).some((item) => item.status.type === 'running'), 60000);
+                const live = await taskLogs(ctx.config.baseUrl, ctx.repoName, 'slow-ws', 'slow', { stream: 'stderr' }, opts);
+                assert.strictEqual(live.ended, false, 'the log of an execution still running has not ended');
+                await dataflowCancel(ctx.config.baseUrl, ctx.repoName, 'slow-ws', opts);
+                const cancelled = (items) => items.find((item) => item.status.type === 'cancelled');
+                await waitFor(async () => cancelled(await history()) !== undefined, 60000);
+                const stopped = cancelled(await history());
+                if (stopped?.reason.type !== 'some')
+                    assert.fail('a cancelled attempt says why it stopped');
+                assert.strictEqual(stopped.reason.value.kind.type, 'aborted');
+                assert.notStrictEqual(stopped.reason.value.message, '', 'in words, as its log\'s last line does');
+                const ended = await taskLogs(ctx.config.baseUrl, ctx.repoName, 'slow-ws', 'slow', {
+                    stream: 'stderr', execution: { inputsHash: live.inputsHash, executionId: live.executionId },
+                }, opts);
+                assert.strictEqual(ended.ended, true, 'and once it is cancelled, it has');
+                // The task reads ready, naming why its latest attempt stopped.
+                const task = (await workspaceStatus(ctx.config.baseUrl, ctx.repoName, 'slow-ws', opts)).tasks.find((each) => each.name === 'slow');
+                assert.ok(task !== undefined, 'the task is in the status');
+                assert.strictEqual(task.status.type, 'ready');
+                if (task.stopped.type !== 'some')
+                    assert.fail('the status names why the task\'s attempt stopped');
+                assert.strictEqual(task.stopped.value.kind.type, 'aborted');
+            });
             it('dataflowCancel returns error when no execution is running', async (t) => {
                 const ctx = await withSlow(t);
                 const opts = await ctx.opts();
-                // Try to cancel when nothing is running
-                try {
-                    await dataflowCancel(ctx.config.baseUrl, ctx.repoName, 'slow-ws', opts);
-                    assert.fail('Should have thrown an error');
-                }
-                catch (err) {
-                    assert.ok(err instanceof Error);
-                    // Expect error about no active execution
-                }
+                // Nothing is running to cancel: the server says so, as the request
+                // meeting the workspace's state rather than a fault of its own
+                await assert.rejects(dataflowCancel(ctx.config.baseUrl, ctx.repoName, 'slow-ws', opts), (err) => {
+                    assert.ok(err instanceof ApiError, `Expected ApiError, got ${String(err)}`);
+                    assert.strictEqual(err.code, 'dataflow_error');
+                    assert.strictEqual(err.details?.message, 'No active execution for this workspace');
+                    return true;
+                });
             });
         });
         // Concurrent set during execution - tests that datasetSet is not blocked by dataflowExecuteLaunch
@@ -627,6 +753,17 @@ export function dataflowTests(setup) {
                     assert.ok(err.code === 'workspace_not_found' || err.code === 'workspace_not_deployed', `Expected workspace_not_found or workspace_not_deployed, got ${err.code}`);
                 }
             });
+            it('dataflowExecuteLaunch refuses a name no workspace can have as invalid_name of a workspace, before it takes a lock', async (t) => {
+                const ctx = await setup(t);
+                const opts = await ctx.opts();
+                // Each is refused as a workspace's name, whatever orchestrator runs
+                // the repository's dataflows: `bad:name` not as a lock's, and
+                // `main#dataflow` without taking the lock a run of main's dataflow
+                // holds.
+                for (const [name, why] of MALFORMED_WORKSPACE_NAMES) {
+                    await assert.rejects(dataflowExecuteLaunch(ctx.config.baseUrl, ctx.repoName, name, { force: true }, opts), refusedAsWorkspaceName(name, why));
+                }
+            });
             it('dataflowGraph returns error for non-existent workspace', async (t) => {
                 const ctx = await setup(t);
                 const opts = await ctx.opts();
@@ -701,6 +838,42 @@ export function dataflowTests(setup) {
                 }
             });
         });
+        // A run forces every task, none, or the tasks it names. The diamond's left
+        // and right read the inputs, and merge reads both.
+        describe('forcing named tasks', { concurrency: false }, () => {
+            it('re-runs the tasks a run names, and serves the rest from the cache while their inputs hold', async (t) => {
+                const ctx = await withForced(t);
+                const opts = await ctx.opts();
+                assertDataflowSucceeded(await dataflowExecute(ctx.config.baseUrl, ctx.repoName, 'forced-ws', {}, opts), 'first run');
+                const result = await dataflowExecute(ctx.config.baseUrl, ctx.repoName, 'forced-ws', { force: ['left'] }, opts);
+                assertDataflowSucceeded(result, 'forced run');
+                // left runs again and writes what it wrote before, so merge, which
+                // reads it, is served from the cache as right is.
+                assert.deepStrictEqual(['left', 'right', 'merge'].map((name) => [name, result.tasks.find((task) => task.name === name)?.cached]), [['left', false], ['right', true], ['merge', true]], describeDataflowResult(result));
+            });
+            it('refuses a start forcing a task the graph lacks, or one the filter leaves out, before anything runs', async (t) => {
+                const ctx = await withForced(t);
+                const opts = await ctx.opts();
+                await assert.rejects(dataflowExecuteLaunch(ctx.config.baseUrl, ctx.repoName, 'forced-ws', { force: ['left', 'no_such_task'] }, opts), (err) => {
+                    assert.ok(err instanceof ApiError, `Expected ApiError, got ${String(err)}`);
+                    assert.strictEqual(err.code, 'task_not_found');
+                    assert.strictEqual(err.details?.task, 'no_such_task');
+                    return true;
+                });
+                await assert.rejects(dataflowExecuteLaunch(ctx.config.baseUrl, ctx.repoName, 'forced-ws', { force: ['right'], filter: 'left' }, opts), (err) => {
+                    assert.ok(err instanceof ApiError, `Expected ApiError, got ${String(err)}`);
+                    assert.strictEqual(err.code, 'dataflow_error');
+                    assert.strictEqual(err.details?.message, "the run forces 'right', which the filter 'left' leaves out: a filtered run runs 'left' and the tasks it depends on, and no other");
+                    return true;
+                });
+                // Neither started a run.
+                await assert.rejects(dataflowExecutePoll(ctx.config.baseUrl, ctx.repoName, 'forced-ws', {}, opts), (err) => {
+                    assert.ok(err instanceof ApiError, `Expected ApiError, got ${String(err)}`);
+                    assert.strictEqual(err.code, 'execution_not_found');
+                    return true;
+                });
+            });
+        });
         describe('dependency graph', { concurrency: false }, () => {
             it('dataflowGraph returns correct structure', async (t) => {
                 const ctx = await withGraph(t);
@@ -727,43 +900,143 @@ export function dataflowTests(setup) {
             it('taskLogs supports offset and limit', async (t) => {
                 const ctx = await withLogPag(t);
                 const opts = await ctx.opts();
-                // Execute to generate logs
-                await dataflowExecute(ctx.config.baseUrl, ctx.repoName, 'logpag-ws', { force: true }, opts);
-                // Get full logs
-                const full = await taskLogs(ctx.config.baseUrl, ctx.repoName, 'logpag-ws', 'compute', { stream: 'stdout' }, opts);
-                // Skip test if log is too short for meaningful pagination
-                if (full.totalSize < 5n) {
-                    return;
+                const read = (logOptions) => taskLogs(ctx.config.baseUrl, ctx.repoName, 'logpag-ws', 'log', { stream: 'stdout', ...logOptions }, opts);
+                const total = BigInt(LOGGED_LINES.length);
+                // The task writes three known lines to its stdout
+                assertDataflowSucceeded(await dataflowExecute(ctx.config.baseUrl, ctx.repoName, 'logpag-ws', { force: true }, opts));
+                // The whole log
+                const full = await read({});
+                assert.strictEqual(full.data, LOGGED_LINES);
+                assert.strictEqual(full.offset, 0n);
+                assert.strictEqual(full.size, total);
+                assert.strictEqual(full.totalSize, total);
+                assert.strictEqual(full.complete, true);
+                // Its first 5 bytes: a limit cuts it, short of its end
+                const head = await read({ offset: 0, limit: 5 });
+                assert.strictEqual(head.data, 'line ');
+                assert.strictEqual(head.offset, 0n);
+                assert.strictEqual(head.size, 5n);
+                assert.strictEqual(head.totalSize, total);
+                assert.strictEqual(head.complete, false);
+                // A window from byte 5: an offset and a limit together
+                const middle = await read({ offset: 5, limit: 9 });
+                assert.strictEqual(middle.data, '0\nline 1\n');
+                assert.strictEqual(middle.offset, 5n);
+                assert.strictEqual(middle.size, 9n);
+                assert.strictEqual(middle.complete, false);
+                // From byte 14 to its end: an offset alone
+                const tail = await read({ offset: 14 });
+                assert.strictEqual(tail.data, 'line 2\n');
+                assert.strictEqual(tail.offset, 14n);
+                assert.strictEqual(tail.size, 7n);
+                assert.strictEqual(tail.complete, true);
+                // A window of no bytes is a window: it reports the log's size, which
+                // is how e3's CLI learns it
+                const probe = await read({ offset: 0, limit: 0 });
+                assert.strictEqual(probe.data, '');
+                assert.strictEqual(probe.size, 0n);
+                assert.strictEqual(probe.totalSize, total);
+            });
+            it('refuses a malformed window or stream with bad_request, before it reads a log', async (t) => {
+                const ctx = await withLogPag(t);
+                const opts = await ctx.opts();
+                assertDataflowSucceeded(await dataflowExecute(ctx.config.baseUrl, ctx.repoName, 'logpag-ws', { force: true }, opts));
+                // Through the client, which sends a number as it prints
+                const windows = [
+                    [{ offset: NaN }, 'offset must be a non-negative integer, got "NaN"'],
+                    [{ offset: -1 }, 'offset must be a non-negative integer, got "-1"'],
+                    [{ offset: 1.5 }, 'offset must be a non-negative integer, got "1.5"'],
+                    [{ limit: NaN }, 'limit must be a non-negative integer, got "NaN"'],
+                    [{ limit: -1 }, 'limit must be a non-negative integer, got "-1"'],
+                ];
+                for (const [window, message] of windows) {
+                    await rejectsBadRequest(taskLogs(ctx.config.baseUrl, ctx.repoName, 'logpag-ws', 'log', { stream: 'stdout', ...window }, opts), message);
+                }
+                // As a request spells them: a word; a number past those a number holds
+                // exactly; a stream other than the two a log has, a way out of the
+                // execution among them; and a window for a task there is no log of,
+                // refused before the server looks for one
+                const logs = `${ctx.config.baseUrl}/api/repos/${encodeURIComponent(ctx.repoName)}/workspaces/logpag-ws/dataflow/logs`;
+                const headers = opts.token ? { 'Authorization': `Bearer ${opts.token}` } : {};
+                const requests = [
+                    ['log?offset=abc', 'offset must be a non-negative integer, got "abc"'],
+                    ['log?limit=abc', 'limit must be a non-negative integer, got "abc"'],
+                    ['log?offset=99999999999999999999', 'offset must be at most 9007199254740991, got "99999999999999999999"'],
+                    ['log?stream=stdin', 'stream must be stdout or stderr, got "stdin"'],
+                    [`log?stream=${encodeURIComponent('../../stdout')}`, 'stream must be stdout or stderr, got "../../stdout"'],
+                    ['no_such_task?offset=-1', 'offset must be a non-negative integer, got "-1"'],
+                    [`log?inputs=${'a'.repeat(64)}`, 'inputs and execution name an execution together: give both, or neither'],
+                    ['log?execution=0190a0b0-4444-7000-8000-000000000000', 'inputs and execution name an execution together: give both, or neither'],
+                ];
+                for (const [request, message] of requests) {
+                    const response = await ctx.fetch(`${logs}/${request}`, { headers });
+                    assert.strictEqual(response.status, 400, request);
+                    assert.deepStrictEqual(await response.json(), { error: { type: 'bad_request', message } }, request);
                 }
-                // Get first 5 bytes
-                const chunk1 = await taskLogs(ctx.config.baseUrl, ctx.repoName, 'logpag-ws', 'compute', { stream: 'stdout', offset: 0, limit: 5 }, opts);
-                assert.strictEqual(chunk1.data, full.data.slice(0, 5));
-                assert.strictEqual(chunk1.offset, 0n);
-                // Get from byte 5 onwards
-                const chunk2 = await taskLogs(ctx.config.baseUrl, ctx.repoName, 'logpag-ws', 'compute', { stream: 'stdout', offset: 5 }, opts);
-                assert.strictEqual(chunk2.offset, 5n);
-                assert.strictEqual(chunk2.data, full.data.slice(5));
             });
         });
         describe('event pagination', { concurrency: false }, () => {
-            it('dataflowExecutePoll supports event offset and limit', async (t) => {
+            it('dataflowExecutePoll serves the events past its cursor, at most its limit, and the cursor past them', async (t) => {
                 const ctx = await withEvtPag(t);
                 const opts = await ctx.opts();
+                const poll = (stateOptions) => dataflowExecutePoll(ctx.config.baseUrl, ctx.repoName, 'evtpag-ws', stateOptions, opts);
                 // Execute and wait for completion
                 await dataflowExecute(ctx.config.baseUrl, ctx.repoName, 'evtpag-ws', { force: true }, opts);
-                // Get first event only
-                const page1 = await dataflowExecutePoll(ctx.config.baseUrl, ctx.repoName, 'evtpag-ws', { offset: 0, limit: 1 }, opts);
-                assert.strictEqual(page1.events.length, 1, 'Should return exactly 1 event');
-                assert.ok(page1.totalEvents >= 3n, `Expected at least 3 total events, got ${page1.totalEvents}`);
-                // Get second event
-                const page2 = await dataflowExecutePoll(ctx.config.baseUrl, ctx.repoName, 'evtpag-ws', { offset: 1, limit: 1 }, opts);
-                assert.strictEqual(page2.events.length, 1, 'Should return exactly 1 event');
-                // Events should be different
-                const event1 = page1.events[0];
-                const event2 = page2.events[0];
-                const event1Key = `${event1.type}:${'value' in event1 ? event1.value.task : ''}`;
-                const event2Key = `${event2.type}:${'value' in event2 ? event2.value.task : ''}`;
-                assert.notStrictEqual(event1Key, event2Key, 'Paginated events should be different');
+                const before = lessFor(IntegerType);
+                // Every event, and the cursor past the last
+                const all = await poll({});
+                assert.ok(all.events.length >= 3, `Expected at least 3 events, got ${all.events.length}`);
+                assert.ok(before(0n, all.nextSeq), 'the cursor moved past the events');
+                // A page of one, and the next from its cursor: the events in order
+                const page1 = await poll({ limit: 1 });
+                const page2 = await poll({ since: page1.nextSeq, limit: 1 });
+                assert.deepStrictEqual([...page1.events, ...page2.events], all.events.slice(0, 2), 'the first two events, in order');
+                assert.ok(before(page1.nextSeq, page2.nextSeq), 'each cursor past the events served');
+                // A poll that has every event is served none, and its cursor stays
+                const caughtUp = await poll({ since: all.nextSeq });
+                assert.deepStrictEqual([caughtUp.events, caughtUp.nextSeq], [[], all.nextSeq]);
+                assert.strictEqual(caughtUp.status.type, 'completed', 'with the run\'s state');
+                // Where the run's events end: a poll of every event reaches its last,
+                // and a page of one leaves events for the next
+                assert.strictEqual(all.lastSeq, all.nextSeq, 'a poll of every event is at the run\'s last');
+                assert.deepStrictEqual([dataflowEventsRemain(all), dataflowEventsRemain(page1), dataflowEventsRemain(caughtUp)], [false, true, false]);
+                // Each poll names the run, and another run is another id
+                assert.deepStrictEqual([page1.runId, page2.runId, caughtUp.runId], [all.runId, all.runId, all.runId]);
+                assertDataflowSucceeded(await dataflowExecute(ctx.config.baseUrl, ctx.repoName, 'evtpag-ws', { force: true }, opts));
+                assert.notStrictEqual((await poll({ limit: 0 })).runId, all.runId, 'the next run is another');
+            });
+            it('refuses a malformed cursor or limit with bad_request; a poll of no events carries the run\'s state', async (t) => {
+                const ctx = await withEvtPag(t);
+                const opts = await ctx.opts();
+                assertDataflowSucceeded(await dataflowExecute(ctx.config.baseUrl, ctx.repoName, 'evtpag-ws', { force: true }, opts));
+                // Through the client, which sends a limit as it prints
+                const windows = [
+                    [{ limit: NaN }, 'limit must be a non-negative integer, got "NaN"'],
+                    [{ limit: -1 }, 'limit must be a non-negative integer, got "-1"'],
+                    [{ limit: 1.5 }, 'limit must be a non-negative integer, got "1.5"'],
+                    [{ since: -1n }, 'since must be a non-negative integer, got "-1"'],
+                ];
+                for (const [window, message] of windows) {
+                    await rejectsBadRequest(dataflowExecutePoll(ctx.config.baseUrl, ctx.repoName, 'evtpag-ws', window, opts), message);
+                }
+                // As a request spells them: a word, and a number past those a number
+                // holds exactly
+                const execution = `${ctx.config.baseUrl}/api/repos/${encodeURIComponent(ctx.repoName)}/workspaces/evtpag-ws/dataflow/execution`;
+                const headers = opts.token ? { 'Authorization': `Bearer ${opts.token}` } : {};
+                const requests = [
+                    ['since=abc', 'since must be a non-negative integer, got "abc"'],
+                    ['since=1.5', 'since must be a non-negative integer, got "1.5"'],
+                    ['since=99999999999999999999', 'since must be at most 9007199254740991, got "99999999999999999999"'],
+                ];
+                for (const [query, message] of requests) {
+                    const response = await ctx.fetch(`${execution}?${query}`, { headers });
+                    assert.strictEqual(response.status, 400, query);
+                    assert.deepStrictEqual(await response.json(), { error: { type: 'bad_request', message } }, query);
+                }
+                const none = await dataflowExecutePoll(ctx.config.baseUrl, ctx.repoName, 'evtpag-ws', { limit: 0 }, opts);
+                assert.strictEqual(none.status.type, 'completed');
+                assert.deepStrictEqual([none.events, none.nextSeq], [[], 0n], 'no events, and the cursor where it was');
+                assert.ok(dataflowEventsRemain(none), 'and where the run\'s events end, past the cursor');
             });
         });
     });