@elaraai/e3-api-server 1.0.84 → 1.0.86

package/README.md

@@ -160,8 +160,15 @@ of the run in the request's host, and a poll and a cancel read the latest run
 from that store, whichever instance answers them. The dataset transfer routes
 (`createTransferRoutes`) take the transfer backend, whose upload store takes a
 delivery in on the runner it was given: an init adopts only what takes nothing
-in, and answers at once. A route answers for the repository in its URL alone:
-a job, an upload or a run another repository started is not found through it.
+in, and answers at once. A poll reads the latest run's summary from the store
+(`readLatestSummary`), and its events only past the poll's cursor, a page of
+its limit at a time, from the run's events, which the store keeps apart from
+its state, so a store whose reads cost by the byte answers a caught-up poll
+cheaply, and any poll by what it serves; the waits and
+split progress it serves are the orchestrator's (`getProgress`), which has none
+of a run another instance runs. A route answers for the repository in its URL
+alone: a job, an upload or a run another repository started is not found
+through it.
 
 ```typescript
 import { Hono } from 'hono';
@@ -182,18 +189,77 @@ leaves the steps to a job of its own. Given `applyUpgrades: false`, the gate
 applies none: it answers every request to a repository that owes them `503`
 `repository_upgrade_pending` — but a running dataflow's cancel and poll — until
 the steps are applied, and calls `onUpgradePending` for each, where the host
-starts its job, once. The job opens the repository with e3-core's
-`repositoryOpen`, which applies them, waiting for work running in it as any
-open does.
+starts its job, once. The job applies them with e3-core's
+`repositoryUpgradeStep`, a part at a time, each running for the budget it is
+given, until none is owed. A part takes the step up where the last one stopped,
+whichever process ran it, and waits for work running in the repository as an
+open does. No route applies a step itself: the record route (`getRecord`) only
+reads, and refuses a repository that owes one as the gate does, gate or no.
 
 ```typescript
 app.use('/api/repos/:repo/*', createRepositoryGate(storage, getRepoPath, {
   applyUpgrades: false,
-  // The job runs repositoryOpen(storage, getRepoPath(repo))
+  // Each run of the job applies a part, under its time limit, and the job
+  // runs again while any step is owed:
+  // repositoryUpgradeStep(storage, getRepoPath(repo), { budgetMs: 10 * 60_000 })
   onUpgradePending: (repo) => startUpgradeJob(repo),
 }));
 ```
 
+A host's own routes answer their errors as these do, with the mapping every
+route uses, so no host keeps a copy of it that falls behind as it grows:
+
+- `errorToVariant` gives an e3-core error as the API's `ErrorType`, which
+  `sendError` answers in BEAST2;
+- `errorToHttpStatus` and `sendJsonError` answer it as JSON, as the gate
+  answers its refusals;
+- `sendUpgradePending` answers a repository that owes upgrades as the gate
+  does.
+
+A host's own routes over records answer as the record and dataset routes do:
+
+- `mutationResultOf` gives the outcome of a record operation as the
+  `MutationResultType` value the mutation and compact routes answer with,
+  such as a rollback's through e3-core's `recordSystemCommit`;
+- `getValuePage` answers a window of a collection the host names by hash,
+  such as a record's state at a past commit, with the body, the `X-*` headers
+  and the refusals of a dataset's page (`getDatasetPage`).
+
+Each is exported from the root and the portable entries, and each handler from
+`./handlers` too. e3-api-client reads what they answer: `parsePage` a page,
+`parseErrorBody` a JSON refusal, and `objectGet` and `collectionGetStream` a
+value by its hash.
+
+A host whose requests have a time limit gives it to the routes that run a
+program for a request, so that each answers its typed outcome before the host
+cuts it off: the function and one-shot routes take `syncDeadlineMs`, and so do
+the record routes, whose mutation and compaction answer `timed_out` or
+`conflict` 2 s under it. The record routes' `historyLimit` is how many commits
+a history request that names no `limit` is answered with; the client pages on
+from the last one's parent. Unset, as on this server, neither is bounded. A
+limit no request could meet is refused when the routes are mounted.
+
+```typescript
+app.route('/api/repos/:repo/workspaces/:ws/records', createWorkspaceRecordRoutes(storage, getRepoPath, getRunner, {
+  syncDeadlineMs: 29_000,  // under a 30 s gateway
+  historyLimit: 1_000,
+}));
+```
+
+A dataset page or key search pinned to the value's hash (`hash=`) never
+changes, so it is answered `Cache-Control: private, max-age=31536000,
+immutable`: the caller's own cache keeps it for good, and no cache between
+keeps a workspace's rows for whoever asks next. A host whose data any caller may
+read lets those caches keep it too, a CDN's among them, with the dataset
+routes' `cache: 'public'`; `getDatasetPage`, `getValuePage` and
+`findDatasetKey` take the same. An answer not pinned is `no-store`.
+
+```typescript
+app.route('/api/repos/:repo/workspaces/:ws/datasets', createDatasetRoutes(storage, getRepoPath, transferBackend, {
+  cache: 'public',  // every caller may read every workspace this host serves
+}));
+```
+
 ## API Endpoints
 
 All endpoints are prefixed with `/api/repos/:repo` where `:repo` is:
@@ -208,6 +274,7 @@ All endpoints are prefixed with `/api/repos/:repo` where `:repo` is:
 | PUT | `/api/repos/:repo` | Create repository (multi-repo mode) |
 | DELETE | `/api/repos/:repo` | Remove repository (multi-repo mode): marked as being removed first, so a request to it is refused from then on |
 | GET | `/api/repos/:repo/status` | Repository status (counts) |
+| GET | `/api/repos/:repo/record` | The repository's record: the release that last wrote it, and the upgrades it has had. A read, which applies none it owes: without the gate ahead of it, a repository that owes one is refused as the gate refuses it, 503 `repository_upgrade_pending` with `Retry-After` |
 | POST | `/api/repos/:repo/gc` | Start garbage collection (async) |
 | GET | `/api/repos/:repo/gc/:id` | Get GC status |
 
@@ -231,7 +298,7 @@ All endpoints are prefixed with `/api/repos/:repo` where `:repo` is:
 | GET | `/api/repos/:repo/workspaces` | List all workspaces |
 | POST | `/api/repos/:repo/workspaces` | Create workspace |
 | GET | `/api/repos/:repo/workspaces/:ws` | Get workspace info |
-| GET | `/api/repos/:repo/workspaces/:ws/status` | Get workspace status (datasets, tasks, summary) |
+| GET | `/api/repos/:repo/workspaces/:ws/status` | Get workspace status (datasets, tasks, summary). With `?path=` (repeated, each a dataset's keypath, `.inputs.x`), only those datasets and the tasks producing them, each as the whole status gives it: a path that names no dataset is left out, and one that is no keypath is refused 400 `bad_request` |
 | POST | `/api/repos/:repo/workspaces/:ws/deploy` | Start deploying a package to the workspace, as a job: answers the job's id |
 | GET | `/api/repos/:repo/workspaces/:ws/deploy/:id` | Poll a deploy job: `processing` with how far it has got, what the deploy did for each record and index, or why it failed |
 | GET | `/api/repos/:repo/workspaces/:ws/lock` | What holds the workspace exclusively, and how far it says it has got; none when nothing does |
@@ -271,7 +338,7 @@ through the objects route and splices them itself, as e3-api-client's
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
-| GET | `/api/repos/:repo/objects/:hash` | An object's bytes; one over 1 MB answers JSON `{ url }` to download it from |
+| GET | `/api/repos/:repo/objects/:hash` | An object's bytes; one over 1 MB answers JSON `{ url }` to download it from; a hash that is no SHA-256 in lowercase hex is refused 400 `invalid_name` |
 | GET | `/api/downloads/:id` | A download a `{ url }` answer names (no `Authorization`) |
 
 ### Dataset transfer
@@ -316,10 +383,10 @@ and its commit takes it in.
 |--------|----------|-------------|
 | GET | `/api/repos/:repo/packages/:pkg/:version/functions` | A package's functions and their signatures |
 | GET | `/api/repos/:repo/packages/:pkg/:version/functions/:fn` | One function's signature |
-| POST | `/api/repos/:repo/packages/:pkg/:version/functions/:fn` | Call a package's function: its result, inline |
+| POST | `/api/repos/:repo/packages/:pkg/:version/functions/:fn` | Call a package's function with values: its result, inline. A dataset argument is `invalid` here, with no workspace to read it from |
 | GET | `/api/repos/:repo/workspaces/:ws/functions` | The deployed package's functions |
 | GET | `/api/repos/:repo/workspaces/:ws/functions/:fn` | One function's signature |
-| POST | `/api/repos/:repo/workspaces/:ws/functions/:fn` | Call one of them |
+| POST | `/api/repos/:repo/workspaces/:ws/functions/:fn` | Call one of them: each argument a value, or one of the workspace's datasets, pinned at its hash when the call starts; the result names the datasets it read (`inputs`) |
 | POST | `/api/repos/:repo/workspaces/:ws/one-shot` | Run a caller's program over the workspace's datasets: its result, naming the datasets it read (`inputs`) |
 | POST | `/api/repos/:repo/workspaces/:ws/one-shot/split` | Launch a split call — a caller's program over a dataset's pieces — as a job: answers the job's id; with `?explain=1` the job plans the pieces the call would run, and runs nothing |
 | GET | `/api/repos/:repo/workspaces/:ws/one-shot/split/:id` | Poll a split call: how far it has got, its result, the pieces an explain planned, or why it failed |
@@ -345,13 +412,22 @@ for the whole job, counted from its launch. A call is polled only through the
 repository and workspace that launched it, and a caller with a platform-free
 grant polls only a platform-free call, or one such a caller launched.
 
+### Records
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/repos/:repo/workspaces/:ws/records/:rec` | The record's mutations, indexes and migrations, with their types: whether each index is built for the head's state, and when each migration was applied and by which commit, read from the record's ref and state, never its history |
+| GET | `/api/repos/:repo/workspaces/:ws/records/:rec/history` | Its commits, newest first: `?limit=` of them from `?from=`, the head when absent; with no limit, the whole chain, or the host's page (`historyLimit`). Each previews its arguments: the arguments' object, and each argument's type, size and East text, cut at 256 characters, the text of one over 64 KiB left out, and no argument of an object over 1 MiB, which the objects route serves whole |
+| POST | `/api/repos/:repo/workspaces/:ws/records/:rec/mutations/:mut` | Apply a mutation: `committed`, `invalid`, `failed`, `timed_out` or `conflict`; with an `Idempotency-Key`, a retry answers the first call's commit |
+| POST | `/api/repos/:repo/workspaces/:ws/records/:rec/compact` | Collapse the history to a `$compact` root, the state kept (an elevated role when auth is on) |
+
 ### Execution
 
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | POST | `/api/repos/:repo/workspaces/:ws/dataflow` | Start a run of the dataflow (answers 202 once it has started) |
 | GET | `/api/repos/:repo/workspaces/:ws/dataflow` | Get workspace status (for polling) |
