@elaraai/east-codex-plugin 1.0.102 → 1.0.104

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.102",
3
+ "version": "1.0.104",
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)
@@ -70,13 +70,15 @@ What do you need?
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
72
  │ ├─ A named function (RPC) → e3.function(name, fn, config?) — called by name, persists nothing
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
@@ -384,6 +386,7 @@ const change = e3.streamTask('change', {
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
388
  | `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>`). |
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. |
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. |
@@ -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 waiting → .cancel() (client-side; server still finishes)
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.
@@ -311,6 +318,14 @@ result-size limit; long compute belongs in dataflow tasks and
311
318
  `status()`, `error()` and `pending()`. All handles bound to one function share
312
319
  one channel, so one component can launch while another shows the spinner.
313
320
 
321
+ A function that declares `inputs` (`e3.function(name, { inputs, args, output },
322
+ fn)`, the **e3** skill) is bound the same way: its handle's `call` takes the
323
+ `args` alone, and each call reads the inputs from the workspace as they are
324
+ stored when it launches. The page binds none of them; an optimiser's eye
325
+ (`optimise={Func.bind(fn)}`) passes its request as the one argument while the
326
+ function reads its reference data as inputs. `e3-ui:func.examples.tsx:funcBindInputs`
327
+ is the example.
328
+
314
329
  ```tsx
315
330
  <Reactive>{$ => {
316
331
  const forecast = $.let(Func.bind(forecastFn)); // e3.function('forecast', East.function([IntegerType, FloatType], FloatType, …))
@@ -358,6 +373,18 @@ and `<Schematic>` share one contract:
358
373
  - **The app's optimiser**: `optimise={Func.bind(fn)}`, an `e3.function` from
359
374
  the builder's `Types.OptimiseRequest` to its `Types.OptimiseResult`; its
360
375
  answer lands as one undoable step.
376
+ - **Which views an instance offers**: a component that switches between views
377
+ takes `views` — the Roster's, Calendar's and Allocation's layouts, the
378
+ Ontology's display modes and `<Query.Builder>`'s
379
+ Visual · jq (and `resultViews`, Table · Tree). Literal tags (`views={["people"]}`),
380
+ variants of its `Types`, or an expression of an array of them, so a page's state
381
+ can choose them as it runs. Left out, or empty as the page runs, every view; one
382
+ left, no switch shows in any form of the toolbar; the component's own order
383
+ stands. `e3-ui:roster.examples.tsx:rosterViews` wires a multi-select into it.
384
+ `<DecisionQueue>`'s `facets` is the same.
385
+ - **Which periods an instance offers**: `viewPeriods` on `<Roster>` and
386
+ `<Calendar>` does the same for Day · Week · Month. (A Plan's are its axis's
387
+ `resolutions`.)
361
388
  - **Misuse is refused at build**, naming the change — forms from earlier
362
389
  releases included — so read the error rather than guessing.
363
390
 
@@ -368,7 +395,7 @@ and `<Schematic>` share one contract:
368
395
  | `<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
396
  | `<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
397
  | `<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` |
398
+ | `<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
399
  | `<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
400
 
374
401
  Field types matter: a `Sheet.column.quantity` sits on a `Float` field, a
@@ -377,16 +404,9 @@ start and end are `Option<DateTime>` when it can wait in the backlog.
377
404
 
378
405
  ## Other surfaces
379
406
 
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
407
+ - **`<Ontology value={view} />`** edits a typed node / link graph
408
+ (`OntologyType`), committing through the binding. The **east-ontology** skill
383
409
  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
410
  - **The Decide loop.** Reasoning tasks emit `Array<Decision.Types.Decision>`
391
411
  (`Decision.make` / `option` / `reference` / `judgement`).
392
412
  `Decision.bind([Contract]?, { decisions: [views…], judgements })` unions them
@@ -442,10 +462,9 @@ in; dates print in UTC.
442
462
  <VStack gap="3">
443
463
  <Slider value={value} min={0} max={100} onChange={t.write} />
444
464
  <HStack gap="2">
445
- <Button variant="outline" onClick={discard}>Discard</Button>
446
- <Button variant="solid" onClick={commit}>Apply</Button>
465
+ <Button variant="outline" onClick={discard} disabled={t.pending().not()}>Discard</Button>
466
+ <Button variant="solid" onClick={commit} disabled={t.pending().not()}>Apply</Button>
447
467
  </HStack>
448
- <Diff bindings={[t.binding]} />
449
468
  </VStack>
450
469
  );
451
470
  }}</Reactive>
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: east-ontology
3
- description: "Build an Economic Ontology of a business and render it with the e3-ui Ontology editor. Use when: (1) Modelling how a business creates value as a graph of resources, activities, KPIs, decisions, objectives, policies, data/systems ('map our supply chain', 'build an ontology', 'model the business', 'create a digital twin', 'what should we optimize or automate', 'where is the value created'), (2) Running an ontology-elicitation workshop and turning the captured activity table into nodes + links, (3) Encoding that graph as an `OntologyType` e3.input and surfacing it via `Ontology.Root` with staged commit/discard + Diff, (4) Using the ontology to identify high-value, decision-improving AI / optimization initiatives."
3
+ description: "Build an Economic Ontology of a business and render it with the e3-ui Ontology editor. Use when: (1) Modelling how a business creates value as a graph of resources, activities, KPIs, decisions, objectives, policies, data/systems ('map our supply chain', 'build an ontology', 'model the business', 'create a digital twin', 'what should we optimize or automate', 'where is the value created'), (2) Running an ontology-elicitation workshop and turning the captured activity table into nodes + links, (3) Encoding that graph as an `OntologyType` e3.input and surfacing it via `Ontology.Root` with staged commit/discard, (4) Using the ontology to identify high-value, decision-improving AI / optimization initiatives."
4
4
  ---
5
5
 
6
6
  # Economic Ontology
@@ -135,22 +135,22 @@ const ontology = e3.input('supply_chain', OntologyType, variant('value', {
135
135
  const editor = East.function([], UIComponentType, (_$) =>
136
136
  Reactive.Root(East.function([], UIComponentType, $ => {
137
137
  const view = $.let(Data.bind(ontology));
138
- return Ontology.Root({ binding: view.binding });
138
+ return Ontology.Root({ value: view });
139
139
  })),
140
140
  );
141
141
  ```
142
142
 
143
143
  ### `Ontology.Root` options
144
144
 
145
- `Ontology.Root({ value, ... })` — only `value` is required (pass the `Data.bind` handle over an `OntologyType` dataset). Options: `readonly` (hide mutation surfaces; commit-bar + drawer still render), `hideMiniMap`, `hideSearch`, `density` (`'comfortable'` | `'compact'` | `'condensed'`), `defaultView` (`'graph'` | `'table'` — the header's segmented control switches at runtime either way), `onCommitted` / `onDiscarded`, `style` (per-surface colour escape hatches — see `OntologyStyleType`).
145
+ `Ontology.Root({ value, ... })` — only `value` is required (pass the `Data.bind` handle over an `OntologyType` dataset). Options: `readonly` (hide mutation surfaces; the property drawer still renders), `hideMiniMap`, `hideSearch`, `density` (`'comfortable'` | `'compact'` | `'condensed'`), `defaultView` (`'graph'` | `'table'` — the header's segmented control switches at runtime either way), `onCommitted` / `onDiscarded`, `style` (per-surface colour escape hatches — see `OntologyStyleType`).
146
146
 
147
147
  ### The table view
148
148
 
149
149
  The editor's header has a segmented `Graph | Table` control. The table is a value-driver-tree projection of the same bound value: rows are `process` nodes **grouped by the objective they serve** (via KPI `drives` paths), ordered by **value-chain stage** (topological order of `uses`/`produces` resource flow, with cycles — e.g. cash → materials → goods → cash — condensed, sharing a stage, and flagged ↺). Each row shows uses/produces/KPIs/data/**decisions**/policies plus owning agents; expanding a row reveals what feeds it and what it feeds (with the carrying resources) and completeness warnings (no inputs, no outputs, no KPI, no decision). Hovering any chip highlights every occurrence of that node across the table.
150
150
 
151
- ### Edit modes, commit, and Diff
151
+ ### Edit modes and commit
152
152
 
153
- The editor uses the same staged-buffer machinery as `Diff`. `Data.bind(dataset)` **without `mode`** stages edits — the footer commit-bar applies or discards them, and you can stack a `Diff.Root({ bindings: [view.binding] })` beside the editor to review the pending node/link patch before commit. Pass `{ mode: 'direct' }` to write each mutation straight back instead (good for read-mostly demos). For a locked view, `readonly: some(true)`.
153
+ Every edit goes through the binding. `Data.bind(dataset)` **without `mode`** is direct: each edit is written straight to the dataset. Bind `{ mode: 'staged' }` to hold edits until they are applied: while a change waits the editor's header shows *Unsaved changes* with **Discard** and **Apply**, which drop or commit it (`onDiscarded` / `onCommitted` fire after). A page can do the same through the handle's `commit()` / `discard()`. For a locked view, `readonly: some(true)`.
154
154
 
155
155
  ## Validation
156
156
 
@@ -165,7 +165,7 @@ The graph exists to find the decisions worth improving. For each `decision` node
165
165
 
166
166
  ## Related skills
167
167
 
168
- - **e3-ui** — the `Ontology`, `Data.bind`, and `Diff` API this builds on (and `ui()` to ship the editor as an e3 task).
168
+ - **e3-ui** — the `Ontology` and `Data.bind` API this builds on (and `ui()` to ship the editor as an e3 task).
169
169
  - **east-ui** — layout (`Card`, `Stack`) for composing the editor into a dashboard.
170
170
  - **east-design** — turn the prioritised decisions into an implementation plan.
171
171
  - **east-py-datascience** — the optimization / ML that improves a targeted decision.
@@ -176,6 +176,5 @@ The graph exists to find the decisions worth improving. For each `decision` node
176
176
  Ground the encoding in real graphs via `search_east_examples`:
177
177
  - `Ontology supply-chain process kpi objective` — a full activity/resource/KPI graph
178
178
  - `Ontology governance policy decision document` — policy/decision/document-heavy graph
179
- - `Ontology Diff review pending patch` — editor + Diff panel for staged commits
180
179
  - `Ontology readonly viewer` — locked, mutation-free view
181
180
  - `Ontology density compact` — density presets