@elaraai/east-codex-plugin 1.0.89 → 1.0.91

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.89",
3
+ "version": "1.0.91",
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",
@@ -102,10 +102,12 @@ platform = East.platform_functions(__name__) # pass to East.compile(fn, platfo
102
102
  A body's parameters are expressions already. A python scalar or `datetime` inside
103
103
  a body lifts to a literal; `East.value(v, T)` / `b.const(v)` lift anything else
104
104
  (TS `East.value` / `$.const`); an East COLLECTION an `East.function` body closes
105
- over is snapshot into the IR (`.bind(table)` it as a trailing parameter to keep it
106
- live). The other way, an artifact is a plain callable on values, every eager
107
- method accepts one (a VALUE takes no block), and one called inside another body
108
- is a call of its inline Function node — see [Python values vs East expressions](#python-values-vs-east-expressions).
105
+ over is snapshot into the IR as a literal of its contents, rebuilt wherever the
106
+ body reads it — `t = b.const(table)` builds it once per call, and `.bind(table)`
107
+ as a trailing parameter keeps it live. The other way, an artifact is a plain
108
+ callable on values, every eager method accepts one (a VALUE takes no block),
109
+ and one called inside another body is a call of its inline Function node — see
110
+ [Python values vs East expressions](#python-values-vs-east-expressions).
109
111
 
110
112
  ## Decision Tree: What Do You Need?
111
113
 
@@ -140,7 +142,7 @@ Task → What do you need?
140
142
  │ ├─ Call python from a body → the @East.platform_function you hold IS the Platform node (no declaration) · East.platform /
141
143
  │ │ asyncPlatform / genericPlatform only for one implemented elsewhere · East.compile(fn, platform=East.platform_functions(__name__))
142
144
  │ │ → "Declare, implement, build, compile", "Platform functions"
143
- │ ├─ Make it fast → data stays in East · chain · CSE by reusing a python variable · capture small tables, .bind big ones
145
+ │ ├─ Make it fast → data stays in East · chain · bind shared work with b.const · b.const a captured table, .bind big ones
144
146
  │ │ → "Performance — the levers, ranked"
145
147
  │ ├─ IR ↔ python → to_python_source · east-py transpile · compile_from_beast2 / json / east / value · east-c ir … → "IR ↔ python"
146
148
  │ ├─ Refusals at edit time → east-py lint · flake8 --select EAS · east-py lsp; TYPE errors → east-py check
@@ -171,9 +173,10 @@ Task → What do you need?
171
173
  │ └─ Let East call python → @East.platform_function · @East.generic_platform_function · @memoize → "Platform functions"
172
174
  │
173
175
  ├─ C. Cross between them → a body's parameters are expressions · python scalars and datetimes lift · East.value(v, T) /
174
- │ b.const(v) · a captured East collection is a build-time SNAPSHOT (an eager callback refuses it), .bind(table) keeps it
175
- │ live · an East function is a callable on values, and a VALUE takes no block · east.runtime.compiler.eager_stats()
176
- │ shows how a hot call ran → "Python values vs East expressions", "Performance"
176
+ │ b.const(v) · a captured East collection is a build-time SNAPSHOT, a literal rebuilt at each read (an eager callback
177
+ │ refuses it) — b.const(table) builds it once per call, .bind(table) keeps it live · an East function is a callable on
178
+ │ values, and a VALUE takes no block · east.runtime.compiler.eager_stats() shows how a hot call ran
179
+ │ → "Python values vs East expressions", "Performance"
177
180
  │
178
181
  └─ D. Run a program from the shell → east-py run (IR + input files → a result) · exec (a unit: the runner protocol e3
179
182
  speaks) · convert (a beast2 value → East text) · version · where its time goes: --profile / EAST_PROFILE=1
@@ -313,12 +316,12 @@ artifact used as an `East.if_else` arm evaluates only when that arm is taken,
313
316
  an error inside it names its own lines, and a profile lists it as an entry of
314
317
  its own, placed where it was written and where it was called. (One called with
315
318
  arguments narrower than its parameters — a column projection's narrowed rows —
316
- re-runs its source in its own frame and splices in instead, as does one whose
317
- build hoisted constants.) An artifact that mutates or raises, called and
318
- DISCARDED, is the build's "evaluated and thrown away" error — spell it
319
- `b.do(push(xs))` / `East.block(push(xs), result)`, as with any mutation. An
320
- artifact that calls platform functions stays first-class (composable,
321
- serializable) but raises until `East.compile` pairs it with implementations.
319
+ re-runs its source in its own frame and splices in instead.) An artifact that
320
+ mutates or raises, called and DISCARDED, is the build's "evaluated and thrown
321
+ away" error — spell it `b.do(push(xs))` / `East.block(push(xs), result)`, as
322
+ with any mutation. An artifact that calls platform functions stays first-class
323
+ (composable, serializable) but raises until `East.compile` pairs it with
324
+ implementations.
322
325
  `East.function(...)` spelled INSIDE a body is the inline `Function` node, a
323
326
  Function-typed expression: bind it with `b.const`, hand it to a callback slot,
324
327
  or call it (a `Call`; in an `East.asyncFunction`, calling an async one is a
@@ -516,7 +519,7 @@ East values. A worked example is in
516
519
  | `East.while_(state, cond, body, label=…)` | `While` | `cond(b, s) -> Boolean`, `body(b, s) -> next state` |
517
520
  | `East.for_(coll, state, body, label=…)` | `ForArray`/`ForSet`/`ForDict` | Array `body(b, s, el[, i])`, Set `body(b, s, el)`, Dict `body(b, s, k, v)` |
518
521
  | `East.block(a, b, …)` | `Block` | evaluates in order, yields the last — the sequencing point for mutators (`East.block(lambda b: …)` is the statement form) |
519
- | `East.let(value, fn)` | `Let` | `fn(b, bound)` — bind once, use many times (explicit CSE inside a loop) |
522
+ | `East.let(value, fn)` | `Let` | `fn(b, bound)` — bind once, use many times, inside an expression body (`b.const` is the statement form) |
520
523
  | `East.ref(v)` | `NewRef` | a cell — `.get()` / `.update(v)` / `.merge(v, fn(b, current, patch))` |
521
524
  | `East.label(name=None)` | — | names a loop, for `break_`/`continue_` from a NESTED one |
522
525
  | `East.break_(state=…, label=…)` / `East.continue_(state=…, label=…)` | `Break` / `Continue` | leave / next iteration, optionally committing a last state |
@@ -539,10 +542,10 @@ counts = East.for_(rows, {"counts": East.new_dict(StringType, IntegerType)},
539
542
  ```
540
543
 
541
544
  ⚠️ Seed accumulators with `East.new_array/new_set/new_dict`. A captured
542
- `EastArray(T)` works too — a loop's seed is built fresh per call — but
543
- anywhere ELSE in a function a captured collection is a build-time snapshot
544
- shared by every call, and mutating one raises rather than leaking state
545
- between calls.
545
+ `EastArray(T)` works too — a captured collection is a snapshot of its
546
+ contents, rebuilt wherever the body reads it, so a seed is fresh per call —
547
+ but mutating one anywhere ELSE changes a copy nothing else sees, and the
548
+ build raises rather than compile a mutation that persists nowhere.
546
549
 
547
550
  ### Queries — `East.jq`
548
551
 
@@ -625,34 +628,39 @@ element**.
625
628
  crossing per element — convert at most once, at the very end.
626
629
  2. **Let the callbacks build, and chain on the results** — a chain of
627
630
  `map`/`filter`/`reduce` stays native between steps. Return a dict literal
628
- (`lambda b, r: {"a": …, "b": …}`) to derive every column in ONE pass. **Reuse
629
- a python variable to share work** (build-time CSE): `fields =
630
- r.data.split("|")` read for 30 columns compiles to ONE `Let` — the split runs
631
- once per row (re-calling `.split()` per column re-emits it). Loop-invariant
632
- subexpressions hoist out of nested lambdas to the function body, a value read
633
- once inside a callback included, so `table = derive(rec)` before a `.map` runs
634
- once. A hoist never leaves a guard: a subexpression shared inside `b.try_` /
635
- `East.try_catch` binds inside that body, so `s.try_parse(T)` still answers
636
- `none` when CSE'd. `East.function(..., cse=False)` switches the pass off and
637
- builds exactly what the body spells (what the transpiler emits).
638
- 3. **Side tables: capture small ones, `bind` big ones** — opposite contracts:
631
+ (`lambda b, r: {"a": …, "b": …}`) to derive every column in ONE pass. **Bind
632
+ shared work with `b.const`** — the builder emits exactly what the body
633
+ spells, as TypeScript's does, so a python variable holding an expression is
634
+ re-emitted (and re-evaluated) at every read: `fields = r.data.split("|")`
635
+ read for 30 columns runs the split 30 times per row, and `table =
636
+ derive(rec)` read inside a `.map` runs `derive` once per element. `fields =
637
+ b.const(r.data.split("|"))` and `table = b.const(derive(rec))` run each
638
+ once, as `$.const` does — the `no-reinlined-east-binding` rule (`east-py
639
+ lint`, the LSP) points at every such read. There is no optimisation pass
640
+ (#1312 removed the trace-time CSE: it moved reads across mutations it could
641
+ not see), so what you write is what runs — a callback that pushes onto
642
+ `order` and returns `order.size() - 1` reads the size after its push.
643
+ 3. **Side tables: `b.const` a captured one, `bind` big ones** — opposite contracts:
639
644
  - **Capture (snapshot).** A collection captured by an `East.function` body
640
- is snapshot into its IR — hoisted and identity-deduped, so it builds **once
641
- per compiled function** and each lookup runs in C. Right for tables up to
642
- ~10⁴–10⁵ entries; the snapshot's build cost and memory ride the function (a
643
- 1M-entry dict takes ~10 s), and later mutations are **not** seen. Only an
645
+ is snapshot into its IR as a literal of its contents — exactly as a
646
+ TypeScript literal is — and rebuilt wherever the body reads it: per call
647
+ at the function's top level, per element inside a callback. **Bind it
648
+ once per call with `t = b.const(TABLE)`** and read `t`. Right for small
649
+ tables (up to a few thousand entries): the literal's size rides the IR,
650
+ every call rebuilds it, and later mutations are **not** seen. Only an
644
651
  EXPLICIT build snapshots: an eager callback refuses a mutable capture.
645
652
  - **`East.function(...).bind(table)` (by reference, live).** Declare the
646
- table as a trailing parameter and pre-bind it: zero copy, O(1) at any size
647
- (1M entries: ~0.1 ms), the per-row cost of the hoisted case, and the
648
- function **sees later mutations**. Rebinding gives independent callables,
649
- the unbound function stays usable, and a wrong-typed value raises
650
- `TypeError`.
653
+ table as a trailing parameter and pre-bind it: zero copy, O(1) at any
654
+ size, nothing rebuilt per call, and the function **sees later
655
+ mutations**. Rebinding gives independent callables, the unbound function
656
+ stays usable, and a wrong-typed value raises `TypeError`.
651
657
 
652
658
  ```python
653
659
  fx = EastDict(StringType, FloatType, rates) # small table → capture
654
- to_usd = East.function([Row], FloatType, # (the EXPLICIT build
655
- lambda b, r: r.amount * fx.get_or_default(r.ccy, 1.0)) # opts into snapshot)
660
+ @East.function([Row], FloatType) # (the EXPLICIT build
661
+ def to_usd(b, r): # opts into the snapshot)
662
+ t = b.const(fx) # the literal, once per call
663
+ return r.amount * t.get_or_default(r.ccy, 1.0)
656
664
 
657
665
  TableT = DictType(StringType, FloatType) # huge table → bind
658
666
  conv = East.function([Row, TableT], FloatType,
@@ -684,7 +692,7 @@ REBUILDS it through the surface above:
684
692
 
685
693
  ```python
686
694
  from east.codegen import to_python_source
687
- print(to_python_source(classify)) # `@East.function(..., cse=False)` / `def main(b, …)`
695
+ print(to_python_source(classify)) # `@East.function(...)` / `def main(b, …)`
688
696
  ```
689
697
 
690
698
  ```bash
@@ -793,6 +801,7 @@ The rules — `east-py lint --list-rules` prints them:
793
801
  | `no-python-string-building` (EAS023, warning) | an f-string assembling an East string CONSTANT — a regex, a template, a key | spell the constant out |
794
802
  | `no-derived-struct-fields` (EAS024, warning) | `Derived = StructType([… for f in Other.value])` | a type declaration is a wire format — spell the fields |
795
803
  | `no-python-data-work` (EAS025, warning) | a python helper doing parse / strip / null-check / coerce work on an EXPRESSION a body hands it | express it in East, where it runs on every row |
804
+ | `no-reinlined-east-binding` (EAS026, warning) | a python local holding an EXPRESSION (`n = xs.size()`, not a `b.let`/`b.const` binding) read more than once in one body, or read inside a per-element callback, a loop body or a nested function below the body that bound it | each read re-emits — and re-evaluates — the expression: bind it once, `n = b.const(xs.size())`, where it is needed (the TypeScript rule of the same name) |
796
805
 
797
806
  Configure it once in the project's `pyproject.toml`; every surface reads it, and
798
807
  `east-py lint`'s own flags add to it:
@@ -815,10 +824,7 @@ A file that does not import `east` is never diagnosed; a line ending in `# noqa`
815
824
  `node_modules`, `dist`, `build`, `.git`, `__pycache__`, `tests` and `test` are not
816
825
  walked. The rules are syntactic, so a clean `lint` is necessary, not sufficient —
817
826
  the type errors live behind `east-py check`. The rules are disjoint (each
818
- mistake is one rule's to report). One TypeScript rule has no python twin on
819
- purpose: `no-reinlined-east-binding` warns that a JS `const` holding an `Expr`
820
- re-inlines it at each use, but the python build's CSE binds a reused python local
821
- to ONE `Let`, so the hazard does not exist here.
827
+ mistake is one rule's to report).
822
828
 
823
829
  ### Cross-language functions: `east-py export-functions` and `East.import_function`
824
830
 
@@ -837,12 +843,11 @@ from east.types.types import FloatType, StructType, IntegerType
837
843
  Row = StructType([("qty", IntegerType), ("price", FloatType)])
838
844
  score = East.function([Row], FloatType, lambda b, r: r.qty.to_float() * r.price)
839
845
  east_functions = {"score": score} # name -> East.function artifact. CLOSED values: the
840
- # exported IR must BIND every name it reads. A build's
841
- # own hoisted constants — a captured lookup table, a
842
- # stdlib format string — ride along and close over
843
- # nothing; a .bind result (no IR of its own) and
844
- # an unresolved import are refused, and a genuinely free
845
- # variable is refused BY NAME
846
+ # exported IR must BIND every name it reads. A captured
847
+ # lookup table or a stdlib format string is a literal in
848
+ # the body and closes over nothing; a .bind result (no IR
849
+ # of its own) and an unresolved import are refused, and a
850
+ # genuinely free variable is refused BY NAME
846
851
  ```
847
852
 
848
853
  ```typescript
@@ -1639,7 +1644,7 @@ CUTOFF = 100
1639
1644
  @East.function([Row], FloatType)
1640
1645
  def usd(b, r):
1641
1646
  return East.if_else(r.amount > CUTOFF, # a scalar constant lifts (TS East.value)
1642
- r.amount * RATES.get_or_default(r.ccy, 1.0), # an EXPLICIT build snapshots the dict
1647
+ r.amount * RATES.get_or_default(r.ccy, 1.0), # an EXPLICIT build snapshots the dict: a literal, rebuilt per call
1643
1648
  0.0)
1644
1649
 
1645
1650
  rows.map(lambda b, r: r.amount * RATES.get_or_default(r.ccy, 1.0)) # ❌ an eager callback REFUSES