-| GET | `/api/repos/:repo/workspaces/:ws/dataflow/execution` | The latest run's state and a window of its events (`offset`, `limit`), with the server's budget in use; while the run is in flight, the tasks and units waiting for room and each split task's progress, as the orchestrator running it answers them |
+| GET | `/api/repos/:repo/workspaces/:ws/dataflow/execution` | The latest run's state, its id (`runId`) and the sequence number of its last event (`lastSeq`), and its events past the poll's cursor (`since`, the `nextSeq` the poll before answered; at most `limit` of them, and never more than 1,000, the default: a `nextSeq` before `lastSeq` left some for the next poll), with the server's budget in use; while the run is in flight, the tasks and units waiting for room and each split task's progress, as the orchestrator running it answers them |
 | GET | `/api/repos/:repo/workspaces/:ws/dataflow/budget` | The budget a run gets: the server's cores and memory, and what its runners hold now (`none` from a host whose runners hold none) |
 | POST | `/api/repos/:repo/workspaces/:ws/dataflow/cancel` | Cancel the run in progress |
 | GET | `/api/repos/:repo/workspaces/:ws/dataflow/graph` | Get dependency graph |
@@ -366,6 +442,7 @@ Response bodies are wrapped in a variant type:
 - `{ type: 'error', value: <error> }` - Operation failed
 
 Error variants include:
