@elaraai/east-codex-plugin 1.0.103 → 1.0.105

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@elaraai/east-codex-plugin",
3
- "version": "1.0.103",
3
+ "version": "1.0.105",
4
4
  "description": "East programming language ecosystem - a statically typed, expression-based language for business logic, data processing, UI definitions, and durable execution",
5
5
  "license": "AGPL-3.0-or-later",
6
6
  "type": "module",
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: e3
3
- description: "East Execution Engine (e3): durable, content-addressed dataflow for East programs. Use when (1) authoring a package with @elaraai/e3 — e3.input, e3.task, e3.streamTask with e3.output and e3.partition (bounded memory, work split over an input), e3.customTask, e3.function, e3.package, e3.export, East.importFunction; (2) records — audited state written only through mutations (e3.record with mutation.reduce/edit/patch), their indexes (index.on/key/keys, interval, area, series, summary, nested) and migrations (migration.value/rows/rekey); (3) the e3 CLI — repo, package, workspace, dataset, task, dataflow run, run, call, mutate, seed, history, watch, convert, auth, and the cores and memory a run may use; (4) driving e3 from code (@elaraai/e3-api-client, @elaraai/e3-core, e3-api-server); (5) caching, reactive re-runs and garbage collection; (6) delegating task bodies to a rack (e3 rack); (7) e3 in a browser with @elaraai/e3-web. UI tasks are e3-ui's ui()."
3
+ description: "East Execution Engine (e3): durable, content-addressed dataflow for East programs. Use when (1) authoring a package with @elaraai/e3 — e3.input, e3.task, e3.streamTask with e3.output and e3.partition (bounded memory, work split over an input), e3.customTask, e3.function, e3.package, e3.export, East.importFunction; (2) records — audited state written only through mutations (e3.record with mutation.reduce/edit/patch), their indexes (index.on/key/keys, interval, area, series, summary, nested, entries) and migrations (migration.value/rows/rekey); (3) the e3 CLI — repo, package, workspace, dataset, task, dataflow run, run, call, mutate, seed, history, watch, convert, auth, and the cores and memory a run may use; (4) driving e3 from code (@elaraai/e3-api-client, @elaraai/e3-core, e3-api-server); (5) caching, reactive re-runs and garbage collection; (6) delegating task bodies to a rack (e3 rack); (7) e3 in a browser with @elaraai/e3-web. UI tasks are e3-ui's ui()."
4
4
  ---
5
5
 
6
6
  # East Execution Engine (e3)
@@ -69,14 +69,16 @@ What do you need?
69
69
  │ │ ├─ Too large, or built as you go → e3.streamTask(name, { inputs, output }, fn) — emits into e3.output.array | set | dict | fold
70
70
  │ │ └─ Split over an input, in pieces → wrap that input: e3.partition(dataset, { by? })
71
71
  │ ├─ A shell command → e3.customTask(name, [inputs], outputType, command)
72
- │ ├─ A named function (RPC) → e3.function(name, fn, config?) — called by name, persists nothing
72
+ │ ├─ A named function (RPC) → e3.function(name, fn, config?) — called by name; a call through a workspace is kept for its lifetime
73
+ │ │ └─ It reads workspace data too → e3.function(name, { inputs, args, output, runner? }, fn) — inputs read at each call
73
74
  │ ├─ Audited state → e3.record(name, type, { initial?, indexes?, mutations?, migrations? }), declared whole
74
75
  │ │ ├─ Its writes → mutations: (mutation) => ({ name: mutation.reduce | edit | patch })
75
76
  │ │ ├─ An order to page in → indexes: (index) => ({ name: index.on([...fields]) | index.key(fn) | index.keys(fn) }) (reference/record-indexes.md)
76
77
  │ │ ├─ Read by a time window or a 2D window → index.interval | index.area
77
78
  │ │ ├─ Read a block of keys over time tiles, or their totals → index.series | index.summary
