@elaraai/east-codex-plugin 1.0.106 → 1.0.108

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.106",
3
+ "version": "1.0.108",
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",
@@ -85,6 +85,8 @@ What do you need?
85
85
  │ └─ Bundle and export → e3.package(name, version, ...items); e3.export(pkg, zipPath)
86
86
  ├─ Operate it from the shell → the e3 CLI (reference/cli.md): deploy, run, read and write datasets, mutate records, gc
87
87
  ├─ Delegate local task bodies to a rack → e3 rack enroll + policy; dataflow run --rack, watch --start --rack (reference/rack.md)
88
+ │ ├─ A split task's pieces fill the rack → booked by what each reserves, capped half as much again; --memory-limit bounds the cap, --gpu asks for the GPU
89
+ │ └─ A task with its own python/node environment → nothing new in the package: its layers are built for the rack's platform
88
90
  └─ Drive it from code
89
91
  ├─ A server, over HTTP → @elaraai/e3-api-client (reference/from-code.md)
90
92
  ├─ A local repository → @elaraai/e3-core
@@ -236,6 +238,10 @@ const shout = e3.task('shout', [greet.output],
236
238
  derivation: `{ python: { project } }`, `{ node: { project } }`,
237
239
  `{ tools: { files: [...] } }` (prebuilt binaries on PATH, such as a C runner)
238
240
  or `{ image: { digest: 'repo@sha256:<64 hex>' } }` (cloud; a tag is refused).
241
+ A task with a `python` or `node` environment also runs on a rack
242
+ (`e3 dataflow run --rack`): the launching machine installs the environment
243
+ for the rack's platform and sends it as layers, with no container runtime;
244
+ `tools` and `image` environments stay local there (reference/rack.md).
239
245
 
240
246
  ```python
241
247
  # packages/pricing/src/pricing/__init__.py — the member's root module
@@ -518,7 +524,7 @@ Read the one a task needs; each holds its subject whole.
518
524
  | [reference/cli.md](reference/cli.md) | Every `e3` command: repositories, packages, workspaces, datasets, tasks, runs, calls, records, watch, convert, auth, gc |
519
525
  | [reference/from-code.md](reference/from-code.md) | `@elaraai/e3-api-client`, `@elaraai/e3-core`, `e3-api-server` |
520
526
  | [reference/browser.md](reference/browser.md) | `@elaraai/e3-web`: serveUnits, serveE3, createWebE3, and what a browser cannot do |
521
- | [reference/rack.md](reference/rack.md) | `e3 rack enroll` / `policy`, routing a run to a rack, `@elaraai/e3-rack` |
527
+ | [reference/rack.md](reference/rack.md) | `e3 rack enroll` / `policy`, routing a run to a rack, how a rack is filled and what a run prints, tasks with an environment on a rack, `@elaraai/e3-rack` |
522
528
  | [reference/repository.md](reference/repository.md) | A local repository's layout, and upgrades |
523
529
 
524
530
  ## Related skills
@@ -7,13 +7,13 @@ Part of the `e3` skill.
7
7
  | Signature | Description | Example |
8
8
  | --- | --- | --- |
9
9
  | `e3 rack enroll --listen <host:port> [--allow <ip,...>] [--advertise-url <origin>] [--label <label>] [--no-wait]` | Starts the user-wide hub and prints the source origin, the hub's certificate SHA-256, the matching release and a single-use token for the companion's hidden prompts. Waits for a new registration, not activation. Behind an SSH reverse tunnel, listen on the loopback and advertise the relay's origin. | `e3 rack enroll --listen 127.0.0.1:7331 --allow 127.0.0.1 --advertise-url https://relay.example:7401` |
10
- | `e3 rack policy [repo] set <glob> rack\|local [--size <size>] [--timeout <min>] [--allow-host-access]` | First whole-task-name match wins; `*` and `?` are wildcards. Size: serverless, small, medium, large, xlarge. | `e3 rack policy . set 'train_*' rack --size large` |
10
+ | `e3 rack policy [repo] set <glob> rack\|local [--size <size>] [--memory-limit <size>] [--gpu] [--timeout <min>] [--allow-host-access]` | First whole-task-name match wins; `*` and `?` are wildcards; setting a rule again replaces it whole. Size: serverless (2 cores, 2 GiB), small (2, 4 GiB), medium (4, 8 GiB), large (8, 16 GiB), xlarge (16, 32 GiB). `--memory-limit 8G` is a ceiling on one piece's cap, never a request; `--gpu` asks for a rack's GPU. | `e3 rack policy . set 'train_*' rack --size large` |
11
11
  | `e3 rack policy [repo] enable\|disable\|mode <opt-in\|auto>` | Enable/disable saved opt-in; `mode auto` selects eligible unmatched tasks. Defaults: disabled, opt-in. | `e3 rack policy . enable` |
12
12
  | `e3 rack policy [repo] defaults [--no-spill] [--claim-timeout <sec>] [--retry-task-failures-locally]` | Defaults: large, 1440-minute timeout, spill on, 30-second claim recheck, no task-failure retry. | `e3 rack policy . defaults --no-spill` |
13
13
  | `e3 rack policy [repo] show\|unset <glob>\|reset` | Inspect rules, remove an exact pattern, or delete the saved policy. | `e3 rack policy . show` |
14
- | `e3 dataflow run <repo> <ws> --rack\|--no-rack\|--rack-only` | Select rack routing for this run; rack-only disables capacity spill but keeps infrastructure fallback. ❗ Refused for remote URLs. | `e3 dataflow run . dev --rack` |
14
+ | `e3 dataflow run <repo> <ws> --rack\|--no-rack\|--rack-only` | Select rack routing for this run; rack-only disables capacity spill but keeps infrastructure fallback: work waits two minutes for an unhealthy rack to come back, and is leased once more after a failed transfer, before it runs locally. ❗ Refused for remote URLs. | `e3 dataflow run . dev --rack` |
15
15
  | `e3 watch <source> <repo> <ws> --start --rack` | Reuses a rack session across watch runs and refreshes capacity; a second Ctrl-C stops the watch at once. ❗ `--rack` and `--rack-only` require `--start`. | `e3 watch src/main.ts . dev --start --rack` |
16
- | `e3 rack status\|list\|remove <id-or-label>\|approve <id-or-label>\|stop` | Inspect fleet, revoke a rack, admit the boot a quarantined rack last reported, or stop the shared hub. Status never starts an absent hub. | `e3 rack status` |
16
+ | `e3 rack status\|list\|remove <id-or-label>\|approve <id-or-label>\|stop` | Inspect fleet, revoke a rack, admit the boot a quarantined rack last reported, or stop the shared hub. Status never starts an absent hub, and lists how its last leases ended, each with its reason. | `e3 rack status` |
17
17
  | `e3 rack config [--listen <host:port>] [--allow <ip,...>] [--idle-exit <min>] [--advertise-url <origin>] [--tls\|--no-tls] [--require-approval\|--no-require-approval]` | Configure the shared listener (off by default; HTTPS with the hub's own certificate unless `--no-tls`); every rack and data URL is built on `--advertise-url` when set; zero idle-exit disables automatic shutdown; `--require-approval` quarantines a rack after each reboot until `e3 rack approve` admits it (enrollment admits the first boot). ❗ Plain HTTP only on the loopback or a private address, with `--allow`. | `e3 rack config --listen 10.0.0.5:7331` |
18
18
 
19
19
  The local process owns graph planning, repository and cache. After a cache
@@ -21,10 +21,60 @@ miss, eligible plain task, map and merge bodies can execute on the rack; input
21
21
  closures and every output object transfer by hash. The session verifies the
22
22
  whole output graph before success. Placement never changes task/cache hashes.
23
23
  Local bodies and fallback share the original cores/memory budget; rack bodies
24
- use remote capacity. Calls, mutations and intake stay local. Stock runner
25
- configurations qualify; commands, custom environments/platforms and unscannable
26
- IR stay local. Host file/environment/network access stays local unless a rule
27
- deliberately grants `--allow-host-access` and its resources exist on the rack.
24
+ use remote capacity: each lease asks its cores, what it reserves and its cap
25
+ (a split task's piece one core, reserving what it was measured to need, capped
26
+ half as much again; a task its size's cores, at most the most a rack has,
27
+ reserving its cap, its `--memory-limit`, else its size's memory), a rack is given only what its free
28
+ resources hold by what each lease reserves, and only work whose cap all its
29
+ memory holds, and a run is as much wider as the racks have cores. `e3 rack list` shows each rack's resources and what is free. A run prints `[RACK] <task> → <rack>` when a rack claims a
30
+ task, `[RACK] <task> input transfer retried (2 of 5): <cause>` for a transfer
31
+ given another try, `[LOCAL] <task> (<reason>)` for a rack's work this machine
32
+ runs after all (`spill`, `no-rack-for-tier:<tier>`, or the rack's reason, such
33
+ as `input-transfer-failed: <cause>` or `guest-crashed: <detail>`, or
34
+ `memory-limit-exceeded: needs 3 GB, limit 2 GB` for work whose cap passes its
35
+ rule's limit or every rack's memory),
36
+ `[RACK] <task> waiting: needs 1 core and 4 GB, <rack> has 0 cores and 1 GB
37
+ free` for work queued with no rack having room for what it reserves,
38
+ `[RACK] <task> outgrew its 3 GB cap on <rack>: runs again under 4.5 GB` for a
39
+ split task's piece its rack stopped at its cap (a whole task fails instead:
40
+ `memory-limit-exceeded (cap 16 GB); raise --memory-limit or --size`),
41
+ `[RACK] <task> stopped on <rack> at 2.6 GB, its host short of memory: runs
42
+ again reserving 2.6 GB` for a piece a rack stopped to keep its host from
43
+ running out, as a local run's guard stops one, and ends
44
+ with `Rack summary: 1 task and 12 units on <rack> · 0 waited for capacity · 0
45
+ ran again · 1 transfer retried · 0 ran locally` (each task or unit once,
46
+ though it was leased again). On a rack that admits by
47
+ its resources a split task's pieces are queued together, booked by what each
48
+ reserves, and the rack's guard keeps them from running its host out of memory;
49
+ a first run's piece reserves e3's estimate, as a local run does, so it is as
50
+ wide as a later run and measures no piece first. Calls, mutations and intake stay local. Stock runner
51
+ configurations qualify, and so does a task that declares a `python` or `node`
52
+ environment, with the project platform packages its runner names; commands, a
53
+ platform package with no environment (`non-stock-platform:<name>`) and
54
+ unscannable IR stay local. Host file/environment/network access stays local
55
+ unless a rule deliberately grants `--allow-host-access` and its resources exist
56
+ on the rack.
57
+
58
+ **A task that declares an environment** needs nothing new in its package. On a
59
+ rack whose agent composes environments (`environments` among its features in
60
+ `e3 rack list`; `Rack: <rack> (…, environments for x86_64-manylinux_2_28)` as
61
+ a run starts), the launching machine installs the environment a second time
62
+ for the rack's platform, with the same frozen installs, packs it as layers the
63
+ rack fetches through the hub, and prints `[ENV] 3f9a2b1c0d4e for
64
+ x86_64-manylinux_2_28: building` then `[ENV] 3f9a2b1c0d4e built in 48 s: 4
65
+ layers, 2.1 GB (1 new)`. No container runtime on either machine; nothing is
66
+ compiled for the rack; a second run builds nothing, and a change to the
67
+ project's code makes one small new layer. The layers are kept in the
68
+ repository's `rack/env-layers`, which `e3 repo gc` sweeps. ❗ What cannot go
69
+ stays local, with its reason on the task's `[LOCAL]` line: `environment:tools`
70
+ / `environment:image` (its kind), `environment:windows-host` (a Windows
71
+ launching machine), `no-rack-for-environment:<tier>` (no rack composes them),
72
+ `environment:no-wheel:<package>` and `environment:native-package:<package>`
73
+ (nothing is compiled for another platform), `environment:pnpm` (a pnpm before
74
+ 11, for another platform), `environment:build-failed` (the tool's message is
75
+ in `e3 task logs`; a watch's next run builds it again). A task's tier is its runner's; `--gpu` puts an `east-py`
76
+ task on `py-datascience`, and is refused for another runner
77
+ (`gpu-not-east-py`).
28
78
 
29
79
  The listener serves HTTPS with the hub's own self-signed certificate, made on
30
80
  first use and kept in `hub-tls.beast2`; a rack pins it by its SHA-256, which
@@ -118,7 +168,14 @@ run waits up to 10 seconds for an enrolled rack to report healthy (with none
118
168
  enrolled, or a policy that selects no task for a rack, it starts at once): run
119
169
  `e3 rack hub` as a service, or set `--idle-exit 0`, for a hub racks can always
120
170
  reach. A data URL lasts 15 minutes, which a transfer may use whole; an object is
121
- at most 5 GiB. The control schema currently requires protocol 2 exactly.
171
+ at most 5 GiB. The hub serves one rack eight transfers at once (one more is told
172
+ to ask again), and reads an object from a byte on (`Range`), so a transfer a slow
173
+ link cut short resumes; it keeps a rack's idle connection for 75 seconds.
174
+ A hub and the e3 that calls it speak control protocol 3 exactly:
175
+ a hub an older e3 started is asked to exit once idle, and `e3 rack stop` with
176
+ that e3 replaces it now. A rack's agent and its source speak rack protocol 3:
177
+ an agent of another protocol is refused by name each time it asks, and
178
+ `e3 rack list` shows its rack as `incompatible: …; update the rack` until it is.
122
179
  Agents must report bundled e3 at least the project's release. Infrastructure
123
180
  failure falls back locally with a separate execution attempt, as does an
124
181
  attempt the rack stopped on its own; the run's own cancellation and the task's
@@ -129,11 +186,11 @@ sessions of the same canonical repository and e3 release.
129
186
 
130
187
  | Signature | Description | Example |
131
188
  | --- | --- | --- |
132
- | `openRackRunner({ repoPath, workspace, storage, label, budget?, settings?, policy?, rackOnly? })` | Opens a runner/session; preserve the caller's existing budget and process settings, use `rackSlots` to extend orchestrator width, and close in `finally`. | `const rack = await openRackRunner({ repoPath, workspace: 'dev', storage, label: 'run', budget });` |
189
+ | `openRackRunner({ repoPath, workspace, storage, label, budget?, settings?, policy?, rackOnly?, unreachableWaitMs?, onPlacement?, onEnvironment? })` | Opens a runner/session; preserve the caller's existing budget and process settings, use `rackSlots` to extend orchestrator width, and close in `finally`. Under `rackOnly`, work waits `unreachableWaitMs` (two minutes) for an unhealthy rack before it runs locally. `onPlacement` is told where each task or unit runs; `onEnvironment` that an environment's layers are being built for a rack, and what the build came to. | `const rack = await openRackRunner({ repoPath, workspace: 'dev', storage, label: 'run', budget });` |
133
190
  | `createDataflowRunnerFactory(options?)` | Pass to `createServer({ dataflowRunner })`; one session per API dataflow, using the server's shared budget. Explicit server opt-in overrides policy.enabled; rules still apply. | `const server = await createServer({ reposDir: './repos', dataflowRunner: createDataflowRunnerFactory() });` |
134
191
 
135
192
  The API server's optional rack package is needed only for
136
193
  `e3-api-server --repos ./repos --rack`. Portable handlers receive a runner
137
- factory and do not import hub code. Custom environments, remote function
138
- delegation, automatic reconnect after hub restart and embedded UI integration
139
- are deferred.
194
+ factory and do not import hub code. `tools` and `image` environments on a
195
+ rack, remote function delegation, automatic reconnect after hub restart and
196
+ embedded UI integration are deferred.
@@ -18,6 +18,7 @@ repo/
18
18
  ├── locks/ # locks, their holders, and how far each says it has got
19
19
  ├── gc/ # gc beside running work: unreachable notes, a stepped run's parts
20
20
  ├── envs/ # built execution environments
21
+ ├── rack/ # rack delegation: its policy, and the layers kept of environments built for a rack
21
22
  └── tmp/ # scratch and staged uploads
22
23
  ```
23
24
 
@@ -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 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."
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, the Record table over a system of records, 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
@@ -13,7 +13,7 @@ commit / discard, a view is where a user commits a decision with its evidence.
13
13
 
14
14
  Everything comes from one import, `@elaraai/e3-ui`: the `ui()` task factory, the
15
15
  bindings (`Data`, `Record`, `Func`, `Decision`, `Slice.bindRecords`), the e3
16
- tags (`<Ontology>`, `<Plan>`, `<Sheet>`, `<Calendar>`,
16
+ tags (`<Ontology>`, `<Plan>`, `<Sheet>`, `<Record>`, `<Calendar>`,
17
17
  `<Roster>`, `<Allocation>`, `<Flowchart>`, `<Schematic>`, `<DecisionQueue>`,
18
18
  `<DecisionJournal>`) and the `Studio` and `Query` components. Base tags
19
19
  (`<VStack>`, `<Text>`, `<Stat>`, …) come from `@elaraai/east-ui`.
@@ -160,7 +160,6 @@ Task → What do you need?
160
160
  │ ├─ Drags of templates, backlog cards and events → built in with resources + events (+ library); canDrop={fn(Schedule.Types.Candidate) => Option<String>}
161
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 })
162
162
  │ ├─ Overlap warnings, without dropping overlapping events → Schedule.events(record, { overlaps: "warn" | "allow" })
163
- │ ├─ Save each changed event kind through its patch door → applyMode="batch" (default); "auto" commits each ready gesture
164
163
  │ └─ Dropped cards and moves of data rows as drafts → a series' edit + editing={{ onUpdate | onApply }}
165
164
  │
166
165
  ├─ Let planners type rows in place — the Sheet
@@ -178,6 +177,17 @@ Task → What do you need?
178
177
  │ ├─ 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
178
  │ └─ Drafts checked as they are made, one checked Save → onUpdate | onApply, ready, newRow
180
179
  │
180
+ ├─ Keep a system of records — people, skills, certificates — the Record
181
+ │ ├─ A record's rows, each field a typed cell → <Record record={Record.bind(r)} columns={{ name: Record.column.title(R, {…}), … }} />
182
+ │ ├─ Click-stepped states, two words, a checkbox → Record.column.cycle(R, register, { scale? }) · toggle(R, { on, off }) · boolean(R, {…})
183
+ │ ├─ A variant's cases, stepped in their order → Record.column.cycle(R, Variant, { steps: [{ case, label, tone? }] })
184
+ │ ├─ Who, and the row's last change → Record.column.person(R, register, {…}) · audit(R, { mode }) on a Record.Types.Change field
185
+ │ ├─ Time since a moment, to the viewer's clock → days_since: Record.column.age(R, { since, unit?, stale? }), keyed by a name no field has
186
+ │ ├─ Column groups over adjacent columns → columnGroups={[{ label, columnKeys }]}
187
+ │ ├─ Columns from data: a member's each, a struct field's → any kind's { each: "<register>", groups?: "<register>" } over a Dict keyed by the member · { each: { field: "Header" } } · a field stored its own way: field, read, write, each given the day
188
+ │ ├─ Words or a lock on a cell; a cell read off the row → mark: (…, day) → Option<Record.Types.Mark>, a note or a lock the grid won't edit · value: (row) => … on title, text, date, quantity, integer
189
+ │ └─ Narrow it — one rail — and Apply through the door → slice={{ slice: Slice.bindRecords(key, { rows }) }} + onApply={Record.onApply(record, { keyed: true })}
190
+ │
181
191
  ├─ Schedule bound records on a calendar — the Calendar
182
192
  │ ├─ Event records, with their backlog → <Calendar events={{ job: Calendar.events(Record.bind(jobs), { name, icon, title, start, end, resource: { field, of }, entries, backlog }) }} />
183
193
  │ ├─ Resources and templates, read whole → resources={{ machines: Calendar.resources(Data.bind(r).read(), {…}) }} · Calendar.templates(rows, {…})
@@ -188,6 +198,7 @@ Task → What do you need?
188
198
  ├─ Draw a state-transition flow over the app's records — the Flowchart
189
199
  │ ├─ 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
200
  │ ├─ Editable, or read only → Record.bind(record) · Data.bind(record) (lanes and decisions: small records, read whole)
201
+ │ ├─ Records keyed by any type a Dict takes → a field naming a kind's row holds that kind's key type, checked at build · a new row's key: the kind's key: (row) => … builds it from the row; without one, a String's is made up, an Integer's one past the largest, and any other's typed in the inspector before Save — an editable transition kind keyed so needs key
191
202
  │ ├─ 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
203
  │ ├─ What a narrowing leaves out: gone, or faded → narrowed="hide" (the default) · narrowed="dim"
193
204
  │ ├─ 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)
@@ -198,7 +209,7 @@ Task → What do you need?
198
209
  │ ├─ 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
210
  │ ├─ An author's card dropped onto any kind's row → Flowchart.library.tab(rows, { …, drop: (r) => Flowchart.patch(R, { … }) })
200
211
  │ ├─ 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>}
212
+ │ ├─ What the host hears, and the connect veto → onSelectState · onSelectLink · onSelectTrigger · onTracePath (⌥-click) · canConnect={fn → Option<String>}, each key as its text
202
213
  │ ├─ Top down, a minimap, no legend, read only → orientation="TD" · minimap · legend={false} · readOnly
203
214
  │ ├─ 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
215
  │ └─ 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
@@ -206,6 +217,8 @@ Task → What do you need?
206
217
  ├─ Draw the app's records at world coordinates — a floor, a site — the Schematic
207
218
  │ ├─ A kind per record, under its slot → <Schematic extent={{ width, height }} items={{ racks: Schematic.items(record, { name, icon, x, y, label, … }) }} zones={{ … }} links={{ … }} nets={{ … }} />
208
219
  │ ├─ Editable, or read only → Record.bind(record) · Data.bind(record)
220
+ │ ├─ Records keyed by any type a Dict takes → as the Flowchart's, new keys too — an item's typed, a link kind's or a net kind's key; a link's end and a net's side hold their items' key type, a variant's each case its slot's
221
+ │ ├─ A link or net drawn with no template: its fields → the kind's values: (ends) => ({ … }), over Schematic.Types.Ends (a net's, Sides)
209
222
  │ ├─ Narrow its kinds and templates — one rail → slice={{ slice: Slice.bindRecords(key, { <a kind's slot>: { source: Data.bindPaged(record, { indexes }) }, … }) }} (+ the kind's entries: Data.bindPaged(record))
210
223
  │ ├─ A floor too large to read whole: a window at a time → its source lists index.area({ x, y, width, height, at: "centre", cell }); past 5,000 rows in view, their density
211
224
  │ ├─ Shapes from the row's own fields → footprint: (u) => some(Schematic.circle(u.radius)) · a zone's geometry: (a) => some(Schematic.polygon(a.corners))
@@ -215,34 +228,43 @@ Task → What do you need?
215
228
  │ ├─ The app's own words for what it draws → vocabulary={{ templates, backlog, index, layer, zone, net, link, source, destination }}
216
229
  │ ├─ An author's card dropped onto an entity → Schematic.library.tab(rows, { …, drop: (r) => Schematic.patch(R, { … }) })
217
230
  │ ├─ The inspector, a kind's form and its own Details → inspector · Schematic.items(record, { …, fields?, ready?, inspector? })
218
- │ └─ What the host hears, and the connect veto → onSelect={fn(Array<Schematic.Types.Ref>)} · canConnect={fn(Schematic.Types.Candidate) → Option<String>}
231
+ │ └─ What the host hears, and the connect veto → onSelect={fn(Array<Schematic.Types.Ref>)} · canConnect={fn(Schematic.Types.Candidate) → Option<String>}, each key as its text
219
232
  │
220
233
  ├─ Staff a week's shifts from the app's own duties — the Roster
221
234
  │ ├─ The duties: the app's record, a span kind → events={{ duty: Schedule.events(Record.bind(duties), { start, end, resource: { field, of }, shift, group, position?, activity?, hours? }) }}
235
+ │ ├─ Duties in no group yet: a roster in two steps → group over an Option<String> field, none a duty in no group — on its person's row in People and in Shifts' No group band, counted in their hours, contract and rest and in no group's targets; a drop in a group's slot writes some(group), the optimiser's request and result carry none · in a check, a duty's place (Roster.Types.Place) and Roster.slotOf(place), none in no group · vocabulary={{ noGroup }}
222
236
  │ ├─ Who is rostered → resources={{ people: Schedule.resources(staff.read(), { name, icon, label, group, … }), agencies? }}
223
237
  │ ├─ The lists it reads, over the app's rows → Roster.shifts / groups / positions / activities / proposals(rows, { … })
224
238
  │ ├─ Publish, and the targets: the app's weeks and cover → periods={Schedule.periods(Record.bind(weeks), { every: "week", status, dismissed? })} · targets={Roster.targets(Record.bind(cover), { day, group, shift, positions, hours })}
239
+ │ ├─ Publish a day at a time: the app's days → periods={Schedule.periods(Record.bind(days), { every: "day", status, dismissed?, entries? })} — in Shifts' Day, Publish day writes the day in view; else Publish week, each day of the week that takes edits, as one request; a published day read-only in every layout and period while its week's other days take edits, a rejected proposal kept on its day's row
240
+ │ ├─ A new duty's, target's and week's own fields → values: (d) => ({ … }) on the duty kind, over Roster.Types.NewDuty · Roster.targets(…, { values }) · Schedule.periods(…, { values })
225
241
  │ ├─ Costs in the app's own pay codes → pay={fn(Roster.Types.PayRequest(R)) → Roster.Types.Pay} currency="…"
226
242
  │ ├─ Who fits a Find fix: the app's fit, on e3 → fit={Func.bind(e3.function)} from Roster.Types.FitRequest(R) to FitResult, over Roster.answer(R) + Roster.fit(R)
227
243
  │ ├─ The app's optimiser over the week → optimise={Func.bind(e3.function)} from Roster.Types.OptimiseRequest(R) to Roster.Types.OptimiseResult(R)
244
+ │ ├─ An optimiser that sees the week's edges → Roster.Types.OptimiseRequest(R, { edges: true }) to OptimiseResult(R, { edges: true }) — edges: the window's duties the Roster places in another week, drafts in place; fixed: those of a week that takes no edit, left as they are; an answer that changes a fixed duty, puts one in a week taking no edit or beyond the weeks either side, or gives a key twice is refused, naming the duty
228
245
  │ ├─ Narrow its duties, targets, people, activities, patterns → slice={{ slice: Slice.bindRecords(key, { duty: { source, range: "start" }, targets?, people?, activities?, patterns? }) }}
246
+ │ ├─ The app's check, and a record it reads beside the duties → check={fn(Roster.Types.CheckContext(R)) → Array<Roster.Types.Issue>} · the first step's rota as the slice's reference: { duty, reference: { source, range: "start" } }, check from CheckContext(R, P) — cx.reference: Dict<String, P>, the week's rows and 12 h either side, read through its interval index, never whole; nothing draws it, the rail offers none of it
229
247
  │ ├─ People by week or by month → view={{ layout: "people", period: "week" | "month", date }}
248
+ │ ├─ People in one list, no band over each group → peopleBands={false} — ranked as a group's people are (leads, the rest, agency staff), every group's agency requests one row at its foot; a person keeps their home group for + Assign, a Find, the fit and the optimiser
249
+ │ ├─ The cover targets over People by week or month → on with targets: under each band its work requirement — a lane a shift its targets name, each day's hours rostered (requests included) of needed over a bar, by month a mark a day on the person marks' columns (short, requested, covered or no target), a lane opening to its skill rows, a day or a mark opening its slot in the inspector; one block over every group with peopleBands={false}; deep in a band's people its block stays under the header; on a phone a card a day before each band's people's cards, a line a shift · requirements={false} takes it away
230
250
  │ ├─ 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 })
251
+ │ ├─ The app's own words for who is on it → vocabulary={{ permanent: "Employees", agency: "Contractors", agencyShort: "contr", others: "Colleagues", requests: "Contractor requests", demand: "Hours needed" }} — agencyShort the agency badge in People and on a Shifts chip, requests its rows of agency requests, demand the People layout's work requirement; a fit's reason: Roster.fit(R, { notALead })
232
252
  │ ├─ The shifts' colours, and the app's week patterns → Roster.shifts(rows, { …, color }) · patterns={Roster.patterns(rows, {…})} · library={[…, Roster.library.patterns()]}
233
253
  │ └─ The week's figures in a task → Roster.coverage / check / weekHours / rest (R)
234
254
  │
235
255
  ├─ Book a day's arrivals into lane slots, each bin on its resources — the Allocation
236
256
  │ ├─ The bins: the app's record, an instant kind → events={{ bin: Schedule.events(Record.bind(bins), { at, resource: { field, of: "<lanes>" }, arrival, quantity: { field, unit }, parts: { field, of: "<resources>" }, hold, kind? }) }}
257
+ │ ├─ A reservation's own fields → the bin kind's values: (b) => ({ … }), over Allocation.Types.NewBin; a booked bin takes its arrival's values
237
258
  │ ├─ The lanes and the resources → resources={{ <lanes>: Schedule.resources(rows, { name, icon, label, offset? }), <resources>: Schedule.resources(rows, { name, icon, label, min, max, … }) }}
238
259
  │ ├─ What it books from → arrivals={Allocation.arrivals(rows, { label, quantity, hold, kind?, values?, … })}
239
- │ ├─ Publish: the app's days → periods={Schedule.periods(Record.bind(days), { every: "day", status })}
260
+ │ ├─ Publish: the app's days, or its weeks → periods={Schedule.periods(Record.bind(days), { every: "day", status })} · or its weeks, { every: "week", … }, each keyed by its first day, week={{ start: "monday" | "sunday" }} — Publish week writes the week holding the day in view, and every day of a published week is read-only
240
261
  │ ├─ Who fits where: the app's fit, on e3 → fit={Func.bind(e3.function)} from Allocation.Types.FitRequest(R) to FitResult, over Allocation.answer(R) + Allocation.fit (+ Allocation.lookahead(R))
241
262
  │ ├─ The app's optimiser over the day → optimise={Func.bind(e3.function)} from Allocation.Types.OptimiseRequest(R) to Allocation.Types.OptimiseResult(R)
242
263
  │ ├─ Narrow its bins, lanes, resources and arrivals — one rail → slice={{ slice: Slice.bindRecords(key, { bin: { source, range: "at" }, <lanes>?, <resources>?, arrivals? }) }}
243
264
  │ ├─ Its panes → library={[Allocation.library.arrivals(), Allocation.library.resources()]} · inspector
244
265
  │ ├─ 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 } }}
245
266
  │ ├─ The app's bin fields on the board, and its own issues → columns={[{ key, label, text }]} · check={fn(CheckContext(R)) → Array<Issue>}
267
+ │ ├─ A record the check reads beside the bins → the slice's reference: { bin, …, reference: { source, range } }, check from CheckContext(R, P) — cx.reference: Dict<String, P>, the day's rows, read through its interval index, never whole; nothing draws it
246
268
  │ └─ The board's figures in a task → Allocation.loads / candidates / check / slots (R)
247
269
  │
248
270
  ├─ Render deployed surfaces in a React app (@elaraai/e3-ui-components)
@@ -261,9 +283,8 @@ datasets in `inputs` (their values passed to `fn`), every dataset, record and
261
283
  paged source the body binds, and every `Func.bind`. `fn` returns
262
284
  `UIComponentType` exactly. It runs on `east-c` by default; where only the Node
263
285
  runner is installed, pass `{ runner: { runtime: "east-node" } }` as
264
- `options`. Bindings
265
- take the def itself (`e3.input`, `e3.task`, `e3.record`, `e3.function`), so the
266
- path and type are fixed when the IR is built.
286
+ `options`. Bindings take the def itself (`e3.input`, `e3.task`, `e3.record`,
287
+ `e3.function`), so the path and type are fixed when the IR is built.
267
288
 
268
289
  ### `Data.bind(dataset, options?)`
269
290
 
@@ -329,38 +350,29 @@ fn)`, the **e3** skill) is bound the same way: its handle's `call` takes the
329
350
  `args` alone, and each call reads the inputs from the workspace as they are
330
351
  stored when it launches. The page binds none of them; an optimiser's eye
331
352
  (`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.
334
-
335
- ```tsx
336
- <Reactive>{$ => {
337
- const forecast = $.let(Func.bind(forecastFn)); // e3.function('forecast', East.function([IntegerType, FloatType], FloatType, …))
338
- const run = $.const(East.function([], NullType, $ => { $(forecast.call(12n, 1.05)); }));
339
- return (
340
- <VStack gap="3">
341
- <Button onClick={run} loading={forecast.pending()}>Run forecast</Button>
342
- <Stat label="Forecast" value={East.print(forecast.read())} />
343
- </VStack>
344
- );
345
- }}</Reactive>
346
- ```
353
+ function reads its reference data as inputs. `e3-ui:func.examples.tsx:funcBindCall`
354
+ launches a call from a button and shows its result;
355
+ `e3-ui:func.examples.tsx:funcBindInputs` binds a function that declares inputs.
347
356
 
348
357
  ## The builders
349
358
 
350
- `<Plan>`, `<Sheet>`, `<Calendar>`, `<Roster>`, `<Allocation>`, `<Flowchart>`
351
- and `<Schematic>` share one contract:
359
+ `<Plan>`, `<Sheet>`, `<Record>`, `<Calendar>`, `<Roster>`, `<Allocation>`,
360
+ `<Flowchart>` and `<Schematic>` share one contract:
352
361
 
353
362
  - **Data is the app's own records.** Each builder maps roles onto the app's
354
- fields (`title: "title", start: "start", resource: { field, of }`) and
355
- stores nothing in a shape of its own. Editable data is
363
+ fields (`title: "title"` or a function of the row, `start: "start"`,
364
+ `resource: { field, of }`) and stores nothing of its own. Editable data is
356
365
  `Record.bind(record)` over a record declaring `mutation.patch()`.
357
366
  `Schedule.events` / `resources` / `templates` / `periods` are the shared
358
367
  vocabulary for kinds of events and resources (Plan, Calendar, Roster,
359
368
  Allocation).
360
369
  - **Every gesture is a draft.** Drags, drops, typed cells and form edits are
361
- steps of one editing session with Undo / Redo, saved with one checked Save
362
- through each record's patch door (or the host's `onApply`). Drafts survive
363
- paging, narrowing and remount.
370
+ steps of one session with Undo / Redo, saved with one checked Save through
371
+ each record's patch door (or the host's `onApply`), surviving paging,
372
+ narrowing and remount. While a kind's `ready` refuses a draft, Save waits:
373
+ the entry's panel shows the refusal over its form, the field ringed, an
374
+ Issues tab lists it, and the history's warning button selects the entry.
375
+ Save's menu holds Autosave, off unless `autosave` (a Boolean) begins it on.
364
376
  - **It renders in its own frame**: one toolbar, the canvas, a footer, and the
365
377
  panes its props ask for (`library`, `inspector`). Give it a box with a height.
366
378
  - **One rail narrows it**: `slice={{ slice: Slice.bindRecords(key, { … }) }}`,
@@ -398,15 +410,17 @@ and `<Schematic>` share one contract:
398
410
  |---|---|---|
399
411
  | `<Plan>` | Heterogeneous rows on one time / number / ordinal axis: series over data, event kinds over records, read-only rows | `e3-ui:plan-events.examples.tsx:planEvents` (smallest), `e3-ui:plan.examples.tsx:planTargetState`, `e3-ui:plan-windows.examples.tsx:planWindows`, `e3-ui:plan-records.examples.tsx:planRecordIndexes` |
400
412
  | `<Sheet>` | A planning spreadsheet over a record, the host's rows or a paged source: typed columns, registers, groups, copilot, Excel round-trip | `e3-ui:sheet.examples.tsx:sheetBasic` (smallest), `e3-ui:sheet.examples.tsx:sheetWorkshop`, `e3-ui:sheet.examples.tsx:sheetPaged`, `e3-ui:sheet-records.examples.tsx:sheetRecordIndexes` |
413
+ | `<Record>` | A system of records' rows as a table: the Sheet's kinds with title, person, boolean, toggle, cycle, age and audit; column groups, columns from data, marks and locks, Add and Delete | `e3-ui:record.examples.tsx:recordBasic` (smallest), `e3-ui:record.examples.tsx:recordSkillsMatrix`, `e3-ui:record.examples.tsx:recordEveryKind`, `e3-ui:record.examples.tsx:recordFinishes`, `e3-ui:record.examples.tsx:recordHoursByProject` (columns from data), `e3-ui:record.examples.tsx:recordSkillHistory` (a dated history, read and written at the day) |
401
414
  | `<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` |
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` |
415
+ | `<Roster>` | Weekly staffing: duties over people by shift, cover targets, pay, fit, publish, duties in no group yet | `e3-ui:roster.examples.tsx:rosterMinimal` (smallest), `e3-ui:roster.examples.tsx:rosterWarehouse`, `e3-ui:roster.examples.tsx:rosterPeople`, `e3-ui:roster.examples.tsx:rosterNoGroup` (in two steps) |
403
416
  | `<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` |
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` |
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` |
417
+ | `<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`, `e3-ui:flowchart.examples.tsx:flowchartBakery` |
418
+ | `<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`, `e3-ui:schematic.examples.tsx:schematicBakehouse` |
406
419
 
407
420
  Field types matter: a `Sheet.column.quantity` sits on a `Float` field, a
408
421
  `Sheet.column.date` on a `DateTime`, each `Option` of it allowed; an event's
409
- start and end are `Option<DateTime>` when it can wait in the backlog.
422
+ start and end are `Option<DateTime>` when it can wait in the backlog. A
423
+ `Record.Types.Change` field is the solution's to write; the Record only reads it.
410
424
 
411
425
  ## Other surfaces
412
426
 
@@ -449,13 +463,10 @@ A deployed `ui()` task renders in a React app through
449
463
  requests reach it, `<ReactiveDatasetProvider>` inside it installs the bindings'
450
464
  adapters, and `<UITaskPreview task="…">` fetches and renders a task's output.
451
465
 
452
- | `E3Config` | Meaning |
453
- |---|---|
454
- | `apiUrl` | **required** — the e3 API's base URL |
455
- | `repo` | the repository; `"default"` when omitted |
456
- | `workspace` | the workspace the bindings read and write |
457
- | `token` | a bearer token, or `null`; read afresh for every request |
458
- | `fetch` | the `fetch` requests go through; for an e3 running in the page, the one `createWebE3` gives (e3-web, the **e3** skill) |
466
+ `E3Config` names the e3: `apiUrl` (**required**), `repo` (`"default"` when
467
+ omitted), `workspace`, `token` (a bearer token or `null`, read afresh for every
468
+ request) and `fetch` — for an e3 running in the page, the one `createWebE3`
469
+ gives (e3-web, the **e3** skill).
459
470
 
460
471
  `E3Provider` also takes a `queryClient` to share a TanStack Query cache. Wrap
461
472
  the app in `<I18nProvider locale="…">` (re-exported from
@@ -464,47 +475,17 @@ in; dates print in UTC.
464
475
 
465
476
  ## Key Patterns
466
477
 
467
- ### Staged commit / discard
468
-
469
- ```tsx
470
- <Reactive>{$ => {
471
- const t = $.let(Data.bind(threshold, { mode: 'staged' }));
472
- const value = $.let(t.read());
473
- const commit = $.const(East.function([], NullType, $ => { $(t.commit()); }));
474
- const discard = $.const(East.function([], NullType, $ => { $(t.discard()); }));
475
- return (
476
- <VStack gap="3">
477
- <Slider value={value} min={0} max={100} onChange={t.write} />
478
- <HStack gap="2">
479
- <Button variant="outline" onClick={discard} disabled={t.pending().not()}>Discard</Button>
480
- <Button variant="solid" onClick={commit} disabled={t.pending().not()}>Apply</Button>
481
- </HStack>
482
- </VStack>
483
- );
484
- }}</Reactive>
485
- ```
486
-
487
- ### A record's mutation from a button
488
-
489
- ```tsx
490
- <Reactive>{$ => {
491
- const r = $.let(Record.bind(counter, ["increment"]));
492
- const bump = $.const(East.function([], NullType, $ => { $(r.mutate.increment(1n)); }));
493
- return (
494
- <VStack gap="2">
495
- <Stat label="Counter" value={East.print(r.read())} />
496
- <Button onClick={bump} loading={r.mutate.pending()}>Increment</Button>
497
- <Text>{r.mutate.status().getTag()}</Text>
498
- </VStack>
499
- );
500
- }}</Reactive>
501
- ```
502
-
503
- ### Disable controls on stale data
504
-
505
- ```tsx
506
- <Slider value={t.read()} onChangeEnd={t.writeAndStart} disabled={t.status().hasTag('stale')} />
507
- ```
478
+ - **Staged commit / discard**: `Data.bind(d, { mode: 'staged' })`, with Apply
479
+ calling `commit()` and Discard `discard()`, both off until `pending()`:
480
+ `e3-ui:data.examples.tsx:dataBindStagedVariants`.
481
+ - **A record's mutation from a button**: `Record.bind(r, ["increment"])`, the
482
+ button applying `r.mutate.increment(1n)` with `loading={r.mutate.pending()}`:
483
+ `e3-ui:record.examples.tsx:recordBindMutate`.
484
+ - **Disable controls on stale data**:
485
+
486
+ ```tsx
487
+ <Slider value={t.read()} onChangeEnd={t.writeAndStart} disabled={t.status().hasTag('stale')} />
488
+ ```
508
489
 
509
490
  ## Related skills
510
491
 
@@ -372,7 +372,12 @@ layout container given `density`. An explicit `density` on a component wins.
372
372
  - **Fields**: `Fields.specs(R, hints?, omit?)` turns a struct into an
373
373
  inspector's typed form, each field's editor from its East type, a hint
374
374
  (`Fields.number`, `Fields.select`, `Fields.reference`, …) adding what the
375
- type cannot say.
375
+ type cannot say. A variant whose cases hold data is a choice, the fields of
376
+ the case it holds in a block under it, each case's value hinted through the
377
+ select's `cases` (`Fields.select({ cases: { sliced: Fields.number({ min: 1n }) } })`).
378
+ A reference holds a key of any type a Dict may be keyed by: the host's
379
+ choices are keyed by its text — a String as itself, any other as East
380
+ prints it — and the one chosen is read back at the field's type.
376
381
  - **Drag and drop**: a `<Library>` is a source; a target (`<Blend>`, e3-ui's
377
382
  builders) lists its `id` in `sources`. Every drag reduces to one
378
383
  `DragEventType` (`add`, `move`, `remove`, `resize`), and a target's