@elaraai/create-e3 1.0.68 → 1.0.69

package/dist/index.js

@@ -28,6 +28,7 @@ var RUNTIMES = {
     destParent: "packages/python",
     templateName: "python",
     label: "Python",
+    tasks: 2,
     valid: /^[a-z][a-z0-9_]*$/,
     rule: "lowercase letters, digits and underscores, starting with a letter"
   },
@@ -37,6 +38,7 @@ var RUNTIMES = {
     destParent: "packages/node",
     templateName: "node",
     label: "Node",
+    tasks: 2,
     valid: /^[a-z][a-z0-9-]*$/,
     rule: "lowercase letters, digits and hyphens, starting with a letter"
   },
@@ -46,6 +48,7 @@ var RUNTIMES = {
     destParent: "packages/native",
     templateName: "c",
     label: "C",
+    tasks: 1,
     valid: /^[a-z][a-z0-9_-]*$/,
     rule: "lowercase letters, digits, underscores and hyphens, starting with a letter"
   }
@@ -146,11 +149,13 @@ function excludePackagesFromRootTsconfig(projectDir) {
 `);
 }
 function writeAppWiring(projectDir, names, members) {
-  const imports = members.map((m) => `import { ${m.ident}_task } from "./${m.name}.js";`).join("\n");
-  const list = members.map((m) => `  ${m.ident}_task,`).join("\n");
-  const barrel = `// Generated by create-e3 \u2014 collects one example task per workspace package.
-// Each task's \`environment\` points at its package, so editing one package
-// re-runs only its task. Add packages with \`create-e3 --python-packages=\u2026\`.
+  const imports = members.map((m) => `import { ${m.ident}_tasks } from "./${m.name}.js";`).join("\n");
+  const list = members.map((m) => `  ...${m.ident}_tasks,`).join("\n");
+  const taskCount = members.reduce((n, m) => n + RUNTIMES[m.runtime].tasks, 0);
+  const barrel = `// Generated by create-e3 \u2014 collects the example tasks of every workspace package:
+// a call of the package's platform function (its environment derived from the
+// package) and, for python and node, a call of an East function the package
+// exports (embedded at export). Add packages with \`create-e3 --python-packages=\u2026\`.
 ${imports}
 
 export const packageTasks = [
@@ -163,10 +168,11 @@ ${list}
 
 import { packageTasks } from "./packages/index.js";
 
-// This app wires one example task per generated workspace package. Every
-// task's \`environment\` is captured independently, so editing one package
-// re-runs only its task \u2014 the other packages stay cached. Add your own
-// inputs, tasks and dataflows here.
+// This app wires the example tasks of each generated workspace package. A
+// platform-function task's \`environment\` is captured per package, so editing
+// one package re-runs only its tasks \u2014 the other packages stay cached; an
+// imported East function is embedded at export and runs anywhere. Add your
+// own inputs, tasks and dataflows here.
 export default e3.package("${names.projectName}", "1.0.0", ...packageTasks);
 `;
   writeFileSync(join(projectDir, "src", "index.ts"), index);
@@ -180,9 +186,9 @@ import { packageTasks } from "./packages/index.js";
 // Generated by create-e3 \u2014 smoke tests for the generated multi-package
 // app. Replace with real tests as you add inputs, tasks and dataflows.
 describeEast("${names.displayName}", (test) => {
-  test("wires one task per workspace package", ($) => {
+  test("wires every example task of every workspace package", ($) => {
     const count = $.const(BigInt(packageTasks.length), IntegerType);
-    $(Assert.equal(count, East.value(${members.length}n)));
+    $(Assert.equal(count, East.value(${taskCount}n)));
   });
 
   test("exports the deployable package", ($) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elaraai/create-e3",
-  "version": "1.0.68",
+  "version": "1.0.69",
   "description": "Scaffold a new e3 project (BSL-1.1, Node + Python, durable execution): npm create @elaraai/e3",
   "type": "module",
   "bin": {

package/templates/e3/README.md

@@ -51,3 +51,10 @@ anything was skipped; `npm run shots:html` adds a standalone HTML beside each PN
 If you scaffolded with `--platform`, `src/platform/` holds project-owned TS-East platform functions
 (exported via `./platform`) and `platform_module/` holds the Python ones — replace the generated
 `example` functions with your own native code, called from tasks like any East function.
+
+If you scaffolded with `--python-packages` / `--node-packages` / `--c-packages`, each package under
+`packages/` is its own execution environment, and every python and node package crosses the language
+boundary both ways: a platform function (`example.py` / `src/platform.ts` — native code the task's
+runner needs installed) and an East function (`functions.py` / `src/functions.ts` — East IR the app
+imports with `East.importFunction`; e3 embeds it at export, so it runs anywhere). The app-side wiring
+of each package is `src/packages/<name>.ts`.

package/templates/e3/_packages/c/_app.ts

@@ -20,3 +20,8 @@ export const __PACKAGE_IDENT___task = e3.customTask(
     environment: { tools: { files: ["packages/native/__PACKAGE_NAME__/build/__PACKAGE_NAME__"] } },
   },
 );
+
+// Every task this package contributes to the app's dataflow (collected by
+// src/packages/index.ts). A C package crosses the boundary one way — the built
+// tool; C has no East authoring surface to export a function from.
+export const __PACKAGE_IDENT___tasks = [__PACKAGE_IDENT___task];

package/templates/e3/_packages/node/_app.ts

@@ -1,13 +1,31 @@
 import e3 from "@elaraai/e3";
-import { East, IntegerType, FloatType } from "@elaraai/east";
+import { East, ArrayType, IntegerType, FloatType, FunctionType } from "@elaraai/east";
 
-// TS-East mirror of @__PROJECT_NAME__/__PACKAGE_NAME__'s platform function —
-// same dotted "__PACKAGE_NAME__.example" name + signature. Keep this in lockstep
-// with packages/node/__PACKAGE_NAME__/src/platform.ts.
+// Two ways of crossing the package boundary into packages/node/__PACKAGE_NAME__
+// (@__PROJECT_NAME__/__PACKAGE_NAME__):
+//
+// 1. A PLATFORM function — native Node code East cannot express. This TS-East
+//    declaration mirrors packages/node/__PACKAGE_NAME__/src/platform.ts (same
+//    dotted "__PACKAGE_NAME__.example" name + signature — keep the two in lockstep),
+//    and the task calling it runs on east-node with the package installed.
 const example = East.platform("__PACKAGE_NAME__.example", [IntegerType, FloatType], IntegerType);
 
+// 2. An EAST function — East IR authored in the package (…/src/functions.ts,
+//    listed in its `eastFunctions`), referred to by package, name and type. At
+//    export e3 finds the package in the npm workspace, exports its functions from
+//    the built ./functions entry (east-node export-functions) and embeds the IR in
+//    the task: the deployed program is pure IR, so the task needs no platform and
+//    no environment. The type must equal the exported one exactly — e3 checks it
+//    at export.
+const scale = East.importFunction(
+  "@__PROJECT_NAME__/__PACKAGE_NAME__",
+  "scale",
+  FunctionType([ArrayType(FloatType), FloatType], ArrayType(FloatType)),
+);
+
 const value = e3.input("__PACKAGE_IDENT___value", IntegerType, 21n);
 const factor = e3.input("__PACKAGE_IDENT___factor", FloatType, 2.0);
+const series = e3.input("__PACKAGE_IDENT___series", ArrayType(FloatType), [1.0, 2.0, 3.0]);
 
 // No `environment` — e3 derives it from the `{ custom: "@__PROJECT_NAME__/__PACKAGE_NAME__" }`
 // platform reference below, capturing packages/node/__PACKAGE_NAME__'s npm
@@ -23,3 +41,17 @@ export const __PACKAGE_IDENT___task = e3.task(
     runner: { runtime: "east-node", platforms: [{ custom: "@__PROJECT_NAME__/__PACKAGE_NAME__" }] },
   },
 );
+
+// The imported East function needs no runner, platform or environment: its IR is
+// embedded here at export, and the default runner executes it.
+export const __PACKAGE_IDENT___scaled_task = e3.task(
+  "__PACKAGE_IDENT___scaled",
+  [series, factor],
+  East.function([ArrayType(FloatType), FloatType], ArrayType(FloatType), ($, s, f) => {
+    $.return(scale(s, f));
+  }),
+);
+
+// Every task this package contributes to the app's dataflow (collected by
+// src/packages/index.ts).
+export const __PACKAGE_IDENT___tasks = [__PACKAGE_IDENT___task, __PACKAGE_IDENT___scaled_task];

package/templates/e3/_packages/node/package.json

@@ -6,6 +6,7 @@
   "private": true,
   "exports": {
     "./platform": "./dist/platform.js",
+    "./functions": "./dist/functions.js",
     "./package.json": "./package.json"
   },
   "files": [

package/templates/e3/_packages/node/src/functions.ts

@@ -0,0 +1,29 @@
+import { East, ArrayType, FloatType } from "@elaraai/east";
+
+// An East function owned by @__PROJECT_NAME__/__PACKAGE_NAME__ — East all the way down.
+//
+// platform.ts is the other way across the package boundary: a platform function
+// wraps NATIVE Node code East cannot express, and the task calling it runs on
+// east-node with this package installed. An East function is built here with
+// `East.function`, so it IS East IR: the app refers to it by package, name and
+// type (East.importFunction("@__PROJECT_NAME__/__PACKAGE_NAME__", "scale", …) in
+// src/packages/__PACKAGE_NAME__.ts), and at export e3 finds this package in the
+// npm workspace, exports every function in `eastFunctions` from the BUILT
+// `./functions` entry (east-node export-functions on dist/functions.js — build
+// first) and embeds the IR in the task. The deployed program is pure IR and runs
+// on any runner, with nothing installed where it runs.
+//
+// To add a function: build it here and add it to `eastFunctions` under the name
+// the app imports. The app declares the same FunctionType — the two must be
+// equal exactly, and e3 checks that at export.
+
+// Scale every value by a factor. The parameters are East expressions and `.map`
+// builds East IR — nothing here runs in Node.
+export const scale = East.function(
+  [ArrayType(FloatType), FloatType],
+  ArrayType(FloatType),
+  ($, values, factor) => values.map(($, v) => v.multiply(factor)),
+);
+
+// The East functions this package exports, by the name the app imports them under.
+export const eastFunctions = { scale };

package/templates/e3/_packages/python/_app.ts

@@ -1,12 +1,28 @@
 import e3 from "@elaraai/e3";
-import { East, ArrayType, FloatType } from "@elaraai/east";
+import { East, ArrayType, FloatType, FunctionType } from "@elaraai/east";
 
-// TS-East mirror of `packages/python/__PACKAGE_NAME__`'s @platform_function —
-// same dotted "__PACKAGE_NAME__.example" name, same signature. Keep this in
-// lockstep with packages/python/__PACKAGE_NAME__/src/__PACKAGE_NAME__/example.py.
+// Two ways of crossing the language boundary into packages/python/__PACKAGE_NAME__:
+//
+// 1. A PLATFORM function — native python East cannot express. This TS-East
+//    declaration mirrors packages/python/__PACKAGE_NAME__/src/__PACKAGE_NAME__/example.py
+//    (same dotted "__PACKAGE_NAME__.example" name, same signature — keep the two in
+//    lockstep), and the task calling it runs on east-py with the package installed.
 const example = East.platform("__PACKAGE_NAME__.example", [ArrayType(FloatType)], FloatType);
 
+// 2. An EAST function — East IR authored in python (…/functions.py, listed in the
+//    package's `east_functions`), referred to by package, name and type. At export
+//    e3 finds the package in the uv workspace, exports its functions (east-py
+//    export-functions) and embeds the IR in the task: the deployed program is pure
+//    IR, so the task runs on the DEFAULT runner (east-node) with no python at run
+//    time. The type must equal the exported one exactly — e3 checks it at export.
+const scale = East.importFunction(
+  "__PACKAGE_NAME__",
+  "scale",
+  FunctionType([ArrayType(FloatType), FloatType], ArrayType(FloatType)),
+);
+
 const values = e3.input("__PACKAGE_IDENT___values", ArrayType(FloatType), [1.0, 2.0, 3.0]);
+const factor = e3.input("__PACKAGE_IDENT___factor", FloatType, 2.0);
 
 // No `environment` needed: e3 derives it from the `{ custom: "__PACKAGE_NAME__" }`
 // platform reference below — at export it captures packages/python/__PACKAGE_NAME__'s
@@ -24,3 +40,17 @@ export const __PACKAGE_IDENT___task = e3.task(
     runner: { runtime: "east-py", platforms: [{ custom: "__PACKAGE_NAME__" }, "east-py-std"] },
   },
 );
+
+// The imported East function needs no runner, platform or environment: its IR is
+// embedded here at export, and the default runner executes it.
+export const __PACKAGE_IDENT___scaled_task = e3.task(
+  "__PACKAGE_IDENT___scaled",
+  [values, factor],
+  East.function([ArrayType(FloatType), FloatType], ArrayType(FloatType), ($, v, f) => {
+    $.return(scale(v, f));
+  }),
+);
+
+// Every task this package contributes to the app's dataflow (collected by
+// src/packages/index.ts).
+export const __PACKAGE_IDENT___tasks = [__PACKAGE_IDENT___task, __PACKAGE_IDENT___scaled_task];

package/templates/e3/_packages/python/src/__PACKAGE_NAME__/__init__.py

@@ -1,18 +1,29 @@
-"""The ``__PACKAGE_NAME__`` platform package — its own execution environment.
+"""The ``__PACKAGE_NAME__`` package — its own execution environment, and both ways
+of crossing the language boundary.
 
 Everything under ``packages/python/__PACKAGE_NAME__`` is captured as ONE
-environment when a task wired to it is exported. Editing this package changes
-only its environment hash, so only the tasks that declare
-``environment: { python: { project: "packages/python/__PACKAGE_NAME__" } }``
-re-run — sibling packages are left untouched. That package boundary IS the
+environment when a task wired to it is exported: e3 derives it from the task's
+``{ custom: "__PACKAGE_NAME__" }`` platform reference. Editing this package
+changes only its environment hash, so only the tasks wired to it re-run —
+sibling packages are left untouched. That package boundary IS the
 change-detection granularity.
 
-``east-py run -p __PACKAGE_NAME__`` imports this package and reads the top-level
-``platform`` list below. To add a function: create a module beside this file
-(e.g. ``pricing.py``) ending with ``pricing_impl = platform_functions(__name__)``,
-then import and spread it into ``platform``.
+Two things cross from here into the app's TypeScript tasks:
+
+- ``platform`` — the platform functions (``example.py``): NATIVE python that
+  East cannot express. ``east-py run -p __PACKAGE_NAME__`` imports this package
+  and reads the list. To add one: create a module beside this file (e.g.
+  ``pricing.py``) ending with ``pricing_impl = platform_functions(__name__)``,
+  then import and spread it into ``platform``.
+- ``east_functions`` — the East functions (``functions.py``): East IR authored
+  in python, imported by the app with ``East.importFunction`` and embedded at
+  export, so they run on any runner with no python at run time. To add one:
+  build it and add it here under the name the app imports.
 """
 
 from .example import example_impl
+from .functions import scale
 
 platform = [*example_impl]
+
+east_functions = {"scale": scale}

package/templates/e3/_packages/python/src/__PACKAGE_NAME__/functions.py

@@ -0,0 +1,29 @@
+"""An East function owned by the ``__PACKAGE_NAME__`` package — East all the way down.
+
+``example.py`` is the other way across the language boundary: a platform
+function wraps NATIVE python that East cannot express, and the task calling it
+runs on east-py with this package installed. An East function is authored in
+python but built with east-py's ``East.function``, so it IS East IR: the app's
+TypeScript task refers to it by package, name and type
+(``East.importFunction("__PACKAGE_NAME__", "scale", …)`` in
+``src/packages/__PACKAGE_NAME__.ts``), and at export e3 finds this package in
+the uv workspace, exports every function in ``east_functions`` (``east-py
+export-functions``) and embeds the IR in the task. The deployed program is pure
+IR — it runs on ANY runner, the default east-node one included, with no python
+at run time and nothing installed where it runs.
+
+To add a function: build it here (or in a module beside this one) and add it to
+``east_functions`` in ``__init__.py`` under the name the app imports. The app
+declares the same type with ``FunctionType([...], Out)`` — the two must be equal
+exactly, and e3 checks that at export.
+"""
+
+from east import ArrayType, East, FloatType
+
+# Scale every value by a factor. The parameters are East expressions and `.map`
+# builds East IR — nothing here runs in python.
+scale = East.function(
+    [ArrayType(FloatType), FloatType],
+    ArrayType(FloatType),
+    lambda b, values, factor: values.map(lambda b, v: v * factor),
+)