78
- │ │ └─ Read what rows nest (jobs, a value a day, child rows, trees) a tile at a time, with totals and subtotals
79
- │ │ → index.nested({ collections, tile, summary? })
79
+ │ │ ├─ Read what rows nest (jobs, a value a day, child rows, trees) a tile at a time, with totals and subtotals
80
+ │ │ │ → index.nested({ collections, tile, summary? })
81
+ │ │ └─ Read a few keys of a Dict field across every row (each row's figures by category) → index.entries(field)
80
82
  │ ├─ A record's type changes → migrations: (migration) => [migration.value | rows | rekey(name, fn), …], in order (reference/record-migrations.md)
81
83
  │ ├─ A UI task → ui(name, [inputs], fn) from @elaraai/e3-ui (the e3-ui skill)
82
84
  │ ├─ A function written in python or another node package → East.importFunction(pkg, name, FunctionType) in the body
@@ -383,7 +385,8 @@ const change = e3.streamTask('change', {
383
385
  | Definition | What it is |
384
386
  |---|---|
385
387
  | `e3.customTask(name, inputs, outputType, command, { environment? })` | A task that runs a bash script: `command($, inputPaths, outputPath)` builds it from the staged beast2 input files, and it writes the output as a beast2 file. |
386
- | `e3.function(name, fn, { runner?, environment? })` | A named function, called by name with arguments (`e3 call`, the API) and its result returned inline: not in the dataflow, and a call persists nothing. An argument is a value, or in a call through a workspace one of its datasets, read where it is stored. A server bounds a call by a timeout and a 1 MiB result, so long work belongs in a task. A `custom` runner must speak the runner CLI (`<command> -i <arg>… -o <out> <ir>`). |
388
+ | `e3.function(name, fn, { runner?, environment? })` | A named function, called by name with arguments (`e3 call`, the API, `Func.bind`) and its result returned inline: not in the dataflow. An argument is a value, or in a call through a workspace one of its datasets, read where it is stored. A call through a workspace is the server's: it outlives the request that starts it — the client starts it and polls it to its end — and runs until its timeout, the server's ceiling (ten minutes locally) unless it asks for less; it can be cancelled; and the server keeps it for its lifetime, an hour for a success or a cancel and a week for any other end: who made it, its arguments, the versions of the inputs it read, its value and its logs (reference/from-code.md). A call through the package runs within one request and keeps nothing. A result is at most 1 MiB, so a large one belongs in a task. A `custom` runner must speak the runner CLI (`<command> -i <arg>… -o <out> <ir>`). |
389
+ | `e3.function(name, { inputs, args, output, runner?, environment?, async? }, fn)` | A function that reads the workspace as well: `inputs` (an input, a task's output or a record, as a task takes them) are read as stored when each call launches, pinned at their hashes and named in the result's `inputs`; the caller passes `args` alone. The body takes the inputs, then the arguments. `e3.package` collects the inputs and what they depend on; nothing reruns when one changes. The inputs are read one at a time and the call waits for no run, so a call during a run may read one input before the run rewrites it and another after: the hashes in `inputs` say which. Called through a workspace only (`e3 call -w`); an unassigned input is `invalid`, naming it and why. ❗ Refused: an `e3.partition` input, and the `custom` runtime with inputs. `FunctionSpec` names the spec's type. |
387
390
  | `e3.package(name, version, ...items)` | Bundles the items and everything they depend on — pass the last tasks, records and functions; a package passed in contributes its contents. The name and version must be valid file names. |
388
391
  | `e3.export(pkg, zipPath, { functions?, cores? })` | Writes the package zip, resolving every `East.importFunction` (a workspace package is exported by the export itself, `cores` packages at once, the CPUs by default; `functions` lists manifests built elsewhere). |
389
392
 
@@ -392,7 +395,11 @@ const process = e3.customTask('process', [rawData], StringType,
392
395
  ($, inputPaths, outputPath) => East.str`python script.py -i ${inputPaths.get(0n)} -o ${outputPath}`);
393
396
  const add = e3.function('add',
394
397
  East.function([IntegerType, IntegerType], IntegerType, ($, a, b) => a.add(b)));
395
- await e3.export(e3.package('tools', '1.0.0', process, add), '/tmp/tools.zip');
398
+ // Reads the price list from the workspace at each call; the caller passes the sku
399
+ const prices = e3.input('prices', DictType(StringType, FloatType));
400
+ const priceOf = e3.function('price_of', { inputs: [prices], args: [StringType], output: FloatType },
401
+ ($, prices, sku) => prices.get(sku, ($, _sku) => 0.0));
402
+ await e3.export(e3.package('tools', '1.0.0', process, add, priceOf), '/tmp/tools.zip');
396
403
  ```
397
404
 
398
405
  ### Records — audited state, written only through mutations
@@ -476,7 +483,7 @@ cheap. A view reads every field of the rows it shows, so keep a bulky payload it
476
483
  does not display in a second record keyed the same way.
477
484
 
478
485
  A record's indexes (`index.on` / `key` / `keys`, `interval`, `area`,
479
- `series`, `summary`, `nested`) are in
486
+ `series`, `summary`, `nested`, `entries`) are in
480
487
  [reference/record-indexes.md](reference/record-indexes.md), and its migrations
481
488
  in [reference/record-migrations.md](reference/record-migrations.md).
482
489
 
@@ -504,7 +511,7 @@ Read the one a task needs; each holds its subject whole.
504
511
 
505
512
  | File | Holds |
506
513
  |---|---|
507
- | [reference/record-indexes.md](reference/record-indexes.md) | Secondary indexes, interval and area indexes, series and summary indexes, nested series indexes |
514
+ | [reference/record-indexes.md](reference/record-indexes.md) | Secondary indexes, interval and area indexes, series and summary indexes, nested series indexes, entries indexes |
508
515
  | [reference/record-migrations.md](reference/record-migrations.md) | `migration.value` / `rows` / `rekey`, and how a record's type changes |
509
516
  | [reference/cli.md](reference/cli.md) | Every `e3` command: repositories, packages, workspaces, datasets, tasks, runs, calls, records, watch, convert, auth, gc |
510
517
  | [reference/from-code.md](reference/from-code.md) | `@elaraai/e3-api-client`, `@elaraai/e3-core`, `e3-api-server` |
@@ -34,7 +34,7 @@ a task is `<ws>.<task>` and a mutation `<record>.<mutation>`.
34
34
  | `e3 task list [repo] <ws>` | Tasks with the status of each one's latest run. |
35
35
  | `e3 task logs [repo] <ws.task> [-n <lines>] [--all] [--follow] [--execution <task>/<inputs>/<id>]` | The last 200 lines by default, of the latest attempt over the task's current inputs, or its latest run; `--follow` stays on that execution; `--execution`: one unit's log, as a split task's log names it (local). |
36
36
  | `e3 run <repo> <pkg[@ver].task> [inputs.beast2…] -o <out> [--force] [-v] [-j <n>] [--memory <size>]` | Run one task ad hoc. |
37
- | `e3 call <repo> <pkg[@ver].fn> [args…] [-o <out.beast2>] [-j <n>] [--memory <size>] [-v]` · `e3 call <repo> -w <ws> <fn> [args…]` | Call a function; each argument is an `.east` literal or a `.beast2`/`.json`/`.east` file, and with `-w` one written `@<keypath>` (`@.inputs.sales`) is that dataset of the workspace, pinned at its hash when the call starts. |
37
+ | `e3 call <repo> <pkg[@ver].fn> [args…] [-o <out.beast2>] [-j <n>] [--memory <size>] [-v]` · `e3 call <repo> -w <ws> <fn> [args…]` | Call a function; each argument is an `.east` literal or a `.beast2`/`.json`/`.east` file, and with `-w` one written `@<keypath>` (`@.inputs.sales`) is that dataset of the workspace, pinned at its hash when the call starts. A function that declares `inputs` reads them from the workspace itself, so it takes its arguments alone and is called with `-w`; without it, it is refused, naming its inputs. The value goes to stdout, and the function's stdout and stderr to stderr. Through a server's workspace the call is the server's, kept for its lifetime: it runs as long as its timeout allows, a call longer than a second is named (`Call <id> runs on`), and Ctrl-C asks the server to stop it (exit 130). |
38
38
  | **Records** (`-w <ws>` required) | |
39
39
  | `e3 mutate <repo> <record.mutation> [args…] -w <ws> [-j <n>] [--memory <size>] [-v]` | Apply a mutation. |
40
40
  | `e3 seed <repo> <record> <file.beast2> -w <ws> [-j <n>] [--memory <size>]` | Commit a record's first state from a beast2 file, as its `$init`: for a record declared with no initial value, unassigned until then (local). The file is taken in as a `file` source is, never read whole; a record that holds a state is refused. |
@@ -18,7 +18,8 @@ naming the holder: its pid, boot id, command and when it took the lock.
18
18
  | Workspaces | `workspaceList`, `workspaceCreate(url, repo, ws, opts)`, `workspaceCopy(url, repo, from, to, opts)` → the target, made or replaced whole, `workspaceBundle(url, repo, ws, opts)` → the workspace as it is, as a bundle's bytes — its package, every dataset's ref, the executions its tasks' outputs come from, and every object those reach — and `workspaceBundleImport(url, repo, ws, bundle, opts)` → the workspace made from one under a name no workspace has, in another repository or another e3 (`workspace_exists`, `package_exists`, `bundle_invalid`), its tasks up to date with no run; a host mounts these routes where a bundle fits in a request: the local server, and e3-web, `workspaceGet`, `workspaceStatus(url, repo, ws, opts, { paths? })` — the whole workspace's, or the datasets named and the tasks producing them, `workspaceStatusSince(url, repo, ws, etag, opts, { paths? })` → `{ status, etag }`, or `null` while the status answered under `etag` is current (a poll sends the last answer's tag back; `null` asks in full), `workspaceLockStatus(url, repo, ws, opts)` → what holds the workspace and how far it says it has got (a deploy's files and records), or `null`, `workspaceRemove`, `workspaceDeploy(url, repo, ws, 'pkg@ver', opts, { schema?, inputs?, allowDropRecords?, plan?, onProgress? })` — a job it polls, whose progress while `deploying` is the deploy's own, answering what it did with each record, index and input, `workspaceExport(url, repo, ws, opts, { name?, version? })` → zip bytes. A poll's request takes `pollRequestOptions(opts)`: one attempt, its next poll being its retry |
19
19
  | Datasets | `datasetGet(url, repo, ws, path, opts)` → `{ data, hash, size }` (a collection downloads as its segments), `datasetGetStream`, `datasetGetPage(…, window, opts)`, `datasetFindKey(…, query, opts)`, and several reads in one request (at most `DATASET_BATCH_MAX`, 10,000, each at one content hash, in a body of at most 16 MiB: a larger one is refused 413, `payload_too_large`): `datasetFindKeys(…, { queries, index?, hash? }, opts)` — key searches, `datasetGetRows(…, { keys, hash? }, opts)` — a Dict's rows by `.east` key, each with its position — or `datasetGetRows(…, { keysOf: { path, index, runs, hash }, hash? }, opts)`, by the keys the entries of some runs of another record's index name, which the server reads from the index so none is sent (a drawing's details for its window's cells), a stale `keysOf.hash` thrown as `RunsHashMismatchError` naming the record's content — and `datasetGetRuns(…, { runs, hash, index?, join? }, opts)` — the entries of several runs as one window, a rows or runs answer holding the first `count` the page budget reaches (by runs, of `runEntries`); and where a narrowing's rows sit in a record, from its index alone: `datasetPlace(…, { index, runs, offset?, limit?, hash }, opts)` → `{ segments, placed, runEntries, totalElements, hash }` — how many of the runs' entries each record segment holds (`{ segment, offset, count, rows }`), for the first `placed` of a window from `offset` (the next window from `offset + placed`), and `datasetWithin(…, { index, runs, keys, hash }, opts)` → `{ within, hash }` — whether each index entry key (`(ik=…, k=…)`) lies in one of the runs, `datasetSet(url, repo, ws, path, beast2Bytes, opts)`, `datasetSetStream(url, repo, ws, path, { size, hash, slice }, opts, { onCommitProgress? })` — a file of any size, the server's commit saying how far it has taken it in, `datasetList`, `datasetListAt`, `datasetListRecursive`, `datasetListWithStatus`, `datasetGetStatus` |
20
20
  | Runs and tasks | `dataflowExecute(url, repo, ws, { force?, filter? }, opts, { pollInterval?, timeout? })` → the result (or `dataflowExecuteLaunch` and `dataflowExecutePoll`) — `force` is `true` or the names of the tasks to re-run, `filter` one task's exact name, `dataflowCancel` — with nothing running, `dataflow_error` ("No active execution for this workspace"), `dataflowGraph`, `dataflowBudget`, `taskList`, `taskGet`, `taskExecutionList(url, repo, ws, task, opts, { limit?, before? })` — a page of the task's runs, the latest first, each naming its `executionId`, the next page the runs `before` the last one's (100 a page unless `limit` says, 1,000 at most), `taskLogs(url, repo, ws, task, { stream?, offset?, limit?, execution? }, opts)` — a chunk of the log of the task's current execution, or of the one `execution` names (`{ inputsHash, executionId }`), the chunk naming its execution and whether it has `ended` |
21
- | Functions | `functionList`, `functionDescribe`, `functionCall(url, repo, pkg, version, fn, { args, runner, limits }, opts)` — each argument `variant('value', beast2Bytes)`; the function runs on its own runner for any caller (`runner: none`); a runner the call names is never `custom`, and loads a platform package the function's does not only for an elevated caller; `workspaceFunctionList`, `…Describe`, `…Call(url, repo, ws, fn, request, opts)` — where an argument may also be `variant('dataset', path)`, a dataset of the workspace pinned at its hash, which the result names (`inputs`); `oneShotExecute` — a reader runs a platform-free one (stock runner, `platforms: []`, no platform call), and its result names the datasets it read (`inputs`); `splitCall(url, repo, ws, { bodyIr, args, output, then, runner, limits }, opts, { onProgress? })` — a program over a dataset's pieces, as a job it polls, under the same rule (or `splitCallLaunch`, `splitCallStatus` and `splitCallExplain`) |
21
+ | Functions | `functionList`, `functionDescribe`, `functionCall(url, repo, pkg, version, fn, { args, runner, limits }, opts)` — each argument `variant('value', beast2Bytes)`; within one request, keeping nothing; the function runs on its own runner for any caller (`runner: none`); a runner the call names is never `custom`, and loads a platform package the function's does not only for an elevated caller; `workspaceFunctionList`, `…Describe`, `…Call(url, repo, ws, fn, request, opts, { signal?, onStarted?, startWaitMs? })` — where an argument may also be `variant('dataset', path)`, a dataset of the workspace pinned at its hash, which the result names (`inputs`); `oneShotExecute` — a reader runs a platform-free one (stock runner, `platforms: []`, no platform call), and its result names the datasets it read (`inputs`), within one request, keeping nothing; `oneShotCall(url, repo, ws, request, opts, { signal?, onStarted?, startWaitMs? })` — the same, under the same rule, started as a kept call through the workspace (below), and run within one request on a server that keeps none (`oneShotStart` its start apart); `splitCall(url, repo, ws, { bodyIr, args, output, then, runner, limits }, opts, { onProgress?, signal? })` → `{ result, output, report }` — a program over a dataset's pieces, as a job it polls, under the same rule; `output` is `array`, `set`, `dict { merge }`, `fold { combine, zero }`, or `first { limit }` — an `array`'s first `limit` elements in input order, its pieces run in order and stopped once they hold them; `then`, the final function, takes the assembled output and then the arguments not partitioned, in order, and one of another arity is `invalid`, and how it ran: its pieces, the units it ran and the cache served, and its peak; a value over the call's result limit is `too_large`, naming its stored `output`, which `collectionOpen(url, repo, output, opts)` → `{ type, totalElements, page({ offset, limit }) }` reads a window at a time, fetching only the segments each window overlaps; aborting `signal` cancels the job, whose units the server stops (or `splitCallLaunch`, `splitCallStatus`, `splitCallCancel` — `cancelled`, or the status the job had already ended with — and `splitCallExplain`) |
22
+ | Calls through a workspace | A call through a workspace is the server's, and outlives the request that starts it: `workspaceFunctionCall` starts it, waits up to the server's window (20 s; `startWaitMs` less), and polls a call still running to its end, each poll held until it ends or a while passes, however long its timeout lets it run — the server's ceiling, ten minutes locally, unless its `limits` ask for less; aborting `signal` asks the server to stop it, and `onStarted(id)` is told the id of one that runs on; a server that keeps no calls is called through `workspaceFunctionCallSync`, the sync route, which a caller may name itself. Apart: `workspaceFunctionStart(…, opts, { waitMs? })` → `{ id, status }` (`?wait=0` answers `running` at once), `workspaceFunctionCallStatus(url, repo, ws, id, opts, { waitMs?, signal? })` → `running`, `completed` with the result, `cancelled` naming who asked, or `lost`, `workspaceFunctionCallCancel(url, repo, ws, id, opts)`. The server keeps each call for its lifetime, an hour for a success or a cancel and a week for any other end: `workspaceCallList(url, repo, ws, opts, { function?, state?, before?, limit? })` — a page of them, the latest first, its `next` the next page's `before` (`FUNCTION_CALLS_PAGE_DEFAULT` 50, `…_MAX` 200), and `workspaceCallGet(url, repo, ws, id, opts)` — one whole: its function and package (`none` for a one-shot), its arguments (values by the objects they were stored as, datasets by the hashes they were pinned at), the inputs it read, its limits, its value's object, its log tails and when it is forgotten (`expiresAt`); `objectGet` reads a value by its hash. A one-shot started as a call (`oneShotCall`) is kept, polled, cancelled and listed as a function's call is, its program the caller's, under its one-shot grant. A workspace keeps no call that another made: `internal`, "keeps no call" |
22
23
  | Records | `workspaceRecordDescribe`, `workspaceRecordMutate(url, repo, ws, record, mutation, { args, actor, limits }, opts, idempotencyKey?)`, `workspaceRecordHistory(url, repo, ws, record, limit, opts, from?)`, `workspaceRecordCompact` |
23
24
  | From East | `Platform` and the `platform_*` functions (`platform_dataset_get`, `platform_dataflow_execute`, …): the same calls as platform functions, for an East program that drives a server |
24
25
 
@@ -41,8 +42,11 @@ over itself.
41
42
  **`e3-api-server`** serves repositories: `--repos <dir>` (each subdirectory a
42
43
  repository) or `--repo <path>` (one, served as `default`), `-p`/`--port` (3000),
43
44
  `-H`/`--host` (localhost), `--cors`, `-j`/`--memory` (the server's budget, for
44
- every run and call it serves and every upload it takes in), and auth — `--oidc`, a built-in provider for `e3
45
+ every run and call it serves and every upload it takes in), the call limits —
46
+ `--call-deadline` (a one-shot or sync function call's, 120s), `--job-timeout`
47
+ (a split call's job, or a kept call, 10m), `--max-result` (1M, held in the server's memory while
48
+ it is answered) and `--max-log` (256K) — and auth: `--oidc`, a built-in provider for `e3
45
49
  auth login` (`--token-expiry`, `--refresh-token-expiry`), or an external JWT
46
50
  issuer (`--auth-key`, `--auth-issuer`, `--auth-audience`). In code,
47
- `createServer({ reposDir | singleRepoPath, port, host, … })` starts one, and its
48
- route factories mount on another host.
51
+ `createServer({ reposDir | singleRepoPath, port, host, calls?, … })` starts one,
52
+ and its route factories mount on another host.
@@ -1,6 +1,6 @@
1
1
  # Record indexes
2
2
 
3
- Secondary, interval and area, series and summary, and nested series indexes: what each files, how it is read, and what it costs. Part of the `e3` skill.
3
+ Secondary, interval and area, series and summary, nested series, and entries indexes: what each files, how it is read, and what it costs. Part of the `e3` skill.
4
4
 
5
5
  ## Contents
6
6
 
@@ -8,6 +8,7 @@ Secondary, interval and area, series and summary, and nested series indexes: wha
8
8
  - Interval and area indexes — `index.interval`, `index.area`
9
9
  - Series and summary indexes — `index.series`, `index.summary`
10
10
  - Nested series indexes — `index.nested`
11
+ - Entries indexes — `index.entries(field)`
11
12
 
12
13
  ## Secondary indexes — `index.on([...fields])`, `index.key(fn)`, `index.keys(fn)`
13
14
 
@@ -324,3 +325,52 @@ the summary tiles they touch and the subtotals of the tiles they touch at each
324
325
  level. A replace on the way, which a recursive type's patch always is, and an
325
326
  inserted or deleted row are compared whole. Both ways give the same delta, and a maintained
326
327
  index is the one `e3 reindex` rebuilds, byte for byte.
328
+
329
+ ## Entries indexes — `index.entries(field)`
330
+
331
+ What a reader needs when a record's rows each hold a Dict of categories — a
332
+ station's figures by service — and it reads a few categories at a time. An
333
+ entries index files one Dict field of the rows entry by entry, each under its
334
+ own key and then the row's, carrying that key's value, so a key's entries
335
+ across the whole record are one contiguous range: a reader reads the keys it
336
+ picks as a range each, in one request, and reads no other key's entries and no
337
+ segment of the record's own. Each row stays one row, its categories nested in
338
+ it.
339
+
340
+ ```typescript
341
+ // StationsType: Dict<String, { site: String, parcels: Integer, byService: Dict<String, { parcels: Integer, waiting: Integer }> }>
342
+ const stations = e3.record('stations', StationsType, {
343
+ initial: new Map(),
344
+ indexes: (index) => ({
345
+ stations_by_service: index.entries('byService'), // { ik: the service, k: the station } → that service's figures there
346
+ stations_by_site: index.on(['site']), // pages each station without its services
347
+ }),
348
+ });
349
+ ```
350
+
351
+ | | |
352
+ |---|---|
353
+ | **What it files** | `{ ik, k } → value`: once for each key the row's field holds, that key and the row's, carrying the key's value. A row whose field is empty files nothing. The field's key may be any type a Dict is keyed by — a String, a Struct, an Option — and its value any type |
354
+ | **Its definition** | keyed by the field's key and valued by its value (`stations.indexes.stations_by_service.keyType`, `.valueType`), its field as written beside them (`.entries.field`), as an `on` index carries its fields: what a binding reads (see **e3-ui**) |
355
+ | **Reading** | a search of the index by a key, as East prints it — `{ key: '"Priority"' }` — finds the key's range: several keys are several searches in one `datasetFindKeys` request, then one `datasetGetRuns` read of the entries they select |
356
+ | **Several** | one entries index a Dict field: a record may declare one for each |
357
+ | **Refused, in words** | a field the rows lack, or one that is not a Dict, naming the fields that fit — TypeScript refuses both where they are written; a `value`, since each entry carries its own; a second entries index over a field; and one beside a nested series index: one kind of index files a record's nested fields |
358
+
359
+ **The lean rows.** Beside an entries index e3 keeps the record's rows by key,
360
+ each with the field emptied — the row's own type, as a nested series index's
361
+ lean rows are — in an index of the record's named `<index>_rows` (e3-types'
362
+ `entriesRowsName`), built with it and never declared, as a nested series
363
+ index's span is: a reader of the entries reads each row there without the
364
+ entries it reads apart. Each entries index's lean rows empty its own field
365
+ alone. The record's other indexes that carry nothing or the row carry it with
366
+ every field an entries index files emptied, so a page through them reads no
367
+ entry; an index with a `value` of its own carries its own, and the record's own
368
+ rows stay whole. An index the record declares under the lean rows' name is
369
+ refused.
370
+
371
+ **Writes.** A write changes the entries whose key or value it changed — a
372
+ row's entries before and after compared key by key: one gone a delete, one come
373
+ an insert, one whose value changed an update by the value's patch — and the
374
+ lean rows where it changed the row's other fields. After a patch, an edit or a
375
+ reduce alike, a maintained entries index, its lean rows and the indexes beside
376
+ them are what `e3 reindex` rebuilds, byte for byte.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: e3-ui
3
- description: "Builds interactive decision surfaces as e3 UI tasks (ui()) authored in east-ui JSX and bound to workspace data: Data.bind and Data.bindPaged for datasets, Record.bind for records and their mutations, Func.bind for e3.function calls, staged edits reviewed with the Diff tag. Provides the planning builders Plan, Sheet, Calendar, Roster, Allocation, Flowchart and Schematic, plus Ontology, Experiment, the Decide loop (Decision.bind, DecisionQueue, DecisionJournal), the Studio page builder, saved jq queries (Query.Builder), and rendering deployed surfaces in a React app (E3Provider). Use when a UI reads or writes e3 workspace data or runs as an e3 task; components with no e3 data are east-ui's."
3
+ description: "Builds interactive decision surfaces as e3 UI tasks (ui()) authored in east-ui JSX and bound to workspace data: Data.bind and Data.bindPaged for datasets, Record.bind for records and their mutations, Func.bind for e3.function calls, staged edits applied or discarded together. Provides the planning builders Plan, Sheet, Calendar, Roster, Allocation, Flowchart and Schematic, plus Ontology, the Decide loop (Decision.bind, DecisionQueue, DecisionJournal), the Studio page builder, saved jq queries (Query.Builder), and rendering deployed surfaces in a React app (E3Provider). Use when a UI reads or writes e3 workspace data or runs as an e3 task; components with no e3 data are east-ui's."
4
4
  ---
5
5
 
6
6
  # e3-ui — e3 + UI bridge
@@ -8,13 +8,12 @@ description: "Builds interactive decision surfaces as e3 UI tasks (ui()) authore
8
8
  `@elaraai/e3-ui` connects **east-ui** JSX tags to **e3** workspaces. A decision
9
9
  surface is an e3 **UI task** whose reads and writes of workspace data are
10
10
  recorded in a manifest derived from its IR, so the engine knows what the UI
11
- depends on and re-renders it when that data changes. With staged writes,
12
- `<Diff>` review and commit / discard, a view is where a user commits a decision
13
- with its evidence.
11
+ depends on and re-renders it when that data changes. With staged writes and
12
+ commit / discard, a view is where a user commits a decision with its evidence.
14
13
 
15
14
  Everything comes from one import, `@elaraai/e3-ui`: the `ui()` task factory, the
16
15
  bindings (`Data`, `Record`, `Func`, `Decision`, `Slice.bindRecords`), the e3
17
- tags (`<Diff>`, `<Ontology>`, `<Experiment>`, `<Plan>`, `<Sheet>`, `<Calendar>`,
16
+ tags (`<Ontology>`, `<Plan>`, `<Sheet>`, `<Calendar>`,
18
17
  `<Roster>`, `<Allocation>`, `<Flowchart>`, `<Schematic>`, `<DecisionQueue>`,
19
18
  `<DecisionJournal>`) and the `Studio` and `Query` components. Base tags
20
19
  (`<VStack>`, `<Text>`, `<Stat>`, …) come from `@elaraai/east-ui`.
@@ -93,8 +92,8 @@ Task → What do you need?
93
92
  │ ├─ Write a value → .write(v)
94
93
  │ ├─ Write + kick dataflow → .writeAndStart(v)
95
94
  │ ├─ Current status (variant) → .status() (e.g. .status().hasTag('stale'))
96
- │ ├─ The binding handle → .binding (pass to <Diff bindings={[…]} />)
97
- │ └─ Staged mode → { mode: 'staged' } + .commit() / .discard()
95
+ │ ├─ The binding handle → .binding (its source and patch paths, and its mode)
96
+ │ └─ Staged mode → { mode: 'staged' } + .commit() / .discard(), .pending() while a change waits
98
97
  │
99
98
  ├─ Read a collection too large to hold whole — Data.bindPaged(dataset, options?)
100
99
  │ ├─ One window → .page(offset, limit) (none = in flight; some([]) = exhausted; a failure throws)
@@ -119,13 +118,11 @@ Task → What do you need?
119
118
  │ ├─ Lifecycle (variant) → .status() (idle|running|succeeded|failed|cancelled)
120
119
  │ ├─ Failure detail → .error() (Option — message/kind/stdout/stderr)
121
120
  │ ├─ Spinner boolean → .pending()
122
- │ └─ Stop waiting → .cancel() (client-side; server still finishes)
123
- │
124
- ├─ Review pending (staged) changes
125
- │ └─ <Diff bindings={[a.binding, b.binding, …]} />
121
+ │ ├─ Stop the call → .cancel() (asks the server to stop it; a later .call() supersedes one in flight the same way)
122
+ │ └─ A function that reads workspace data too → e3.function(name, { inputs, args, output }, fn); .call(args…) takes the args alone
126
123
  │
127
124
  ├─ Edit a graph / ontology dataset
128
- │ └─ <Ontology binding={view.binding} /> (OntologyType: NodeType / LinkType)
125
+ │ └─ <Ontology value={view} /> (OntologyType: NodeType / LinkType)
129
126
  │
130
127
  ├─ Offer components for operators to arrange on pages (Studio)
131
128
  │ ├─ Declare one — self-contained, like a ui() body → Studio.component(key, meta, fn)
@@ -158,6 +155,7 @@ Task → What do you need?
158
155
  │ ├─ …on paged resources: read a cell at a time → the kind's source lists index.series + index.summary beside its interval index
159
156
  │ ├─ A link between two runs, or two events → Plan.link({ from: Plan.ref(…), fromRun, … }) / Plan.link({ from: Plan.eventRef(kind, key), … })
160
157
  │ ├─ Its library pane: templates, backlog, series, cards → library={[Plan.library.events(), Plan.library.backlog(), Plan.library.series(), Plan.library.tab(rows, {…})]}
158
+ │ ├─ The app's own words for what it draws → vocabulary={{ unassigned, backlog, rows, dueThisWeek, confirmed, … }}
161
159
  │ ├─ Its inspector pane: what is selected → inspector (+ an event kind's own: Schedule.events(record, { inspector }))
162
160
  │ ├─ Drags of templates, backlog cards and events → built in with resources + events (+ library); canDrop={fn(Schedule.Types.Candidate) => Option<String>}
163
161
  │ ├─ The app's optimiser over the window and the backlog → optimise={Func.bind(e3.function)} from Plan.Types.OptimiseRequest({ job: Job }, { presses: Press }) to Plan.Types.OptimiseResult({ job: Job })
@@ -172,30 +170,38 @@ Task → What do you need?
172
170
  │ ├─ The host's rows → <Sheet data={…} id="id" columns={{…}} />
173
171
  │ ├─ Narrow its rows and templates — one rail → slice={{ slice: Slice.bindRecords(key, { rows, rowTemplates, … }) }} (Sheet.templates(rows, { …, source }))
174
172
  │ ├─ Its panes, each optional → library={[Sheet.library.rows(), Sheet.library.columns(), Sheet.library.tab(…)]} · inspector (+ fields)
173
+ │ ├─ The app's own words for what it draws → vocabulary={{ members, unassigned, source, destination, wanted, actual }}
175
174
  │ ├─ Its columns, registers and the driver → Sheet.column.* / Sheet.register.* / Sheet.driver
176
175
  │ ├─ Groups, loose rows between them, read-only sub rows → Sheet.group / Sheet.Types.Entry / Sheet.subRows
177
176
  │ ├─ Data too large to hold whole → data={paged}, a Data.bindPaged handle
178
177
  │ ├─ The app's optimiser over the rows in view → optimise={Func.bind(e3.function)} from Sheet.Types.OptimiseRequest(R) to Sheet.Types.OptimiseResult(R)
178
+ │ ├─ On a phone: a column pinned, how many in view → narrow={{ pin?: "<column>", columns?: 1 | 2 | 3 }} (none pinned, 2 in view by default)
179
179
  │ └─ Drafts checked as they are made, one checked Save → onUpdate | onApply, ready, newRow
180
180
  │
181
181
  ├─ Schedule bound records on a calendar — the Calendar
182
182
  │ ├─ Event records, with their backlog → <Calendar events={{ job: Calendar.events(Record.bind(jobs), { name, icon, title, start, end, resource: { field, of }, entries, backlog }) }} />
183
183
  │ ├─ Resources and templates, read whole → resources={{ machines: Calendar.resources(Data.bind(r).read(), {…}) }} · Calendar.templates(rows, {…})
184
+ │ ├─ The app's own words for what it draws → vocabulary={{ backlog, templates, template, dueThisWeek, dueNextWeek, later, noDate, unscheduled, unassigned, resources }}
184
185
  │ ├─ Narrow it — one rail, one date window → slice={{ slice: Slice.bindRecords(key, { job: { source, range: "start" }, machines?, jobTemplates? }) }}
185
186
  │ └─ The app's optimiser → optimise={Func.bind(e3.function)}
186
187
  │
187
- ├─ Draw a state-transition or process flow — the Flowchart
188
- │ ├─ An e3 record of flows by name → <Flowchart record={…} flow="…" /> (record = Record.bind(r), r of Flowchart.Types.Flows)
189
- │ ├─ The record's value, written as literals → Flowchart.values({ [name]: { lanes, states, links, triggers? } }) (a lone flow: one entry)
190
- │ ├─ One flow of the host's, an input's value → <Flowchart data={Data.bind(input)} /> (the input's value Flowchart.value({ … }))
191
- │ ├─ One flow from the app's own tables → <Flowchart data={Flowchart.over(states, { state, links, link, lanes, triggers?, trigger? })} />
192
- │ ├─ Decision triggers and evidence on the transitions → a flow's triggers, a link's trigger / evidence
193
- │ ├─ Selection and ⌥-click path tracing → onSelect*, onTracePath
194
- │ ├─ Its inspector → on by default (inspector={false} takes it away); a state's or a transition's own Details → inspector={{ state, transition }}
195
- │ ├─ The flows listed by name, one opened, new started → library={[Flowchart.library.flows()]}
196
- │ ├─ State and transition templates, the author's cards → library={[…, Flowchart.library.states(templates.read(), {…, source }), Flowchart.library.transitions(…), Flowchart.library.tab(rows, {…})]}
197
- │ ├─ Narrow its flows, templates and tabs — one rail → slice={{ slice: Slice.bindRecords(key, { flows?, steps?, … }) }}
198
- │ └─ Edit a flow: lanes, states, transitions, one Save → record={…}, or data={…} + onApply (canConnect vetoes a pair)
188
+ ├─ Draw a state-transition flow over the app's records — the Flowchart
189
+ │ ├─ A kind per record: its states, transitions, lanes, decisions → <Flowchart states={Flowchart.states(record, { label, lane, order, members? })} transitions={Flowchart.transitions(record, { from, to, decision?, kind?, evidence? })} lanes={Flowchart.lanes(record, { label, order })} decisions={Flowchart.decisions(record, { label, owner? })} />
190
+ │ ├─ Editable, or read only → Record.bind(record) · Data.bind(record) (lanes and decisions: small records, read whole)
191
+ │ ├─ Narrow its states, transitions and cards — one rail → slice={{ slice: Slice.bindRecords(key, { states: { source: Data.bindPaged(record, { indexes }) }, transitions: { … }, <a cards list's source>? }, { presets? }) }} (+ the kind's entries: Data.bindPaged(record))
192
+ │ ├─ What a narrowing leaves out: gone, or faded → narrowed="hide" (the default) · narrowed="dim"
193
+ │ ├─ What its cards and labels draw from the app's rows → details: Flowchart.details(rows, { details: [Flowchart.figure(f), .tags(f), .histogram(f, { unit }), .list(f)] }) on Flowchart.states / .transitions — rows keyed as the kind's, bound as it is read (Data.bind, or Data.bindPaged beside a kind read through its source)
194
+ │ ├─ …where each read shows, tags in the app's colours → show: "all" (default) | "canvas" | "inspector" · Flowchart.tags(f, { colors: { Tag: { colorPalette, variant? } } or rows.read() of Flowchart.Types.TagColor, legend: true })
195
+ │ ├─ …a histogram over the app's own bins and axis → Flowchart.histogram(f, { unit, bins?: [edges…] (left out: every row's edges merged), scale?: "band" | "linear", ticks?: [n, { at, label }] })
196
+ │ ├─ …weighed by what the rail picks of a Dict field → Flowchart.details(evidence, { source: "evidence", details: [ … ] }) — evidence = Data.bindPaged(record, { indexes: [its index.entries("byService")] }), also the rail's source: Slice.bindRecords(key, { …, evidence: { source: evidence, fields: { byService: { label, hints } }, initial? } }) — a figure adds, a histogram adds bin by bin, a list adds by name, tags join; weigh: false keeps a share's own, and a field the entries lack draws the row's
197
+ │ ├─ Each kind's cards, and the Steps, Transitions and Lanes tabs → Flowchart.templates(rows, { name, group?, values, source? }) on the kind · library={[Flowchart.library.states(), .transitions(), .lanes()]}
198
+ │ ├─ The app's own words for what it draws → each kind's own name: Flowchart.states(record, { …, name: "Stop" }) — its tabs, canvas, inspector, footer and Find say it · vocabulary={{ planned, observed }}, a transition's kinds
199
+ │ ├─ An author's card dropped onto any kind's row → Flowchart.library.tab(rows, { …, drop: (r) => Flowchart.patch(R, { … }) })
200
+ │ ├─ The inspector, a kind's form and the app's check → on by default (inspector={false} takes it away) · Flowchart.states(record, { …, fields?, ready? })
201
+ │ ├─ What the host hears, and the connect veto → onSelectState · onSelectLink · onSelectTrigger · onTracePath (⌥-click) · canConnect={fn → Option<String>}
202
+ │ ├─ Top down, a minimap, no legend, read only → orientation="TD" · minimap · legend={false} · readOnly
203
+ │ ├─ On a phone: how many lanes in view, ‹ › through them → narrow={{ lanes?: 1 | 2 | 3 }} (2 by default; one where the details draw on the cards)
204
+ │ └─ Edit it: lanes, states, transitions, one Save → each kind Record.bind(record) over a record declaring mutation.patch(); Save writes each through its patch door
199
205
  │
200
206
  ├─ Draw the app's records at world coordinates — a floor, a site — the Schematic
201
207
  │ ├─ A kind per record, under its slot → <Schematic extent={{ width, height }} items={{ racks: Schematic.items(record, { name, icon, x, y, label, … }) }} zones={{ … }} links={{ … }} nets={{ … }} />
@@ -206,6 +212,7 @@ Task → What do you need?
206
212
  │ ├─ What a card draws from another record → Schematic.items(…, { details: Schematic.details(record, { status, meter, metric, sublabel }) })
207
213
  │ ├─ The layers, from the app's record → layers={Schematic.layers(systems.read(), { label, order?, tone?, color?, visible?, locked?, opacity? })}
208
214
  │ ├─ Templates, the backlog, the index, the layers → Schematic.templates(rows, { …, source }) · library={[Schematic.library.templates(), .backlog(), .index(), .layers()]}
215
+ │ ├─ The app's own words for what it draws → vocabulary={{ templates, backlog, index, layer, zone, net, link, source, destination }}
209
216
  │ ├─ An author's card dropped onto an entity → Schematic.library.tab(rows, { …, drop: (r) => Schematic.patch(R, { … }) })
210
217
  │ ├─ The inspector, a kind's form and its own Details → inspector · Schematic.items(record, { …, fields?, ready?, inspector? })
211
218
  │ └─ What the host hears, and the connect veto → onSelect={fn(Array<Schematic.Types.Ref>)} · canConnect={fn(Schematic.Types.Candidate) → Option<String>}
@@ -220,6 +227,8 @@ Task → What do you need?
220
227
  │ ├─ The app's optimiser over the week → optimise={Func.bind(e3.function)} from Roster.Types.OptimiseRequest(R) to Roster.Types.OptimiseResult(R)
221
228
  │ ├─ Narrow its duties, targets, people, activities, patterns → slice={{ slice: Slice.bindRecords(key, { duty: { source, range: "start" }, targets?, people?, activities?, patterns? }) }}
222
229
  │ ├─ People by week or by month → view={{ layout: "people", period: "week" | "month", date }}
230
+ │ ├─ Offer only some layouts, no switch with one left → views={["people"]} or views={expr of Array<Roster.Types.Layout>}
231
+ │ ├─ The app's own words for who is on it → vocabulary={{ permanent: "Employees", agency: "Contractors", others: "Colleagues" }}; a fit's reason: Roster.fit(R, { notALead })
223
232
  │ ├─ The shifts' colours, and the app's week patterns → Roster.shifts(rows, { …, color }) · patterns={Roster.patterns(rows, {…})} · library={[…, Roster.library.patterns()]}
224
233
  │ └─ The week's figures in a task → Roster.coverage / check / weekHours / rest (R)
225
234
  │
@@ -232,6 +241,7 @@ Task → What do you need?
232
241
  │ ├─ The app's optimiser over the day → optimise={Func.bind(e3.function)} from Allocation.Types.OptimiseRequest(R) to Allocation.Types.OptimiseResult(R)
233
242
  │ ├─ Narrow its bins, lanes, resources and arrivals — one rail → slice={{ slice: Slice.bindRecords(key, { bin: { source, range: "at" }, <lanes>?, <resources>?, arrivals? }) }}
234
243
  │ ├─ Its panes → library={[Allocation.library.arrivals(), Allocation.library.resources()]} · inspector
244
+ │ ├─ The app's own words for what it holds → labels={{ lane, arrival, resource, quantity, bin, reservation, reserved, priorJob, nextJob, hold, groups: { overdue, ready, removed, allocated, free, loading, busy } }}
235
245
  │ ├─ The app's bin fields on the board, and its own issues → columns={[{ key, label, text }]} · check={fn(CheckContext(R)) → Array<Issue>}
236
246
  │ └─ The board's figures in a task → Allocation.loads / candidates / check / slots (R)
237
247
  │
@@ -240,9 +250,6 @@ Task → What do you need?
240
250
  │ ├─ The bindings' adapters → <ReactiveDatasetProvider> inside it
241
251
  │ ├─ A deployed ui() task, by name → <UITaskPreview task="…" />
242
252
  │ └─ e3 running in the page, no server → apiUrl and fetch from e3-web's createWebE3
243
- │
244
- └─ Let a user ask "did X change Y?" against a dataset and trust the answer
245
- └─ <Experiment data configs experiment? design? journal? columns subject /> (generic over the row; runs e3.functions)
246
253
  ```
247
254
 
248
255
  ## Bindings
@@ -264,7 +271,7 @@ A reactive binding to an `e3.input` or a task's output. `read()` tracks the
264
271
  dependency, so `<Reactive>` re-renders when it changes. Modes:
265
272
  - `'direct'` (default): each `write()` mutates the dataset.
266
273
  - `'staged'`: `write()` accumulates a patch; `commit()` applies it, `discard()`
267
- drops it, and `<Diff bindings={[b.binding]} />` reviews it.
274
+ drops it, and `pending()` says whether a change waits.
268
275
 
269
276
  A record a builder reads whole beside its pages (a templates list, the
270
277
  resources a check reads) binds with `Data.bind`, which the manifest preloads.
@@ -304,12 +311,26 @@ conflict naming the entry, and nothing is overwritten. `Record.onApply(record,
304
311
 
305
312
  ### `Func.bind(fn)`
306
313
 
307
- A call handle for an `e3.function` (bounded RPC: a server deadline and a
308
- result-size limit; long compute belongs in dataflow tasks and
309
- `writeAndStart`). `call(args…)` is fire-and-forget and safe in a sync
310
- `onClick`, latest-wins; the outcome arrives reactively through `read()`,
311
- `status()`, `error()` and `pending()`. All handles bound to one function share
312
- one channel, so one component can launch while another shows the spinner.
314
+ A call handle for an `e3.function`. `call(args…)` is fire-and-forget and safe
315
+ in a sync `onClick`, latest-wins; the outcome arrives reactively through
316
+ `read()`, `status()`, `error()` and `pending()`. All handles bound to one
317
+ function share one channel, so one component can launch while another shows the
318
+ spinner. A call is the server's: it outlives the request that starts it, and
319
+ runs until its timeout — the server's ceiling, ten minutes locally — however
320
+ long that is, so an optimiser of several minutes is called the same way; the
321
+ server keeps it for its lifetime, with its arguments, the inputs it read, its
322
+ value and its logs (the **e3** skill). `cancel()` asks the server to stop the
323
+ call, and `status()` reads `cancelled`; a `call` that supersedes one in flight
324
+ asks the server to stop that one. A result is at most 1 MiB: a large one
325
+ belongs in a task, read with `Data.bind`.
326
+
327
+ A function that declares `inputs` (`e3.function(name, { inputs, args, output },
328
+ fn)`, the **e3** skill) is bound the same way: its handle's `call` takes the
329
+ `args` alone, and each call reads the inputs from the workspace as they are
330
+ stored when it launches. The page binds none of them; an optimiser's eye
331
+ (`optimise={Func.bind(fn)}`) passes its request as the one argument while the
332
+ function reads its reference data as inputs. `e3-ui:func.examples.tsx:funcBindInputs`
333
+ is the example.
313
334
 
314
335
  ```tsx
315
336
  <Reactive>{$ => {
@@ -358,6 +379,18 @@ and `<Schematic>` share one contract:
358
379
  - **The app's optimiser**: `optimise={Func.bind(fn)}`, an `e3.function` from
359
380
  the builder's `Types.OptimiseRequest` to its `Types.OptimiseResult`; its
360
381
  answer lands as one undoable step.
382
+ - **Which views an instance offers**: a component that switches between views
383
+ takes `views` — the Roster's, Calendar's and Allocation's layouts, the
384
+ Ontology's display modes and `<Query.Builder>`'s
385
+ Visual · jq (and `resultViews`, Table · Tree). Literal tags (`views={["people"]}`),
386
+ variants of its `Types`, or an expression of an array of them, so a page's state
387
+ can choose them as it runs. Left out, or empty as the page runs, every view; one
388
+ left, no switch shows in any form of the toolbar; the component's own order
389
+ stands. `e3-ui:roster.examples.tsx:rosterViews` wires a multi-select into it.
390
+ `<DecisionQueue>`'s `facets` is the same.
391
+ - **Which periods an instance offers**: `viewPeriods` on `<Roster>` and
392
+ `<Calendar>` does the same for Day · Week · Month. (A Plan's are its axis's
393
+ `resolutions`.)
361
394
  - **Misuse is refused at build**, naming the change — forms from earlier
362
395
  releases included — so read the error rather than guessing.
363
396
 
@@ -368,7 +401,7 @@ and `<Schematic>` share one contract:
368
401
  | `<Calendar>` | Calendar, Resources and Timeline layouts over event records with a backlog | `e3-ui:calendar.examples.tsx:calendarMinimal` (smallest), `e3-ui:calendar.examples.tsx:calendarOperations`, `e3-ui:calendar-records.examples.tsx:calendarRecordIndexes` |
369
402
  | `<Roster>` | Weekly staffing: duties over people by shift, cover targets, pay, fit, publish | `e3-ui:roster.examples.tsx:rosterMinimal` (smallest), `e3-ui:roster.examples.tsx:rosterWarehouse`, `e3-ui:roster.examples.tsx:rosterPeople` |
370
403
  | `<Allocation>` | A day's arrivals booked into lane slots, each bin on resources | `e3-ui:allocation.examples.tsx:allocationMinimal` (smallest), `e3-ui:allocation.examples.tsx:allocationKilnYard`, `e3-ui:allocation.examples.tsx:allocationFitRule` |
371
- | `<Flowchart>` | States in ordered phase lanes, transitions, decision triggers | `e3-ui:flowchart.examples.tsx:flowchartFlows` (smallest), `e3-ui:flowchart.examples.tsx:flowchartDepot`, `e3-ui:flowchart.examples.tsx:flowchartDetail` |
404
+ | `<Flowchart>` | States in ordered lanes, transitions and decisions, a record of the app's each, the app's details drawn on the cards and labels | `e3-ui:flowchart.examples.tsx:flowchartDwell` (smallest), `e3-ui:flowchart.examples.tsx:flowchartDepot`, `e3-ui:flowchart.examples.tsx:flowchartDepotEditing`, `e3-ui:flowchart.examples.tsx:flowchartTicketMinutes`, `e3-ui:flowchart.examples.tsx:flowchartDepotTopDown` |
372
405
  | `<Schematic>` | Items, zones, links and nets at world coordinates | `e3-ui:schematic.examples.tsx:schematicFloor` (smallest), `e3-ui:schematic.examples.tsx:schematicDataCentre`, `e3-ui:schematic-records.examples.tsx:schematicRecordIndexes` |
373
406
 
374
407
  Field types matter: a `Sheet.column.quantity` sits on a `Float` field, a
@@ -377,16 +410,9 @@ start and end are `Option<DateTime>` when it can wait in the backlog.
377
410
 
378
411
  ## Other surfaces
379
412
 
380
- - **`<Diff bindings={[…]} />`** reviews pending changes of any staged bindings.
381
- - **`<Ontology binding={view.binding} />`** edits a typed node / link graph
382
- (`OntologyType`); stack a `<Diff>` beside it. The **east-ontology** skill
413
+ - **`<Ontology value={view} />`** edits a typed node / link graph
414
+ (`OntologyType`), committing through the binding. The **east-ontology** skill
383
415
  builds the graph.
384
- - **`<Experiment>`** answers "did X change Y?" over a bound dataset: `data` and
385
- `configs` (the questions, `Experiment.Types.Configuration`) via `Data.bind`,
386
- `experiment` (an estimator `(rows, config) → result`) and `design` via
387
- `Func.bind`, a `journal` that Commit appends to, and `columns` / `subject`
388
- whose labels every sentence speaks. The words are derived from the numbers;
389
- nothing is authored.
390
416
  - **The Decide loop.** Reasoning tasks emit `Array<Decision.Types.Decision>`
391
417
  (`Decision.make` / `option` / `reference` / `judgement`).
392
418
  `Decision.bind([Contract]?, { decisions: [views…], judgements })` unions them
@@ -406,7 +432,15 @@ start and end are `Option<DateTime>` when it can wait in the backlog.
406
432
  saved jq queries; `Query.value(sources, queries)` ships some, checked at
407
433
  build. `<Query.Builder queries datasets />` edits a query as steps or jq,
408
434
  checks it, runs it on e3 (split over a large dataset's pieces) and saves it;
409
- `<Query.Library>` lists them.
435
+ `<Query.Library>` lists them. A run of one program is a call the workspace
436
+ keeps, as it keeps a function's (the **e3** skill): held to its own timeout,
437
+ never a request's, and listed among the workspace's calls, naming no
438
+ function. A split run's plan read-out says how many pieces it cut and how
439
+ many units e3's cache served; `first(…)` and `limit(n; …)` over a dataset's
440
+ rows split too, stopping once they have their rows; a run given up — a new
441
+ run, or the builder going — cancels its call, or its split call's job; and a
442
+ split answer too large for one, with no final step, is read a page at a time
443
+ in the Table and the Tree.
410
444
 
411
445
  ## Rendering surfaces in an app — `<E3Provider>`
412
446
 
@@ -442,10 +476,9 @@ in; dates print in UTC.
442
476
  <VStack gap="3">
443
477
  <Slider value={value} min={0} max={100} onChange={t.write} />
444
478
  <HStack gap="2">
445
- <Button variant="outline" onClick={discard}>Discard</Button>
446
- <Button variant="solid" onClick={commit}>Apply</Button>
479
+ <Button variant="outline" onClick={discard} disabled={t.pending().not()}>Discard</Button>
480
+ <Button variant="solid" onClick={commit} disabled={t.pending().not()}>Apply</Button>
447
481
  </HStack>
448
- <Diff bindings={[t.binding]} />
449
482
  </VStack>
450
483
  );
451
484
  }}</Reactive>
@@ -186,6 +186,9 @@ Task → What do you need?
186
186
  ├─ A JSON contract for a type → jsonSchemaFor(T) · back from a vendored schema → typeFromJsonSchema(schema)
187
187
  └─ Data larger than memory → reference/beast2.md; inside a body blob.openBeast(T),
188
188
  and a file on the runner's disk FileSystem.openBeast(T, path) (east-node-std / east-c-std / east-py-std)
189
+ └─ A loop over a lazy input (a large task input, an openBeast) decodes only the fields its body reads:
190
+ read the row through fields (row.total, $.for(row.lines, …)), not bound whole ($.let(row));
191
+ a runner's -v says "paged loops: N segments decoded to the fields read, M in full"
189
192
  ```
190
193
 
191
194
  ## Types and their values
@@ -20,7 +20,7 @@ reads any container version its type was written in.
20
20
  | **Collections larger than memory** (v5) |
21
21
  | `new Beast2ElementWriter(T, sink, opts?)` | The canonical writer: `.add(element)` one Array/Set element or Dict `[key, value]` — Set elements and Dict keys strictly ascending in East order — and the content-defined cut rule places the segments, so the bytes are a function of the value, identical from east-c and east-py, and a one-row edit re-cuts only the segments around it. Memory is one segment; `.finish()` writes the last, the terminator and the index. `sink` is `(bytes) => void`, or `{ segment(s) }` for one standalone segment blob at a time (`s`: `{ count, fence, logicalBytes, blob }`, under `writer.header`) |
22
22
  | `encodeBeast2PagedFor(T)(value)` | One value in memory through the element writer; plain `Map`/`Set` inputs are sorted first |
23
- | `new Beast2RunSorter(T, openRun, { merge } \| { union })` | Elements in ANY order in, sorted canonical runs out (a key added twice folds with `merge(key, acc, value)`, or `union` for a Set; without one it throws); then `mergeBeast2For(T, { merge } \| { union })(runs, sink)` writes the value. Memory is one run, then one segment per run. A run closes at `RUN_MAX_COUNT` elements or `RUN_MAX_BYTES`, platform constants, so every runtime writes the same runs |
23
+ | `new Beast2RunSorter(T, openRun, { merge } \| { union })` | Elements in ANY order in, sorted canonical runs out (a key added twice folds with `merge(key, acc, value)`, or `union` for a Set; without one it throws); then `mergeBeast2For(T, { merge } \| { union })(runs, sink)` writes the value. Memory is one run, then one segment per run. A run closes at `RUN_MAX_COUNT` elements or `RUN_MAX_BYTES`, platform constants, so every runtime writes the same runs. A fold whose values do not grow — `merge` over a bounded value type (Null, Boolean, Integer, Float, DateTime, Structs and Variants of those), or `union` — folds each key's values as they are added, in a table of at most `FOLD_TABLE_MAX_KEYS` keys and `FOLD_TABLE_MAX_KEY_BYTES` that spills into the open run, so few keys make one small run |
24
24
  | `mergeBeast2For(T, opts?)(sources, sink)` | Sorted collections — blobs, range readers or manifests — into their union's blob or manifest, segment by segment; a key several hold folds in input order; `opts.from` / `opts.to` merge a key range |
25
25
  | `recutBeast2For(T)(pieces, sink)` | A collection in pieces, some already written, into its canonical segments: a segment the whole shares with its piece is carried unread (`sink.carried`), the rest re-cut (`sink.written`) |
26
26
  | `intakeBeast2For(T)(delivery, sink, opts?)` | A collection from outside — a `Beast2SyncRangeReader` over a v4 or v5 blob whose header names exactly `T` — through the Writer into a `Beast2ManifestSink`, a segment at a time: each row is walked by its type, the Writer's own bytes go on as they stand, and any other row is decoded and written again. `opts.segments` takes in the index's segments `[from, to)`, a piece of a large delivery. Refuses another type, a malformed segment or one over `RUN_MAX_BYTES`, a row that does not decode, and keys that do not ascend, with `Beast2IntakeError` in the words every runner uses. What e3's intake units run, on every runner |
@@ -69,3 +69,12 @@ openBeast2PagesFor(Rows)(blob).element(4_000_000); // one row: decodes ONE segm
69
69
  `$.for` cost one segment, mutation is refused (`.copy()` first), and the
70
70
  header type is checked against `T` first. `East.Blob.encodeBeast` writes no
71
71
  index, so a paged blob comes from the writers above or a runner's output.
72
+ - **A `$.for` over a lazy input decodes each segment to the fields its body
73
+ reads** of each row — an Array's element, a Dict's value — on every runtime:
74
+ read through field accesses (`row.total`, `row.address.city`), inner loops
75
+ over its arrays and dicts (`$.for(row.lines, …)`), their sizes, and functions
76
+ called on the row or its fields. Binding the row (`$.let(row)`), putting it in
77
+ a container or passing it to a function value decodes every field, as does a
78
+ Set's loop. Every runner's `-v` says `paged loops: N segments decoded to the
79
+ fields read, M in full`; in process, `beast2PagedLoopStats()` counts
80
+ them. The bytes are read either way: a dropped field is only not built.
@@ -22,6 +22,18 @@ const revenue = East.function([ArrayType(Order)], FloatType, ($, orders) =>
22
22
  East.jq({ orders }, ".orders | map(.total) | add", FloatType));
23
23
  ```
24
24
 
25
+ A stage that collects rows before a step that reads them one at a time —
26
+ `map(f) | add`, `| length`, `| any`, `| first`, `| .[:n]`, a `reduce` over
27
+ `.[]` — runs as one loop, so the array between them is never built; `first`
28
+ and `.[:n]` stop the stage once they have their rows, unless a later row could
29
+ raise (QUERY.md §15.1–15.2).
30
+
31
+ A row a stage builds or keeps holds only the fields the steps after it read:
32
+ `map(. + {region: …}) | group_by(.region) | map(… .total …)` builds each row of
33
+ its region and total, and over an e3 root `map(select(p))` keeps each row as
34
+ the fields read after it, so a paged dataset decodes those alone. A row read
35
+ whole — the output, `keys`, `tojson`, `==` — is built whole (QUERY.md §15.1).
36
+
25
37
  | Signature | Description | Example |
26
38
  |-----------|-------------|---------|
27
39
  | **In an East body** |
@@ -32,7 +44,7 @@ const revenue = East.function([ArrayType(Order)], FloatType, ($, orders) =>
32
44
  | `printJq(program: JqNode, options?: { layout?: "line" \| "pipeline" }): PrintedJq` | A program's canonical text, and its nodes' spans; `pipeline` puts each top-level stage on a line of its own | `printJq(checked.program!).text` |
33
45
  | `translateJq(checked: CheckJqResult, options?: { maxOutputs?: number, tooling?: boolean }): JqTranslation` **❗** | The translation: `fn()`, an East function of the inputs the query reads (`inputs`), and its `resultType` | `East.compile(translateJq(checked).fn(), [])` |
34
46
  | `evaluateJq(program: string \| CheckJqResult, input: unknown, options?: { inputType?, root?, tooling?, platform? }): unknown` **❗** | Checks, translates, compiles (cached) and runs a query over a TypeScript value. Throws `QueryError`: the checker's diagnostics, or one `runtime` diagnostic at the node that raised | `evaluateJq("[.[] \| .id]", orders, { inputType: ArrayType(Order) })` |
35
- | `splitJq(checked: CheckJqResult, options?: { maxOutputs?: number }): JqSplit` | A query checked as an e3 root, split over one dataset's pieces for an e3 split call: `piece()` each piece runs, the `output` kind its outputs combine by (`array`, `set`, `dict` with `merge()`, `fold` with `zero` and `combine()`), and `then()` over the result; or, `kind: "whole"`, why it runs as one unit. QUERY.md §17.1 | `splitJq(checkJq(".orders \| group_by(.region) \| map(length)", Root, { root: true })).output.kind` |
47
+ | `splitJq(checked: CheckJqResult, options?: { maxOutputs?: number }): JqSplit` | A query checked as an e3 root, split over one dataset's pieces for an e3 split call: `piece()` each piece runs, the `output` kind its outputs combine by (`array`, `set`, `dict` with `merge()`, `fold` with `zero` and `combine()`, or `first` with its `limit`, a stream's first rows in input order for `first(f)` and `limit(n; f)`), and `then()` over the result; or, `kind: "whole"`, why it runs as one unit. QUERY.md §17.1 | `splitJq(checkJq(".orders \| group_by(.region) \| map(length)", Root, { root: true })).output.kind` |
36
48
 
37
49
  - **The values are East's.** A Dict is an object keyed by its key type, so
38
50
  `.byId[1035]` looks up an Integer key; a variant reads as `{type, value}`,