@elaraai/east-codex-plugin 0.0.0-stage → 1.0.90
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/.build/daemon/east-py-lsp.js +568 -0
- package/.build/daemon/lsp.js +3737 -0
- package/.build/daemon/server.js +3535 -0
- package/.build/hooks/codex-tools.js +584 -0
- package/.build/hooks/diagnose-bash.js +399 -0
- package/.build/hooks/diagnose.js +347 -0
- package/.build/hooks/pre-read.js +100 -0
- package/.build/hooks/pre-write.js +247 -0
- package/.build/hooks/session-start.js +263 -0
- package/.build/hooks/subagent-start.js +212 -0
- package/.build/mcp/server.js +23577 -0
- package/.build/status/report.js +2163 -0
- package/.codex-plugin/plugin.json +36 -0
- package/.lsp.json +21 -0
- package/.mcp.json +11 -0
- package/LICENSE.md +682 -0
- package/README.md +192 -2
- package/hooks/hooks.json +51 -0
- package/index.json +44926 -0
- package/package.json +36 -4
- package/skills/e3/SKILL.md +841 -0
- package/skills/e3-create/SKILL.md +265 -0
- package/skills/e3-ui/SKILL.md +2260 -0
- package/skills/e3-ui-cli/SKILL.md +332 -0
- package/skills/east/SKILL.md +690 -0
- package/skills/east-contribute/SKILL.md +348 -0
- package/skills/east-design/SKILL.md +233 -0
- package/skills/east-node-io/SKILL.md +143 -0
- package/skills/east-node-std/SKILL.md +289 -0
- package/skills/east-ontology/SKILL.md +181 -0
- package/skills/east-project/SKILL.md +189 -0
- package/skills/east-py/SKILL.md +2023 -0
- package/skills/east-py-datascience/SKILL.md +280 -0
- package/skills/east-py-io/SKILL.md +186 -0
- package/skills/east-py-std/SKILL.md +301 -0
- package/skills/east-ui/SKILL.md +1529 -0
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: east-node-io
|
|
3
|
+
description: "I/O platform functions for the East language on Node.js. Use when writing East programs that need SQL databases (SQLite, PostgreSQL, MySQL, Access), NoSQL databases (Redis, MongoDB), S3 storage, file transfers (FTP, SFTP), file format parsing (XLSX, XML), or compression (Gzip, Zip, Tar). Triggers for: (1) Writing East programs with @elaraai/east-node-io, (2) Database operations with SQL.SQLite, SQL.Postgres, SQL.MySQL, SQL.Access, NoSQL.Redis, NoSQL.MongoDB, (3) Cloud storage with Storage.S3, (4) File transfers with Transfer.FTP, Transfer.SFTP, (5) Format parsing with Format.XLSX, Format.XML, (6) Compression with Compression.Gzip, Compression.Zip, Compression.Tar."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# East Node IO
|
|
7
|
+
|
|
8
|
+
I/O platform functions for East on Node.js: databases, object storage, file
|
|
9
|
+
transfers, spreadsheet and XML formats, and compression. Each module is a set
|
|
10
|
+
of platform declarations an East function calls, with its implementation in
|
|
11
|
+
`Module.Implementation`; the same functions, under the same platform names,
|
|
12
|
+
are implemented on the python runtime (**east-py-io**).
|
|
13
|
+
|
|
14
|
+
Nearly all of them are **async** — the databases, S3, transfers, Gzip and Tar
|
|
15
|
+
(XLSX, XML and Zip are sync) — so a function calling them is an
|
|
16
|
+
`East.asyncFunction`, compiled with `East.compileAsync` and awaited. A sync
|
|
17
|
+
`East.function` calling one is refused at compile: `Async platform call not
|
|
18
|
+
allowed outside async function`.
|
|
19
|
+
|
|
20
|
+
## Before writing code — search the example index
|
|
21
|
+
|
|
22
|
+
Every East API has a tested example in the plugin's index — the index IS the
|
|
23
|
+
API reference, printed from each example's IR in TypeScript or python. Before
|
|
24
|
+
writing or changing East code:
|
|
25
|
+
|
|
26
|
+
1. Call `search_east_examples` for each capability you
|
|
27
|
+
are about to use — `language: "python"` for east-py, `"typescript"`
|
|
28
|
+
otherwise. Summaries come back first: id, signature, the inputs and the
|
|
29
|
+
expected result, a few hundred bytes each.
|
|
30
|
+
2. Fetch the one or two that match with `get_east_example`
|
|
31
|
+
and pattern your code on them.
|
|
32
|
+
3. Do not read `node_modules/@elaraai/**` or `*.examples.ts` files wholesale,
|
|
33
|
+
and do not reason from `.d.ts` signatures: the index holds the same
|
|
34
|
+
programs, exact and far cheaper, and the signatures omit the runtime rules
|
|
35
|
+
that make East code correct.
|
|
36
|
+
|
|
37
|
+
Nothing is injected for you; the search is the step.
|
|
38
|
+
|
|
39
|
+
## Quick Start
|
|
40
|
+
|
|
41
|
+
```typescript
|
|
42
|
+
import { East, StringType, NullType, none, variant } from "@elaraai/east";
|
|
43
|
+
import { SQL } from "@elaraai/east-node-io";
|
|
44
|
+
import { Env, EnvImpl } from "@elaraai/east-node-std";
|
|
45
|
+
|
|
46
|
+
const queryUser = East.asyncFunction([StringType], NullType, ($, userId) => {
|
|
47
|
+
const config = $.let({
|
|
48
|
+
host: "localhost", port: 5432n, database: "myapp", user: "postgres",
|
|
49
|
+
password: Env.get("PGPASSWORD").unwrap(), // from the environment, never a literal
|
|
50
|
+
ssl: none, maxConnections: none,
|
|
51
|
+
});
|
|
52
|
+
const conn = $.let(SQL.Postgres.connect(config));
|
|
53
|
+
$(SQL.Postgres.query(conn, "SELECT * FROM users WHERE id = $1", [variant("String", userId)]));
|
|
54
|
+
$(SQL.Postgres.close(conn));
|
|
55
|
+
});
|
|
56
|
+
|
|
57
|
+
const compiled = East.compileAsync(queryUser, [...SQL.Postgres.Implementation, ...EnvImpl]);
|
|
58
|
+
await compiled("user123");
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Decision Tree: Which Module to Use
|
|
62
|
+
|
|
63
|
+
```
|
|
64
|
+
Task → What do you need?
|
|
65
|
+
│
|
|
66
|
+
├─ SQL Database — .connect(config) → a handle · .close(handle) · .closeAll()
|
|
67
|
+
│ ├─ SQL.SQLite (embedded, placeholder ?) · SQL.Postgres ($1, $2, …) · SQL.MySQL (?)
|
|
68
|
+
│ │ ├─ .query(handle, sql, params) → Types.Result, a variant by statement kind
|
|
69
|
+
│ │ │ (select {rows} · insert {rowsAffected, lastInsertId} · update / delete {rowsAffected})
|
|
70
|
+
│ │ └─ .select([RowType], handle, sql, params) → Array<RowType> — the typed read; the type argument FIRST, in an array
|
|
71
|
+
│ │ (params: an Array of Types.Parameter — variant("String", s), variant("Integer", n), …)
|
|
72
|
+
│ └─ SQL.Access (read-only, .mdb / .accdb) → .open(config) · .tables(handle) · .query([RowType], handle, options) ·
|
|
73
|
+
│ .close() · .closeAll()
|
|
74
|
+
│
|
|
75
|
+
├─ NoSQL
|
|
76
|
+
│ ├─ NoSQL.Redis (key-value) → .connect() · .get(h, key) → Option<String> · .set(h, key, value) ·
|
|
77
|
+
│ │ .setex(h, key, value, seconds) · .delete(h, key) · .close() · .closeAll()
|
|
78
|
+
│ └─ NoSQL.MongoDB (documents) → .connect() · .insertOne(h, doc) · .findOne(h, filter) · .findMany(h, filter, options) ·
|
|
79
|
+
│ .updateOne(h, filter, update) · .deleteOne(h, filter) · .close()
|
|
80
|
+
│
|
|
81
|
+
├─ Storage.S3 (S3-compatible; each call takes the config, no connection)
|
|
82
|
+
│ └─ .putObject() · .getObject() · .headObject() · .deleteObject() · .listObjects() · .presignUrl()
|
|
83
|
+
│
|
|
84
|
+
├─ Transfer.FTP · Transfer.SFTP → .connect() · .put(h, path, blob) · .get(h, path) · .list(h, path) · .delete(h, path) · .close()
|
|
85
|
+
│
|
|
86
|
+
├─ Format (sync)
|
|
87
|
+
│ ├─ Format.XLSX → .read(blob, options) (a sheet: rows of cells) · .write(sheet, options) → Blob · .info(blob)
|
|
88
|
+
│ └─ Format.XML → .parse(blob, config) → a recursive Node · .serialize(node, config) → Blob
|
|
89
|
+
│
|
|
90
|
+
└─ Compression
|
|
91
|
+
├─ Compression.Gzip (one stream) → .compress(blob, options) · .decompress(blob)
|
|
92
|
+
├─ Compression.Zip (archive; sync) → .compress(entries, options) · .decompress(blob)
|
|
93
|
+
└─ Compression.Tar (archive) → .create(entries) · .extract(blob)
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## Compiling East Programs
|
|
97
|
+
|
|
98
|
+
```typescript
|
|
99
|
+
// One module
|
|
100
|
+
const compiled = East.compileAsync(myFunction, SQL.Postgres.Implementation);
|
|
101
|
+
|
|
102
|
+
// Several — each module's Implementation, spread together
|
|
103
|
+
const compiled2 = East.compileAsync(myFunction, [...SQL.Postgres.Implementation, ...Storage.S3.Implementation]);
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
The implementations are also exported flat (`PostgresImpl`, `S3Impl`,
|
|
107
|
+
`GzipImpl`, …).
|
|
108
|
+
|
|
109
|
+
## Accessing Types
|
|
110
|
+
|
|
111
|
+
```typescript
|
|
112
|
+
import { SQL, Storage, NoSQL, Format, Compression } from "@elaraai/east-node-io";
|
|
113
|
+
|
|
114
|
+
// Module.SubModule.Types.TypeName
|
|
115
|
+
SQL.Postgres.Types.Config // { host, port, database, user, password, ssl: Option, maxConnections: Option }
|
|
116
|
+
SQL.Postgres.Types.Result // and Parameter, Parameters, Row
|
|
117
|
+
Storage.S3.Types.Config // and ObjectMetadata, ListResult
|
|
118
|
+
NoSQL.Redis.Types.Config
|
|
119
|
+
NoSQL.MongoDB.Types.FindOptions // and Config, BsonValue, BsonDocument
|
|
120
|
+
Format.XLSX.Types.Sheet // and Cell, Row, ReadOptions, WriteOptions, SheetInfo, Info
|
|
121
|
+
Compression.Zip.Types.Entries // and Level, Options, Entry, Extracted
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
Option fields take `some(value)` / `none`; a config's secret comes from
|
|
125
|
+
`Env.get(...)` (**east-node-std**) — IR is content-addressed and replicated, so
|
|
126
|
+
a literal credential travels with it.
|
|
127
|
+
|
|
128
|
+
## Connection Pattern
|
|
129
|
+
|
|
130
|
+
```typescript
|
|
131
|
+
const conn = $.let(Module.connect(config)); // 1. connect: an opaque handle
|
|
132
|
+
$(Module.operation(conn, ...args)); // 2. operate
|
|
133
|
+
$(Module.close(conn)); // 3. close — handles are pooled per process
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
## Related skills
|
|
137
|
+
|
|
138
|
+
- **east** — the language these platform functions plug into; compile with `East.compileAsync`.
|
|
139
|
+
- **east-node-std** — Console / Env / FileSystem / Fetch / Crypto / Time basics (this package is the database, cloud and format layer on top).
|
|
140
|
+
- **east-py-io** — the same functions on the python runtime.
|
|
141
|
+
- **e3** — run ingest / sync as durable, cached dataflow tasks; pair with **east-ui** / **e3-ui** to surface the results.
|
|
142
|
+
- **east-project** — to author your OWN custom platform function (not just use these stock ones): `East.platform(...).implement(...)` exported from your package's `./platform`, called from an e3 task via `{ runtime: 'east-node', platforms: [{ custom: '@elaraai/<project>' }] }`.
|
|
143
|
+
- **e3-create** — scaffold that custom platform: `--platform` for one module, or `--node-packages=<name>` for a dedicated npm workspace member (its own auto-derived e3 environment).
|
|
@@ -0,0 +1,289 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: east-node-std
|
|
3
|
+
description: "Node.js platform functions for the East language. Use when writing East programs that need Console I/O, Environment variables, FileSystem operations, HTTP Fetch requests, Cryptography, Time operations, Path manipulation, Random number generation, reading large JSON documents, or Testing. Triggers for: (1) Writing East programs with @elaraai/east-node-std, (2) Using platform functions like Console.log, Env.get, FileSystem.readFile, Fetch.get, Crypto.uuid, Time.now, Path.join, Random.normal, (3) Testing East code with describeEast and Assert, (4) Passing credentials/secrets to East tasks without putting them in source, (5) Opening a beast2 collection file too big for memory lazily with FileSystem.openBeast (paged reads inside an East function, on every runtime), (6) Reading a JSON document too large to decode whole — ingesting a multi-gigabyte payload from another system — with Json.open / Json.more / Json.next, strictly against a published contract."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# East Node Standard Library
|
|
7
|
+
|
|
8
|
+
Node.js platform functions for the East language: console, environment,
|
|
9
|
+
filesystem, HTTP, crypto, time, path, random, large-JSON reading and testing.
|
|
10
|
+
Each module (`Console.log`, `FileSystem.readFile`, …) is a platform
|
|
11
|
+
declaration an East function calls, with its implementation in
|
|
12
|
+
`Module.Implementation`; the same functions, under the same platform names, are
|
|
13
|
+
implemented on the python runtime (**east-py-std**) and in C (`east-c-std`), so
|
|
14
|
+
a program using them runs on every runner.
|
|
15
|
+
|
|
16
|
+
## Before writing code — search the example index
|
|
17
|
+
|
|
18
|
+
Every East API has a tested example in the plugin's index — the index IS the
|
|
19
|
+
API reference, printed from each example's IR in TypeScript or python. Before
|
|
20
|
+
writing or changing East code:
|
|
21
|
+
|
|
22
|
+
1. Call `search_east_examples` for each capability you
|
|
23
|
+
are about to use — `language: "python"` for east-py, `"typescript"`
|
|
24
|
+
otherwise. Summaries come back first: id, signature, the inputs and the
|
|
25
|
+
expected result, a few hundred bytes each.
|
|
26
|
+
2. Fetch the one or two that match with `get_east_example`
|
|
27
|
+
and pattern your code on them.
|
|
28
|
+
3. Do not read `node_modules/@elaraai/**` or `*.examples.ts` files wholesale,
|
|
29
|
+
and do not reason from `.d.ts` signatures: the index holds the same
|
|
30
|
+
programs, exact and far cheaper, and the signatures omit the runtime rules
|
|
31
|
+
that make East code correct.
|
|
32
|
+
|
|
33
|
+
Nothing is injected for you; the search is the step.
|
|
34
|
+
|
|
35
|
+
## Quick Start
|
|
36
|
+
|
|
37
|
+
```typescript
|
|
38
|
+
import { East, StringType, NullType } from "@elaraai/east";
|
|
39
|
+
import { NodePlatform, Console, FileSystem } from "@elaraai/east-node-std";
|
|
40
|
+
|
|
41
|
+
const processFile = East.function([StringType], NullType, ($, path) => {
|
|
42
|
+
const content = $.let(FileSystem.readFile(path));
|
|
43
|
+
$(Console.log(content));
|
|
44
|
+
});
|
|
45
|
+
|
|
46
|
+
const compiled = East.compile(processFile, NodePlatform); // every module's implementation
|
|
47
|
+
compiled("input.txt");
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
`Fetch` and `Time.sleep` are ASYNC: a function calling them is an
|
|
51
|
+
`East.asyncFunction`, compiled with `East.compileAsync` and awaited.
|
|
52
|
+
|
|
53
|
+
## Decision Tree: Which Module to Use
|
|
54
|
+
|
|
55
|
+
```
|
|
56
|
+
Task → What do you need?
|
|
57
|
+
│
|
|
58
|
+
├─ Console (stdout/stderr output)
|
|
59
|
+
│ └─ .log(), .error(), .write()
|
|
60
|
+
│
|
|
61
|
+
├─ Env (environment variables — credentials/config supplied at runtime)
|
|
62
|
+
│ └─ .get(name) → Option<String> (some when set, none when not; never
|
|
63
|
+
│ write a credential literal — IR is content-addressed and replicated)
|
|
64
|
+
│
|
|
65
|
+
├─ FileSystem (read/write files and directories)
|
|
66
|
+
│ ├─ Text → .readFile(), .writeFile(), .appendFile()
|
|
67
|
+
│ ├─ Binary → .readFileBytes(), .writeFileBytes()
|
|
68
|
+
│ ├─ Huge beast2 collection file → .openBeast(T, path) — T is an ArrayType/SetType/DictType, passed FIRST; a frozen,
|
|
69
|
+
│ │ lazily paged value: size / get / has / $.for decode one segment (mapped on east-c and east-py, positioned reads on Node)
|
|
70
|
+
│ ├─ Query → .exists(), .isFile(), .isDirectory()
|
|
71
|
+
│ ├─ Directory → .createDirectory(), .readDirectory()
|
|
72
|
+
│ └─ Delete → .deleteFile()
|
|
73
|
+
│
|
|
74
|
+
├─ Json (read a JSON document too large to decode whole)
|
|
75
|
+
│ ├─ Open → .open(path, pointer) / .openText(text, pointer) → an opaque handle;
|
|
76
|
+
│ │ pointer is RFC 6901 ("" for the whole document, "/data" for an envelope's array)
|
|
77
|
+
│ ├─ Iterate → .more(handle) then .next(T, handle) — T FIRST, one element in flight
|
|
78
|
+
│ ├─ One subtree → .value(T, path, pointer) — for the small members beside a huge array
|
|
79
|
+
│ └─ Release → .close(handle)
|
|
80
|
+
│
|
|
81
|
+
├─ Fetch (HTTP; ASYNC) → .get(url) → String · .getBytes(url) → Blob · .post(url, body) → String ·
|
|
82
|
+
│ .request(Fetch.Types.RequestConfig{url, method: GET/POST/PUT/DELETE/PATCH/HEAD/OPTIONS, headers, body: Option})
|
|
83
|
+
│ → Fetch.Types.Response{status, statusText, headers, body, ok}
|
|
84
|
+
│
|
|
85
|
+
├─ Crypto → .uuid() · .randomBytes(n) → Blob · .hashSha256(text) → hex String · .hashSha256Bytes(blob) → Blob digest
|
|
86
|
+
│
|
|
87
|
+
├─ Time → .now() → Integer (Unix milliseconds) · .sleep(ms) (ASYNC) ·
|
|
88
|
+
│ .getTimezoneOffset(dt, zone) → Integer (minutes ahead of UTC for an IANA zone at that instant)
|
|
89
|
+
│
|
|
90
|
+
├─ Path → .join(parts: Array<String>) · .resolve(path) (absolute) · .dirname() · .basename() · .extname()
|
|
91
|
+
│
|
|
92
|
+
├─ Random (one stream; seed it for reproducibility)
|
|
93
|
+
│ ├─ Basic → .uniform() in [0, 1) · .normal() (N(0, 1)) · .range(min, max) → Integer in [min, max]
|
|
94
|
+
│ ├─ Continuous → .exponential(rate) · .weibull(shape) · .pareto(alpha) · .logNormal(mu, sigma)
|
|
95
|
+
│ ├─ Discrete (→ Integer) → .bernoulli(p) · .binomial(n, p) · .geometric(p) · .poisson(rate)
|
|
96
|
+
│ ├─ Composite → .irwinHall(n) (a sum of n uniforms) · .bates(n) (their mean)
|
|
97
|
+
│ └─ Control → .seed(n)
|
|
98
|
+
│
|
|
99
|
+
└─ Assert (testing with describeEast)
|
|
100
|
+
└─ .is(), .equal(), .notEqual(), .less(), .lessEqual(), .greater(), .greaterEqual(), .between(), .throws(), .fail()
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## Compiling East Programs
|
|
104
|
+
|
|
105
|
+
```typescript
|
|
106
|
+
East.compile(myFunction, NodePlatform); // every module
|
|
107
|
+
East.compile(myFunction, NodePlatformSync); // all but the async Fetch and Time.sleep
|
|
108
|
+
East.compile(myFunction, [...Console.Implementation, ...FileSystem.Implementation]); // just these
|
|
109
|
+
East.compileAsync(myAsyncFunction, NodePlatform); // an East.asyncFunction calling Fetch / Time.sleep
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
Each module's platform functions are also exported under their platform names
|
|
113
|
+
(`console_log`, `fs_read_file`, …), with each module's implementations as
|
|
114
|
+
`ConsoleImpl`, `FileSystemImpl`, ….
|
|
115
|
+
|
|
116
|
+
## Available Modules
|
|
117
|
+
|
|
118
|
+
| Module | Import | Purpose |
|
|
119
|
+
|--------|--------|---------|
|
|
120
|
+
| Console | `import { Console } from "@elaraai/east-node-std"` | stdout/stderr output |
|
|
121
|
+
| Env | `import { Env } from "@elaraai/east-node-std"` | Environment variables (runtime credentials/config; name in IR, value from the environment) |
|
|
122
|
+
| FileSystem | `import { FileSystem } from "@elaraai/east-node-std"` | Read/write files and directories |
|
|
123
|
+
| Json | `import { Json } from "@elaraai/east-node-std"` | Read a JSON document too large to decode whole, strictly |
|
|
124
|
+
| Fetch | `import { Fetch } from "@elaraai/east-node-std"` | HTTP requests |
|
|
125
|
+
| Crypto | `import { Crypto } from "@elaraai/east-node-std"` | Hashing, UUIDs, random bytes |
|
|
126
|
+
| Time | `import { Time } from "@elaraai/east-node-std"` | Timestamps and sleep |
|
|
127
|
+
| Path | `import { Path } from "@elaraai/east-node-std"` | Path manipulation |
|
|
128
|
+
| Random | `import { Random } from "@elaraai/east-node-std"` | Statistical distributions |
|
|
129
|
+
| Assert | `import { Assert, describeEast } from "@elaraai/east-node-std"` | Testing utilities |
|
|
130
|
+
|
|
131
|
+
## Accessing Types
|
|
132
|
+
|
|
133
|
+
```typescript
|
|
134
|
+
import { Fetch } from "@elaraai/east-node-std";
|
|
135
|
+
|
|
136
|
+
// Access types via Module.Types.TypeName (also exported as FetchMethod / FetchRequestConfig / FetchResponse)
|
|
137
|
+
const method = Fetch.Types.Method; // Variant<GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS>
|
|
138
|
+
const config = Fetch.Types.RequestConfig; // { url, method, headers: Dict<String, String>, body: Option<String> }
|
|
139
|
+
const response = Fetch.Types.Response; // { status, statusText, headers, body, ok }
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
## Key Patterns
|
|
143
|
+
|
|
144
|
+
### Open a huge beast2 collection file lazily
|
|
145
|
+
|
|
146
|
+
`FileSystem.openBeast(T, path)` is the file-backed twin of `blob.openBeast(T)`
|
|
147
|
+
(the **east** skill): the type comes first, the value is frozen, and only the
|
|
148
|
+
segments a program touches are ever decoded. It is a generic platform call
|
|
149
|
+
(`fs_open_beast<T>`) provided by the std family on every runtime, so an East
|
|
150
|
+
function using it runs unchanged on the east-node, east-c and east-py
|
|
151
|
+
runners — a python-authored function that calls it links into an east-c task.
|
|
152
|
+
|
|
153
|
+
```typescript
|
|
154
|
+
import { East, DictType, IntegerType, StringType, StructType } from "@elaraai/east";
|
|
155
|
+
import { FileSystem } from "@elaraai/east-node-std";
|
|
156
|
+
|
|
157
|
+
const TableType = DictType(IntegerType, StructType({ id: IntegerType, name: StringType }));
|
|
158
|
+
|
|
159
|
+
const total = East.function([StringType], IntegerType, ($, path) => {
|
|
160
|
+
const table = $.let(FileSystem.openBeast(TableType, path)); // reads the index, not the file
|
|
161
|
+
const sum = $.let(table.get(7n).id); // one segment decoded
|
|
162
|
+
$.for(table, ($, row) => { // one segment at a time
|
|
163
|
+
$.assign(sum, sum.add(row.id));
|
|
164
|
+
});
|
|
165
|
+
return sum;
|
|
166
|
+
});
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
- The file's header must carry exactly `T` — a mismatch is
|
|
170
|
+
`Failed to open beast file <path>: beast2: cannot open a blob of type <wire> as <T>`,
|
|
171
|
+
the same text on every runtime; a missing file is `Failed to open beast file <path>: ...`.
|
|
172
|
+
- The value is frozen: `insert` / `update` raise `cannot mutate a frozen value`;
|
|
173
|
+
`.copy()` gives a mutable copy (decoding the whole file).
|
|
174
|
+
- A file without a paging index — what `East.Blob.encodeBeast` writes — or an
|
|
175
|
+
element shape holding `Ref` or function values decodes whole, frozen, with
|
|
176
|
+
the same value. Paged files come from `encodeBeast2PagedFor`, `Beast2Writer`
|
|
177
|
+
and every runner's collection output.
|
|
178
|
+
- The value keeps its file open for as long as it lives (a descriptor on
|
|
179
|
+
Node, a read-only mapping on east-c and east-py): don't hold thousands of
|
|
180
|
+
opened files at once, and don't truncate or rewrite a file while a value
|
|
181
|
+
over it is alive — read it into a fresh value first.
|
|
182
|
+
- For bytes already in hand (a `BlobType` dataset, a `Fetch.getBytes` result)
|
|
183
|
+
use `blob.openBeast(T)` instead; for an e3 task input, do nothing — large
|
|
184
|
+
inputs already open lazily.
|
|
185
|
+
|
|
186
|
+
### Read a JSON document too large to decode whole
|
|
187
|
+
|
|
188
|
+
`Json.open` positions a reader on the array or object an RFC 6901 pointer
|
|
189
|
+
names; `Json.next(T, handle)` reads ONE element against `T`. The type comes
|
|
190
|
+
first, as it does for `FileSystem.openBeast`. One element is in flight at a
|
|
191
|
+
time whatever the document's size, so the natural home is an `e3.streamTask`
|
|
192
|
+
producer that emits as it reads.
|
|
193
|
+
|
|
194
|
+
```typescript
|
|
195
|
+
import { East, ArrayType, IntegerType, StringType, StructType } from "@elaraai/east";
|
|
196
|
+
import { Json } from "@elaraai/east-node-std";
|
|
197
|
+
|
|
198
|
+
const RowType = StructType({ id: IntegerType, name: StringType });
|
|
199
|
+
|
|
200
|
+
const total = East.function([StringType], IntegerType, ($, path) => {
|
|
201
|
+
const handle = $.let(Json.open(path, "/data")); // skips to the array; parses nothing before it
|
|
202
|
+
const sum = $.let(0n);
|
|
203
|
+
$.while(Json.more(handle), $ => {
|
|
204
|
+
$.assign(sum, sum.add(Json.next(RowType, handle).id));
|
|
205
|
+
});
|
|
206
|
+
$(Json.close(handle));
|
|
207
|
+
return sum;
|
|
208
|
+
});
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
- **`{"meta": {…}, "data": [10M rows]}` is the ordinary shape.** Never type the
|
|
212
|
+
whole document as one value — `StructType({ meta: …, data: ArrayType(RowType) })`
|
|
213
|
+
materialises the array however good the reader is. Point at the array, and
|
|
214
|
+
read the envelope separately with `Json.value(MetaType, path, "/meta")`;
|
|
215
|
+
a member AFTER the array costs a scan, not a parse.
|
|
216
|
+
- **It is strict.** It accepts exactly what `jsonSchemaFor(T)` describes, so a
|
|
217
|
+
producer validating against the published schema cannot send something that
|
|
218
|
+
is then rejected. An `Integer` must be a quoted decimal in i64 range: not
|
|
219
|
+
`"0x10"`, `"0b101"`, `" 7 "`, `"007"`, `"-0"`, nor a bare JSON number. A
|
|
220
|
+
`DateTime` is any RFC 3339 date-time — the schema's `format: "date-time"` —
|
|
221
|
+
with `Z` or any offset (read as the UTC instant), a `t` or `z` in either
|
|
222
|
+
case, any number of fractional digits (past the millisecond dropped) and a
|
|
223
|
+
leap second read as the Unix time its fields add up to; a day its month does
|
|
224
|
+
not have (`2026-02-30`) is refused rather than rolled forward, and so is an
|
|
225
|
+
instant outside years 0001–9999. `parseJson` reads a `DateTime` through the
|
|
226
|
+
same parser. A `Blob`'s hex must be lowercase, where `parseJson` also takes
|
|
227
|
+
uppercase.
|
|
228
|
+
- **An `Option<T>` is `null` or `T`'s own encoding** wherever `T` can never
|
|
229
|
+
itself encode as `null`: a row's `note: Option<String>` reads `none` from
|
|
230
|
+
`"note": null` and `some` from `"note": "x"`, and the tagged
|
|
231
|
+
`{"type": "some", "value": "x"}` object there is refused as the payload it
|
|
232
|
+
is not (`expected a String, got an object`). Only `Option<Null>` and
|
|
233
|
+
`Option<Option<T>>` keep the tagged object — what keeps `some(none)`
|
|
234
|
+
distinct from `none` — so a bare `null` there is refused
|
|
235
|
+
(`expected an object, got null`). The rule is the same on every runtime,
|
|
236
|
+
with nothing to configure, and `jsonSchemaFor` describes a flat Option as
|
|
237
|
+
`oneOf [null, T]`.
|
|
238
|
+
- **Errors name the offending node** by RFC 6901 pointer — an array element by
|
|
239
|
+
its index, an object member by its name (`~` and `/` escaped as `~0` / `~1`):
|
|
240
|
+
`json_next: /1/id: "not-an-integer" is not a 64-bit integer in East JSON's form`,
|
|
241
|
+
`json_next: /b~0~1c: "x" is not a 64-bit integer in East JSON's form`. A
|
|
242
|
+
quoted value is clipped at 200 characters, so a message never grows with
|
|
243
|
+
the document.
|
|
244
|
+
- **`more` is a predicate, `next` advances.** They need not alternate, and
|
|
245
|
+
asking `more` twice is harmless.
|
|
246
|
+
- **A JSON object iterates as entries**: pass a `Struct` of exactly `key` and
|
|
247
|
+
`value` (the key must be `String`), in either declared order, which is what
|
|
248
|
+
a `Dict` output needs. The entry type is checked at the container before
|
|
249
|
+
anything is consumed, so a refused call leaves the reader where it was.
|
|
250
|
+
- Handles are held until closed, as a database connection is. A body that can
|
|
251
|
+
fail mid-document should close in a `.catch` that re-raises — a `$.try` whose
|
|
252
|
+
`.catch` is left implicit swallows the error.
|
|
253
|
+
- The same six functions (`json_open`, `json_open_text`, `json_more`,
|
|
254
|
+
`json_next`, `json_value`, `json_close`) exist in `east-py-std` and
|
|
255
|
+
`east-c-std`, and **accept and reject exactly the same documents with
|
|
256
|
+
exactly the same message** — pointer and sentence alike, the property the
|
|
257
|
+
shared compliance corpus pins. `east-py-std` is east-c's reader through a
|
|
258
|
+
Cython bridge, so python and C agree by construction; this Node
|
|
259
|
+
implementation is the second one, and words every refusal as the C one does.
|
|
260
|
+
- **What is skipped is still JSON.** Navigating past a value — the members
|
|
261
|
+
before a pointer target, a field the type does not model — does not
|
|
262
|
+
construct it, but a fault inside it (`[1,,2]`, `trux`, `"a\q"`) is refused
|
|
263
|
+
at open with the text a read would give. A document nested deeper than 2048
|
|
264
|
+
is refused on every runtime, on the value being read and on junk being
|
|
265
|
+
skipped past alike — JSON is an untrusted-input boundary. Nothing after the
|
|
266
|
+
container being iterated is examined.
|
|
267
|
+
- **Strings are validated UTF-8.** A malformed byte sequence (an overlong
|
|
268
|
+
encoding, an encoded surrogate, a byte past U+10FFFF) is `invalid UTF-8 in
|
|
269
|
+
string` — never repaired to U+FFFD, never passed through — and a
|
|
270
|
+
`\uD83D\uDE00` escape pair joins into one code point.
|
|
271
|
+
- **What the schema cannot say, so it is stated here.** A `DateTime`'s instant
|
|
272
|
+
must fall in years 0001–9999, the range every runtime represents
|
|
273
|
+
(`format: "date-time"` admits year 0000, and an offset can carry a time past
|
|
274
|
+
either end), and its digits past the millisecond are dropped. A `Ref` that
|
|
275
|
+
the encoder wrote as `{"$ref": …}` (a repeated target) is not readable — as
|
|
276
|
+
with `Array`/`Set`/`Dict` aliasing, a value with shared references does not
|
|
277
|
+
validate against its own published schema. A `Dict` with two entries carrying
|
|
278
|
+
the same key satisfies `uniqueItems` (the entry objects differ) and is still
|
|
279
|
+
refused. A `Variant` must carry `"type"` before `"value"`, because the
|
|
280
|
+
payload cannot be typed before the case is known — the only place member
|
|
281
|
+
order matters; struct fields may arrive in any order.
|
|
282
|
+
|
|
283
|
+
## Related skills
|
|
284
|
+
|
|
285
|
+
- **east** — the language these platform functions plug into; compile with `NodePlatform`. `jsonSchemaFor(T)` there publishes the contract this reader enforces.
|
|
286
|
+
- **east-node-io** — the heavier I/O layer (SQL / NoSQL, S3, FTP / SFTP, XLSX / XML, compression) when `FileSystem` / `Fetch` aren't enough.
|
|
287
|
+
- **e3** — run these effects as durable, cached tasks instead of one-off scripts.
|
|
288
|
+
- **east-project** — to author your OWN custom platform function (not just use these stock ones): `East.platform(...).implement(...)` default-exported from your package's `./platform`, called from an e3 task via `{ runtime: 'east-node', platforms: [{ custom: '@elaraai/<project>' }] }`.
|
|
289
|
+
- **e3-create** — scaffold that custom platform: `--platform` for one project-owned module, or `--node-packages=<name>` for a dedicated npm workspace member with its own auto-derived e3 environment.
|
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
---
|
|
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."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Economic Ontology
|
|
7
|
+
|
|
8
|
+
An **Economic Ontology** describes how a business creates value: a graph whose nodes are the things a business cares about (resources, activities, KPIs, decisions, objectives, policies, data/systems) and whose links are the relationships between them. This skill covers two things: the **elicitation methodology** for building one with a stakeholder, and how to **encode + render** it with the `Ontology` component from `@elaraai/e3-ui`.
|
|
9
|
+
|
|
10
|
+
The point of an ontology is not the picture — it's to locate the **decisions** that drive objectives, so you can target the highest-value ones with AI / mathematical optimization (an east-py-datascience + e3 build).
|
|
11
|
+
|
|
12
|
+
## Before writing code — search the example index
|
|
13
|
+
|
|
14
|
+
Every East API has a tested example in the plugin's index — the index IS the
|
|
15
|
+
API reference, printed from each example's IR in TypeScript or python. Before
|
|
16
|
+
writing or changing East code:
|
|
17
|
+
|
|
18
|
+
1. Call `search_east_examples` for each capability you
|
|
19
|
+
are about to use — `language: "python"` for east-py, `"typescript"`
|
|
20
|
+
otherwise. Summaries come back first: id, signature, the inputs and the
|
|
21
|
+
expected result, a few hundred bytes each.
|
|
22
|
+
2. Fetch the one or two that match with `get_east_example`
|
|
23
|
+
and pattern your code on them.
|
|
24
|
+
3. Do not read `node_modules/@elaraai/**` or `*.examples.ts` files wholesale,
|
|
25
|
+
and do not reason from `.d.ts` signatures: the index holds the same
|
|
26
|
+
programs, exact and far cheaper, and the signatures omit the runtime rules
|
|
27
|
+
that make East code correct.
|
|
28
|
+
|
|
29
|
+
Nothing is injected for you; the search is the step.
|
|
30
|
+
|
|
31
|
+
## The conceptual model
|
|
32
|
+
|
|
33
|
+
A business creates value by **activities** that convert/exchange **resources** into other resources, **measured by** KPIs, **facilitated by** data/systems, **driven by** decisions, in service of **objectives**, **constrained by** policies. These map onto `NodeKindType` in `ontology.ts`:
|
|
34
|
+
|
|
35
|
+
| Workshop concept | Node kind | Meaning |
|
|
36
|
+
|---|---|---|
|
|
37
|
+
| Activity | `process` | A unit of value-creating work (source milk, pick & pack, dispatch) |
|
|
38
|
+
| Resource | `resource` | Something tracked + consumed/produced (inventory, money, employees, a forecast) |
|
|
39
|
+
| KPI | `kpi` | A quantitative measure of an activity's performance (fill rate, P99 latency) |
|
|
40
|
+
| Decision | `decision` | A choice about how to use resources in an activity to hit a KPI |
|
|
41
|
+
| Agent / role | `agent` | A person, team, or system role that executes activities and owns decisions |
|
|
42
|
+
| Objective | `objective` | A strategic goal — a function of resources ("maximise profit", "NPS ≥ 60") |
|
|
43
|
+
| Policy | `policy` | A rule constraining an activity (FEFO picking, least-privilege access) |
|
|
44
|
+
| Data / system | `data` | A dataset, signal, or system feeding an activity (WMS stream, SAP, carrier API) |
|
|
45
|
+
| Computation / model | `computation` | A derived quantity or model output |
|
|
46
|
+
| Document | `document` | Reference material — a procedure, contract, control spec |
|
|
47
|
+
| Group | `group` | A visual container only — no semantics |
|
|
48
|
+
|
|
49
|
+
Resources may be physical or abstract, ephemeral or long-lasting. Focus on **primary** value-creating activities (procurement, production, packaging, sales) over support functions (HR, Finance, IT), and on what's **quantitative** over qualitative.
|
|
50
|
+
|
|
51
|
+
## Canonical link directions
|
|
52
|
+
|
|
53
|
+
`LinkKindType` is directed (`source` → `target`). Treat the **activity (`process`) as the hub**: resources/KPIs/decisions/data attach to it. These are the patterns the editor's examples use — follow them so graphs read consistently:
|
|
54
|
+
|
|
55
|
+
| Pattern (`source --kind--> target`) | Reads as |
|
|
56
|
+
|---|---|
|
|
57
|
+
| `process --uses--> resource` | activity consumes an input resource |
|
|
58
|
+
| `process --produces--> resource` | activity emits an output resource |
|
|
59
|
+
| `process --results_in--> kpi` | activity's outcome lands in a KPI |
|
|
60
|
+
| `kpi --measures--> process` (or `resource`) | KPI quantifies the activity |
|
|
61
|
+
| `kpi --drives--> objective` | KPI moves a strategic goal |
|
|
62
|
+
| `decision --drives--> process` (or `kpi` / `objective`) | decision steers the activity toward goals |
|
|
63
|
+
| `agent --executes--> process` (or `decision`) | the role that performs the activity / makes the call |
|
|
64
|
+
| `kpi --measures--> agent` | KPI quantifies a team's performance |
|
|
65
|
+
| `data --informs--> process` | a system/signal feeds the activity ("facilitated by") |
|
|
66
|
+
| `process --inserts_data_into--> data` | activity writes back to a system |
|
|
67
|
+
| `data --gets_data_from--> data` (or other) | a read dependency between signals |
|
|
68
|
+
| `policy --constrains--> process` | a rule limits the activity |
|
|
69
|
+
| `document --defines--> policy` | a spec defines a rule |
|
|
70
|
+
| `document --references--> policy` (or node) | documentation pointer |
|
|
71
|
+
|
|
72
|
+
Full `LinkKindType` vocabulary: `uses`, `produces`, `results_in`, `gets_data_from`, `inserts_data_into`, `informs`, `drives`, `constrains`, `defines`, `executes`, `references`, `validates`, `measures`, `simulates`, `contains` (for `group` nodes), `used_by` (inverse of `uses`). There is no literal "facilitates" — model it with `informs` / `gets_data_from`.
|
|
73
|
+
|
|
74
|
+
## Elicitation workflow
|
|
75
|
+
|
|
76
|
+
Run this with the stakeholder; it mirrors the workshop sequence. Capture **problems, not solutions** until the graph is built. Use `AskUserQuestion` to drive each step.
|
|
77
|
+
|
|
78
|
+
```
|
|
79
|
+
1. PAIN → What blocks target KPIs / creates bottlenecks? (capture, don't solve)
|
|
80
|
+
2. ACTIVITIES → List primary value-creating activities → `process` nodes
|
|
81
|
+
3. RESOURCES → For each: what does it use / produce? → `resource` + uses/produces
|
|
82
|
+
4. MEASURE → How is each measured? → `kpi` + measures / results_in
|
|
83
|
+
5. FACILITATE → Which data/systems feed it? → `data` + informs / gets_data_from
|
|
84
|
+
6. DRIVE → What decision sets how resources are used? → `decision` + drives
|
|
85
|
+
6b. OWN → Who executes it / makes that call? → `agent` + executes
|
|
86
|
+
7. OBJECTIVES → What goals do the KPIs serve? → `objective` + kpi drives objective
|
|
87
|
+
8. CONSTRAIN → What rules limit activities? → `policy` + constrains (+ `document` defines)
|
|
88
|
+
9. PRIORITISE → Which decisions, if improved, move objectives most? → the AI/opt backlog
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Start from the **biggest pain points** — don't try to model the whole business. The output of step 9 is the real deliverable: a ranked list of decisions worth improving.
|
|
92
|
+
|
|
93
|
+
### The activity table (intermediate artifact)
|
|
94
|
+
|
|
95
|
+
Before drawing the graph, fill one row per activity. Each row mechanically expands into nodes + links:
|
|
96
|
+
|
|
97
|
+
| Activity | Uses (resources) | Produces (resources) | Measured by (KPIs) | Facilitated by (data/systems) | Driven by (decision) | Owned by (agent) |
|
|
98
|
+
|---|---|---|---|---|---|---|
|
|
99
|
+
| Source raw milk | farm supplier base, demand forecast | raw-milk availability, supply contracts | fortnightly farmgate vs benchmark | SAP, supplier system | how much milk to contract, by region/term | procurement team |
|
|
100
|
+
|
|
101
|
+
Row → one `process` node, one `resource` per cell entry (dedup across rows by `id`), and a link per relationship using the canonical directions above. Decisions and objectives come last and attach with `drives`.
|
|
102
|
+
|
|
103
|
+
## Encode + render
|
|
104
|
+
|
|
105
|
+
The graph is the value of a single `OntologyType`-typed `e3.input`, surfaced through a `Data.bind` binding. Spell the default value out **fully inline** — no `node()` / `link()` helpers, every `variant()` / `some()` / `none` at the construction site.
|
|
106
|
+
|
|
107
|
+
```typescript
|
|
108
|
+
import { East, some, none, variant } from '@elaraai/east';
|
|
109
|
+
import { Reactive, UIComponentType } from '@elaraai/east-ui';
|
|
110
|
+
import { Data, Ontology, OntologyType } from '@elaraai/e3-ui';
|
|
111
|
+
import * as e3 from '@elaraai/e3';
|
|
112
|
+
|
|
113
|
+
const ontology = e3.input('supply_chain', OntologyType, variant('value', {
|
|
114
|
+
nodes: [
|
|
115
|
+
{ id: 'obj-1', name: 'Reduce stockouts', description: some('FY26 target.'), type: variant('objective', null) },
|
|
116
|
+
{ id: 'kpi-1', name: 'Fill rate', description: none, type: variant('kpi', null) },
|
|
117
|
+
{ id: 'proc-1', name: 'Source raw milk', description: none, type: variant('process', null) },
|
|
118
|
+
{ id: 'res-1', name: 'Pallet inventory', description: none, type: variant('resource', null) },
|
|
119
|
+
{ id: 'dec-1', name: 'Contract volume', description: none, type: variant('decision', null) },
|
|
120
|
+
],
|
|
121
|
+
links: [
|
|
122
|
+
{ id: 'l-1', source: 'proc-1', target: 'res-1', type: variant('produces', null) },
|
|
123
|
+
{ id: 'l-2', source: 'kpi-1', target: 'proc-1', type: variant('measures', null) },
|
|
124
|
+
{ id: 'l-3', source: 'kpi-1', target: 'obj-1', type: variant('drives', null) },
|
|
125
|
+
{ id: 'l-4', source: 'dec-1', target: 'proc-1', type: variant('drives', null) },
|
|
126
|
+
],
|
|
127
|
+
metadata: some({
|
|
128
|
+
version: '1.0.0',
|
|
129
|
+
created: new Date('2026-01-15T00:00:00Z'),
|
|
130
|
+
updated: new Date('2026-05-01T12:00:00Z'),
|
|
131
|
+
description: some('Supply-chain operations ontology.'),
|
|
132
|
+
}),
|
|
133
|
+
}));
|
|
134
|
+
|
|
135
|
+
const editor = East.function([], UIComponentType, (_$) =>
|
|
136
|
+
Reactive.Root(East.function([], UIComponentType, $ => {
|
|
137
|
+
const view = $.let(Data.bind(ontology));
|
|
138
|
+
return Ontology.Root({ binding: view.binding });
|
|
139
|
+
})),
|
|
140
|
+
);
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
### `Ontology.Root` options
|
|
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`).
|
|
146
|
+
|
|
147
|
+
### The table view
|
|
148
|
+
|
|
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
|
+
|
|
151
|
+
### Edit modes, commit, and Diff
|
|
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)`.
|
|
154
|
+
|
|
155
|
+
## Validation
|
|
156
|
+
|
|
157
|
+
- **`id` uniqueness** — every node `id` is distinct; link `id`s too.
|
|
158
|
+
- **No orphan links** — each link's `source` and `target` must match a node `id`; the editor surfaces orphans as warnings.
|
|
159
|
+
- **Direction matches semantics** — follow the canonical table; e.g. KPI is the `source` of `measures`, the activity is the `target`.
|
|
160
|
+
- **Objectives are apexes** — they should be reachable from KPIs/decisions via `drives`, not dangling.
|
|
161
|
+
|
|
162
|
+
## From ontology to initiatives
|
|
163
|
+
|
|
164
|
+
The graph exists to find the decisions worth improving. For each `decision` node, the question is: *what's the best way to use its resources to hit the connected KPIs and objectives?* That's an optimization/ML problem — hand it to **east-py-datascience** (MADS / Optuna / SimAnneal / GoogleOr for the decision, XGBoost / NGBoost for the forecasts that feed it) wrapped as **e3** tasks. Use the **east-design** skill to turn the prioritised decision list into that build.
|
|
165
|
+
|
|
166
|
+
## Related skills
|
|
167
|
+
|
|
168
|
+
- **e3-ui** — the `Ontology`, `Data.bind`, and `Diff` API this builds on (and `ui()` to ship the editor as an e3 task).
|
|
169
|
+
- **east-ui** — layout (`Card`, `Stack`) for composing the editor into a dashboard.
|
|
170
|
+
- **east-design** — turn the prioritised decisions into an implementation plan.
|
|
171
|
+
- **east-py-datascience** — the optimization / ML that improves a targeted decision.
|
|
172
|
+
- **east-project** — scaffold the e3 project that hosts the ontology + decision tasks.
|
|
173
|
+
|
|
174
|
+
## Example searches
|
|
175
|
+
|
|
176
|
+
Ground the encoding in real graphs via `search_east_examples`:
|
|
177
|
+
- `Ontology supply-chain process kpi objective` — a full activity/resource/KPI graph
|
|
178
|
+
- `Ontology governance policy decision document` — policy/decision/document-heavy graph
|
|
179
|
+
- `Ontology Diff review pending patch` — editor + Diff panel for staged commits
|
|
180
|
+
- `Ontology readonly viewer` — locked, mutation-free view
|
|
181
|
+
- `Ontology density compact` — density presets
|