+- `invalid_name` - A name, hash or id is not of its form: its kind (a workspace's name, an object's hash, a run's id, …), the value, and why, whichever backend the server runs over
 - `workspace_not_found` - Workspace doesn't exist
 - `workspace_not_deployed` - No package deployed to workspace
 - `workspace_locked` - Workspace is locked by another process

package/dist/src/errors.d.ts

@@ -2,6 +2,7 @@
  * Copyright (c) 2025 Elara AI Pty Ltd
  * Licensed under BSL 1.1. See LICENSE for details.
  */
+import { RepositoryUpgradePendingError } from '@elaraai/e3-core/portable';
 import type { Error } from './types.js';
 /**
  * Map an e3-core error to an HTTP status code.
@@ -14,6 +15,20 @@ export declare function errorToHttpStatus(err: unknown): number;
  * on success, so errors need a different content type and status code.
  */
 export declare function sendJsonError(err: unknown): Response;
+/**
+ * The answer to a request of a repository that owes store upgrades: 503 JSON
+ * `repository_upgrade_pending`, naming the steps and why they wait, with a
+ * `Retry-After`.
+ *
+ * @remarks
+ * The repository gate answers so, and so does a route that opens the
+ * repository itself, whatever its success's type: a client retries the
+ * request, and then raises `repository_upgrade_pending`.
+ *
+ * @param err - The open's refusal
+ * @returns The response
+ */
+export declare function sendUpgradePending(err: RepositoryUpgradePendingError): Response;
 /**
  * Convert an e3-core error to an API error variant.
  */

package/dist/src/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAuBH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAsBtD;AA2BD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,CAQpD;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,KAAK,CA+ElD"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAEL,6BAA6B,EAiB9B,MAAM,2BAA2B,CAAC;AACnC,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAExC;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAsBtD;AA2BD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,QAAQ,CAQpD;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,6BAA6B,GAAG,QAAQ,CAI/E;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,OAAO,GAAG,KAAK,CA+ElD"}

