@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.
@@ -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