package/dist/src/errors.js

@@ -3,7 +3,7 @@
  * Licensed under BSL 1.1. See LICENSE for details.
  */
 import { variant, some, none } from '@elaraai/east';
-import { RepoNotFoundError, RepositoryUpgradePendingError, InvalidNameError, WorkspaceNotFoundError, WorkspaceNotDeployedError, WorkspaceExistsError, WorkspaceLockError, PackageNotFoundError, PackageExistsError, PackageInvalidError, DatasetNotFoundError, DatasetTypeMismatchError, TaskNotFoundError, ExecutionNotFoundError, ObjectNotFoundError, DataflowError, DataflowAbortedError, PermissionDeniedError, } from '@elaraai/e3-core';
+import { RepoNotFoundError, RepositoryUpgradePendingError, InvalidNameError, WorkspaceNotFoundError, WorkspaceNotDeployedError, WorkspaceExistsError, WorkspaceLockError, PackageNotFoundError, PackageExistsError, PackageInvalidError, DatasetNotFoundError, DatasetTypeMismatchError, TaskNotFoundError, ExecutionNotFoundError, ObjectNotFoundError, DataflowError, DataflowAbortedError, PermissionDeniedError, } from '@elaraai/e3-core/portable';
 /**
  * Map an e3-core error to an HTTP status code.
  */
@@ -105,6 +105,27 @@ export function sendJsonError(err) {
         headers: { 'Content-Type': 'application/json' },
     });
 }
+/** How long, in seconds, a client is told to wait before it asks again of a
+ *  repository an upgrade waits on. */
+const UPGRADE_RETRY_AFTER_S = 5;
+/**
+ * The answer to a request of a repository that owes store upgrades: 503 JSON
+ * `repository_upgrade_pending`, naming the steps and why they wait, with a
+ * `Retry-After`.
+ *
+ * @remarks
+ * The repository gate answers so, and so does a route that opens the
+ * repository itself, whatever its success's type: a client retries the
+ * request, and then raises `repository_upgrade_pending`.
+ *
+ * @param err - The open's refusal
+ * @returns The response
+ */
+export function sendUpgradePending(err) {
+    const refused = sendJsonError(err);
+    refused.headers.set('Retry-After', String(UPGRADE_RETRY_AFTER_S));
+    return refused;
+}
 /**
  * Convert an e3-core error to an API error variant.
  */

package/dist/src/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/errors.ts"],"names":[],"mappings":"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"}

package/dist/src/handlers/dataflow.d.ts

@@ -2,7 +2,27 @@
  * Copyright (c) 2025 Elara AI Pty Ltd
  * Licensed under BSL 1.1. See LICENSE for details.
  */
-import type { Budget, DataflowOrchestrator, ExecutionStateStore, StorageBackend, TaskRunner } from '@elaraai/e3-core';
+import type { DataflowOrchestrator, ExecutionStateStore, StorageBackend, TaskRunner } from '@elaraai/e3-core/portable';
+/**
+ * The budget a host's runners take from, as the dataflow routes serve it: its
+ * capacity, and what the runners hold of it now.
+ *
+ * @remarks
+ * e3-core's `Budget`, which a local server's runners hold, is one. The routes
+ * read no more of it than this, so they take it from a host whose budget is
+ * its own.
+ */
+export interface RunnerBudget {
+    /** Runner processes at once. */
+    readonly cores: number;
+    /** Bytes of memory the runners may reserve between them. */
+    readonly memory: number;
+    /** Runner processes holding the budget now. */
+    readonly inFlight: number;
+    /** Bytes the runners hold now, each at the larger of its reservation and
+     *  what it was last measured using. */
+    readonly used: number;
+}
 /**
  * Start dataflow execution (non-blocking).
  *
@@ -13,20 +33,27 @@ import type { Budget, DataflowOrchestrator, ExecutionStateStore, StorageBackend,
  * where it starts the run — a local one in its own process — so this never
  * waits on it.
  *
+ * The workspace's name is checked before the orchestrator is asked, so a name
+ * no workspace can have is refused alike whichever orchestrator runs the
+ * repository's dataflows, and no lock named for it is taken.
+ *
  * @param storage - Storage backend
  * @param orchestrator - The orchestrator that runs the repository's dataflows
  * @param repoPath - The repository's path
  * @param workspace - The workspace whose dataflow runs
  * @param options - The runner the run's tasks and units run on, which holds
  *   the server's budget; the tasks and units the loop keeps in flight, the
- *   orchestrator's own default when absent; and the run's force, filter and
- *   verbosity
- * @returns 202 once the run has started, or the error that stopped it
+ *   orchestrator's own default when absent; what the run forces — `true` for
+ *   every task, or the tasks' names — its filter and its verbosity
+ * @returns 202 once the run has started, or the error that stopped it: a name
+ *   no workspace can have is `invalid_name`, a forced task the graph does not
+ *   have `task_not_found`, and one the filter's run set leaves out
+ *   `dataflow_error`
  */
 export declare function startDataflow(storage: StorageBackend, orchestrator: DataflowOrchestrator, repoPath: string, workspace: string, options: {
     runner: TaskRunner;
     width?: number;
-    force: boolean;
+    force: boolean | readonly string[];
     filter?: string;
     verbose?: boolean;
 }): Promise<Response>;
@@ -46,31 +73,73 @@ export declare function getDataflowStatus(storage: StorageBackend, runner: TaskR
  */
 export declare function getDataflowGraph(storage: StorageBackend, repoPath: string, workspace: string): Promise<Response>;
 /**
- * Get task logs.
+ * Get a chunk of a task's log: of its current execution — the latest over its
+ * current inputs, or its latest run ({@link executionFindCurrent}) — or of the
+ * execution the request names. The chunk names the execution it was read from
+ * and whether it has ended, so a client polling the log reads on from its
+ * offset, starts over when the execution changes, and stops reading once it
+ * has ended and its log is read. A poll costs the same however long the task
+ * has run.
+ *
+ * @param storage - Storage backend
+ * @param repoPath - The repository's path
+ * @param workspace - The workspace
+ * @param taskName - The task
+ * @param stream - The log stream
+ * @param offset - The byte the chunk starts at
+ * @param limit - The most bytes it holds
+ * @param execution - The execution to read, by its inputs hash and id; the
+ *   task's current execution when absent
+ * @returns The chunk, or `execution_not_found` when the task records none
  */
-export declare function getTaskLogs(storage: StorageBackend, repoPath: string, workspace: string, taskName: string, stream: 'stdout' | 'stderr', offset: number, limit: number): Promise<Response>;
+export declare function getTaskLogs(storage: StorageBackend, repoPath: string, workspace: string, taskName: string, stream: 'stdout' | 'stderr', offset: number, limit: number, execution?: {
+    inputsHash: string;
+    executionId: string;
+}): Promise<Response>;
 /**
  * Get dataflow execution state (for polling).
  *
  * Returns the state of the workspace's latest run, as the state store keeps
- * it, including events for progress tracking: the run in flight, whichever
- * process runs it, or the last to end. Supports offset/limit for paginating
- * events. While the run is in flight, it carries the tasks and units waiting
- * for room and each split task's progress, which the orchestrator running it
- * keeps in memory; and it carries the server's budget when it has one.
+ * it, and its events past the poll's cursor: the run in flight, whichever
+ * process runs it, or the last to end. While the run is in flight, it carries
+ * the tasks and units waiting for room and each split task's progress, which
+ * the orchestrator running it keeps in memory; and it carries the server's
+ * budget when it has one.
+ *
+ * @remarks
+ * The poll reads the run's summary, not its whole state, and reads its events
+ * only when the summary's last is past the cursor, so a poll that has every
+ * event, or asks for none (`limit` 0), reads none. It reads them from the
+ * run's events, which the store keeps apart from its state, a page of `limit`
+ * at a time until it has served `limit`, and at most eight pages, so a poll
+ * costs what it serves and the events between. The cursor is the stored
+ * sequence number of the last event the client has (`since`, 0 for none). The
+ * response's `nextSeq` is the cursor past what the poll went through: the API
+ * events it served and the events the API does not show between them, or
+ * `since` when it went through none. The waits and the split tasks' progress
+ * come from the orchestrator's memory, which holds none of a run another
+ * process or instance runs.
+ *
+ * A poll is served at most `limit` events, and never more than
+ * {@link DATAFLOW_POLL_EVENTS_MAX}, which is its limit when it names none, so
+ * an answer stays within what a host's response may hold however long the
+ * run. The response names the run (`runId`) and the sequence number of its
+ * last event (`lastSeq`) as its summary read them, and goes through no event
+ * past that one: a poll whose `nextSeq` is before `lastSeq` left events for
+ * the next.
  *
  * @param stateStore - The store the repository's runs keep their state in
  * @param orchestrator - The orchestrator that runs the repository's dataflows
  * @param repoPath - The repository's path
  * @param workspace - The workspace
- * @param options - The window of events to serve
+ * @param options - The poll's cursor, and the most events it is served
  * @param budget - The server's budget, which its runners hold, if any
  * @returns The execution state, or `execution_not_found`
  */
 export declare function getDataflowExecution(stateStore: ExecutionStateStore, orchestrator: DataflowOrchestrator, repoPath: string, workspace: string, options?: {
-    offset?: number;
+    since?: number;
     limit?: number;
-}, budget?: Budget): Promise<Response>;
+}, budget?: RunnerBudget): Promise<Response>;
 /**
  * The budget a run of the dataflow gets: the server's, which it shares with
  * everything else the server runs.
@@ -79,16 +148,18 @@ export declare function getDataflowExecution(stateStore: ExecutionStateStore, or
  * @returns The budget with what its runners hold now, or `none` for a server
  *   whose runners hold none
  */
-export declare function getDataflowBudget(budget: Budget | undefined): Response;
+export declare function getDataflowBudget(budget: RunnerBudget | undefined): Response;
 /**
  * Cancel a running dataflow execution: the workspace's latest run, when its
- * state says it is running.
+ * summary says it is running.
  *
  * @param stateStore - The store the repository's runs keep their state in
  * @param orchestrator - The orchestrator that runs the repository's dataflows
  * @param repoPath - The repository's path
  * @param workspace - The workspace
- * @returns The response: null once the run is cancelled, or why it is not
+ * @returns The response: null once the run is cancelled; `dataflow_error`
+ *   when no run is running, the request meeting the workspace's state rather
+ *   than a fault of the server's; or why else it is not
  */
 export declare function cancelDataflow(stateStore: ExecutionStateStore, orchestrator: DataflowOrchestrator, repoPath: string, workspace: string): Promise<Response>;
 //# sourceMappingURL=dataflow.d.ts.map

package/dist/src/handlers/dataflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dataflow.d.ts","sourceRoot":"","sources":["../../../src/handlers/dataflow.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAkBH,OAAO,KAAK,EAAE,MAAM,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AA8ItH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,cAAc,EACvB,YAAY,EAAE,oBAAoB,EAClC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GAClG,OAAO,CAAC,QAAQ,CAAC,CAkBnB;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,UAAU,EAClB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,QAAQ,CAAC,CAOnB;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,QAAQ,CAAC,CAenB;AAED;;GAEG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,QAAQ,GAAG,QAAQ,EAC3B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,QAAQ,CAAC,CAqBnB;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,mBAAmB,EAC/B,YAAY,EAAE,oBAAoB,EAClC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,EACjD,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,QAAQ,CAAC,CA6JnB;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,CAEtE;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,UAAU,EAAE,mBAAmB,EAC/B,YAAY,EAAE,oBAAoB,EAClC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,QAAQ,CAAC,CAenB"}
+{"version":3,"file":"dataflow.d.ts","sourceRoot":"","sources":["../../../src/handlers/dataflow.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAwBH,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AA8FvH;;;;;;;;GAQG;AACH,MAAM,WAAW,YAAY;IAC3B,gCAAgC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+CAA+C;IAC/C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;2CACuC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAmDD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,cAAc,EACvB,YAAY,EAAE,oBAAoB,EAClC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,OAAO,GAAG,SAAS,MAAM,EAAE,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,GACtH,OAAO,CAAC,QAAQ,CAAC,CAsBnB;AAED;;;;;;;;;GASG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,cAAc,EACvB,MAAM,EAAE,UAAU,EAClB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,QAAQ,CAAC,CAOnB;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,QAAQ,CAAC,CAenB;AAkBD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,WAAW,CAC/B,OAAO,EAAE,cAAc,EACvB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,QAAQ,GAAG,QAAQ,EAC3B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,MAAM,EACb,SAAS,CAAC,EAAE;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GACtD,OAAO,CAAC,QAAQ,CAAC,CAwBnB;AA4DD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,wBAAsB,oBAAoB,CACxC,UAAU,EAAE,mBAAmB,EAC/B,YAAY,EAAE,oBAAoB,EAClC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAO,EAChD,MAAM,CAAC,EAAE,YAAY,GACpB,OAAO,CAAC,QAAQ,CAAC,CA4GnB;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,YAAY,GAAG,SAAS,GAAG,QAAQ,CAE5E;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAClC,UAAU,EAAE,mBAAmB,EAC/B,YAAY,EAAE,oBAAoB,EAClC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,QAAQ,CAAC,CAenB"}