@elaraai/east 1.0.68 → 1.0.69

package/dist/src/codegen/spellings.spec.js

@@ -0,0 +1,191 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * The spelling table against the surface it spells (#645).
+ *
+ * A row's `exprs` names the argument slots the surface types `Expr`-only —
+ * where a literal must print through `East.value(v, T)`; every other slot
+ * is typed `SubtypeExprOrValue` (or a host value union) and a construction
+ * prints there as the host literal. The TypeScript signatures are the
+ * source of truth for that distinction, so this spec reads them — the
+ * expression classes and the `East.*` helpers under `src/expr/`, parsed by
+ * the TypeScript compiler — and checks every slot of every row: a slot in
+ * `exprs` is `Expr`-only in the signature, a slot in `inferred` is an
+ * unconstrained type parameter (the East type comes from the argument), and
+ * every other slot accepts a value under a type the surface supplies. A
+ * slot the signatures do not settle is an error, not a skip.
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+import { SPELLINGS } from "./spellings.js";
+const EXPR_DIR = fileURLToPath(new URL("../../../src/expr/", import.meta.url));
+/** A bare type-parameter name (the signature's own, unconstrained) — the East type is inferred from the argument. */
+const INFERRED = "<inferred>";
+function kindOf(type) {
+    if (type === INFERRED)
+        return "inferred";
+    if (/=>/.test(type))
+        return "callback";
+    if (/SubtypeExprOrValue|ExprOrValue|ValueTypeOf|\b(?:bigint|number|string|boolean|Date|Uint8Array|Map|Set|Float64Array|BigInt64Array|Uint8ClampedArray|null|RegExp)\b/.test(type))
+        return "value";
+    if (/Expr(?:Type)?(?:\b|<)/.test(type))
+        return "expr";
+    return "unknown";
+}
+/** Every signature (overloads and implementation) of `name` in `node`'s function-like members. */
+class Surface {
+    files = new Map();
+    constructor() {
+        for (const dir of [EXPR_DIR, join(EXPR_DIR, "libs")]) {
+            for (const f of readdirSync(dir)) {
+                if (!f.endsWith(".ts") || f.endsWith(".spec.ts"))
+                    continue;
+                const path = join(dir, f);
+                this.files.set(path, ts.createSourceFile(path, readFileSync(path, "utf-8"), ts.ScriptTarget.Latest, true));
+            }
+        }
+    }
+    file(name) {
+        const hit = this.files.get(join(EXPR_DIR, name));
+        if (hit === undefined)
+            throw new Error(`no surface file ${name}`);
+        return hit;
+    }
+    /** The parameters of a signature: a type parameter (also under `NoInfer`) reads as its constraint, or as {@link INFERRED} when it has none. */
+    static params(sig, sf) {
+        const constraints = new Map();
+        for (const tp of sig.typeParameters ?? [])
+            constraints.set(tp.name.text, tp.constraint?.getText(sf) ?? INFERRED);
+        return sig.parameters.map(p => {
+            const text = (p.type?.getText(sf) ?? "").replace(/^NoInfer<(.*)>$/, "$1");
+            return { type: constraints.get(text) ?? text, rest: p.dotDotDotToken !== undefined };
+        });
+    }
+    /** The signatures of method `name` on class `className` (its own file). */
+    method(className, name) {
+        const sf = this.file(`${className.slice(0, -4).toLowerCase()}.ts`);
+        const out = [];
+        const visit = (n) => {
+            if (ts.isClassDeclaration(n) && n.name?.text === className) {
+                for (const m of n.members) {
+                    if (ts.isMethodDeclaration(m) && ts.isIdentifier(m.name) && m.name.text === name)
+                        out.push(Surface.params(m, sf));
+                }
+            }
+            ts.forEachChild(n, visit);
+        };
+        visit(sf);
+        return out;
+    }
+    /** The signatures of the top-level function `name` in `file`. */
+    fn(file, name) {
+        const sf = this.file(file);
+        const out = [];
+        for (const s of sf.statements) {
+            if (ts.isFunctionDeclaration(s) && s.name?.text === name)
+                out.push(Surface.params(s, sf));
+        }
+        return out;
+    }
+    /** The signatures of member `name` of the default-exported object of `libs/<ns>.ts` — a method, or an imported function. */
+    lib(ns, name) {
+        const file = `libs/${ns.toLowerCase()}.ts`;
+        const sf = this.file(file);
+        const out = [];
+        const visit = (n) => {
+            if (ts.isObjectLiteralExpression(n)) {
+                for (const m of n.properties) {
+                    if (ts.isMethodDeclaration(m) && ts.isIdentifier(m.name) && m.name.text === name)
+                        out.push(Surface.params(m, sf));
+                    if (ts.isShorthandPropertyAssignment(m) && m.name.text === name)
+                        out.push(...this.fn(`${ns.toLowerCase()}.ts`, name));
+                }
+            }
+            ts.forEachChild(n, visit);
+        };
+        visit(sf);
+        return out;
+    }
+}
+/** The receiver class of a builtin by its name prefix; `null` for a namespace helper. */
+function receiverClass(builtin) {
+    if (builtin === "Parse" || builtin.startsWith("Regex"))
+        return "StringExpr";
+    for (const prefix of ["Array", "Blob", "Boolean", "DateTime", "Dict", "Float", "Integer", "Matrix", "Ref", "Set", "String", "Vector"]) {
+        if (builtin.startsWith(prefix))
+            return `${prefix}Expr`;
+    }
+    throw new Error(`no receiver class for ${builtin}`);
+}
+/** The top-level comma-separated argument templates of `head(args)`. */
+function argTemplates(template) {
+    let depth = 0;
+    for (let i = template.length - 1; i >= 0; i--) {
+        if (template[i] === ")")
+            depth += 1;
+        else if (template[i] === "(") {
+            depth -= 1;
+            if (depth === 0) {
+                const inner = template.slice(i + 1, -1).trim();
+                return { head: template.slice(0, i), args: inner === "" ? [] : inner.split(",").map(a => a.trim()) };
+            }
+        }
+    }
+    throw new Error(`not a call template: ${template}`);
+}
+test("every slot of the spelling table agrees with the surface's signatures: `exprs` are the Expr-only slots", () => {
+    const surface = new Surface();
+    const problems = [];
+    for (const [builtin, row] of Object.entries(SPELLINGS)) {
+        const { head, args } = argTemplates(row.template);
+        const method = /^\{\d+\}\.(\w+)$/.exec(head);
+        const namespaced = /^East\.(\w+)\.(\w+)$/.exec(head);
+        const root = /^East\.(\w+)$/.exec(head);
+        const signatures = method !== null
+            ? surface.method(receiverClass(builtin), method[1])
+            : namespaced !== null
+                ? surface.lib(namespaced[1], namespaced[2])
+                : root !== null
+                    ? surface.fn("block.ts", root[1])
+                    : [];
+        if (signatures.length === 0) {
+            problems.push(`${builtin}: no signature found for ${head}`);
+            continue;
+        }
+        const callbacks = new Set(row.callbacks ?? []);
+        const exprs = new Set(row.exprs ?? []);
+        const inferred = new Set(row.inferred ?? []);
+        args.forEach((arg, position) => {
+            const slot = /^\{(\d+)\}$/.exec(arg);
+            if (slot === null)
+                return; // a type parameter, the RegExp or the CSV options
+            const k = Number(slot[1]);
+            if (k === 0 || callbacks.has(k))
+                return; // the receiver is always an Expr; callbacks print as bodies
+            // the parameter at this position in every overload (a rest parameter covers the tail)
+            const kinds = new Set();
+            for (const sig of signatures) {
+                const p = sig[position] ?? (sig.length > 0 && sig[sig.length - 1].rest ? sig[sig.length - 1] : undefined);
+                if (p !== undefined)
+                    kinds.add(kindOf(p.type));
+            }
+            const where = `${builtin}: slot ${k} (${arg} of ${row.template})`;
+            // what the surface says: a typed value slot in any overload wins; else inferred; else Expr-only
+            const surface = kinds.has("value") ? "value" : kinds.has("inferred") ? "inferred" : kinds.has("expr") && !kinds.has("unknown") ? "expr" : "unknown";
+            // what the table says
+            const table = exprs.has(k) ? "expr" : inferred.has(k) ? "inferred" : "value";
+            if (surface === "unknown")
+                problems.push(`${where} has an unsettled type (${[...kinds].join(", ")})`);
+            else if (surface !== table)
+                problems.push(`${where} is ${surface} in the surface but ${table} in the table`);
+        });
+    }
+    assert.deepEqual(problems, [], `\n  ${problems.join("\n  ")}`);
+});
+//# sourceMappingURL=spellings.spec.js.map

package/dist/src/codegen/spellings.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spellings.spec.js","sourceRoot":"","sources":["../../../src/codegen/spellings.spec.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACpD,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,MAAM,QAAQ,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,oBAAoB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAS/E,qHAAqH;AACrH,MAAM,QAAQ,GAAG,YAAY,CAAC;AAE9B,SAAS,MAAM,CAAC,IAAY;IAC1B,IAAI,IAAI,KAAK,QAAQ;QAAE,OAAO,UAAU,CAAC;IACzC,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,UAAU,CAAC;IACvC,IAAI,kKAAkK,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,OAAO,CAAC;IAClM,IAAI,uBAAuB,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,MAAM,CAAC;IACtD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,kGAAkG;AAClG,MAAM,OAAO;IACF,KAAK,GAAG,IAAI,GAAG,EAAyB,CAAC;IAElD;QACE,KAAK,MAAM,GAAG,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC;YACrD,KAAK,MAAM,CAAC,IAAI,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC;gBACjC,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,UAAU,CAAC;oBAAE,SAAS;gBAC3D,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;gBAC1B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,gBAAgB,CAAC,IAAI,EAAE,YAAY,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;YAC7G,CAAC;QACH,CAAC;IACH,CAAC;IAED,IAAI,CAAC,IAAY;QACf,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC;QACjD,IAAI,GAAG,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,IAAI,EAAE,CAAC,CAAC;QAClE,OAAO,GAAG,CAAC;IACb,CAAC;IAED,+IAA+I;IAC/I,MAAM,CAAC,MAAM,CAAC,GAAgC,EAAE,EAAiB;QAC/D,MAAM,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAC;QAC9C,KAAK,MAAM,EAAE,IAAI,GAAG,CAAC,cAAc,IAAI,EAAE;YAAE,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC,UAAU,EAAE,OAAO,CAAC,EAAE,CAAC,IAAI,QAAQ,CAAC,CAAC;QACjH,OAAO,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE;YAC5B,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,iBAAiB,EAAE,IAAI,CAAC,CAAC;YAC1E,OAAO,EAAE,IAAI,EAAE,WAAW,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;QACvF,CAAC,CAAC,CAAC;IACL,CAAC;IAED,2EAA2E;IAC3E,MAAM,CAAC,SAAiB,EAAE,IAAY;QACpC,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;QACnE,MAAM,GAAG,GAAgB,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAG,CAAC,CAAU,EAAQ,EAAE;YACjC,IAAI,EAAE,CAAC,kBAAkB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,KAAK,SAAS,EAAE,CAAC;gBAC3D,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC;oBAC1B,IAAI,EAAE,CAAC,mBAAmB,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI;wBAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;gBACpH,CAAC;YACH,CAAC;YACD,EAAE,CAAC,YAAY,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QAC5B,CAAC,CAAC;QACF,KAAK,CAAC,EAAE,CAAC,CAAC;QACV,OAAO,GAAG,CAAC;IACb,CAAC;IAED,iEAAiE;IACjE,EAAE,CAAC,IAAY,EAAE,IAAY;QAC3B,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3B,MAAM,GAAG,GAAgB,EAAE,CAAC;QAC5B,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,UAAU,EAAE,CAAC;YAC9B,IAAI,EAAE,CAAC,qBAAqB,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI;gBAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;QAC5F,CAAC;QACD,OAAO,GAAG,CAAC;IACb,CAAC;IAED,4HAA4H;IAC5H,GAAG,CAAC,EAAU,EAAE,IAAY;QAC1B,MAAM,IAAI,GAAG,QAAQ,EAAE,CAAC,WAAW,EAAE,KAAK,CAAC;QAC3C,MAAM,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC3B,MAAM,GAAG,GAAgB,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAG,CAAC,CAAU,EAAQ,EAAE;YACjC,IAAI,EAAE,CAAC,yBAAyB,CAAC,CAAC,CAAC,EAAE,CAAC;gBACpC,KAAK,MAAM,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,CAAC;oBAC7B,IAAI,EAAE,CAAC,mBAAmB,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,YAAY,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI;wBAAE,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;oBAClH,IAAI,EAAE,CAAC,6BAA6B,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI;wBAAE,GAAG,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;gBACxH,CAAC;YACH,CAAC;YACD,EAAE,CAAC,YAAY,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;QAC5B,CAAC,CAAC;QACF,KAAK,CAAC,EAAE,CAAC,CAAC;QACV,OAAO,GAAG,CAAC;IACb,CAAC;CACF;AAED,yFAAyF;AACzF,SAAS,aAAa,CAAC,OAAe;IACpC,IAAI,OAAO,KAAK,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC;QAAE,OAAO,YAAY,CAAC;IAC5E,KAAK,MAAM,MAAM,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,QAAQ,CAAC,EAAE,CAAC;QACtI,IAAI,OAAO,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,OAAO,GAAG,MAAM,MAAM,CAAC;IACzD,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,yBAAyB,OAAO,EAAE,CAAC,CAAC;AACtD,CAAC;AAED,wEAAwE;AACxE,SAAS,YAAY,CAAC,QAAgB;IACpC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,IAAI,CAAC,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9C,IAAI,QAAQ,CAAC,CAAC,CAAC,KAAK,GAAG;YAAE,KAAK,IAAI,CAAC,CAAC;aAC/B,IAAI,QAAQ,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;YAC7B,KAAK,IAAI,CAAC,CAAC;YACX,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;gBAChB,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;gBAC/C,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;YACvG,CAAC;QACH,CAAC;IACH,CAAC;IACD,MAAM,IAAI,KAAK,CAAC,wBAAwB,QAAQ,EAAE,CAAC,CAAC;AACtD,CAAC;AAED,IAAI,CAAC,wGAAwG,EAAE,GAAG,EAAE;IAClH,MAAM,OAAO,GAAG,IAAI,OAAO,EAAE,CAAC;IAC9B,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,KAAK,MAAM,CAAC,OAAO,EAAE,GAAG,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,CAAC;QACvD,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QAClD,MAAM,MAAM,GAAG,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7C,MAAM,UAAU,GAAG,sBAAsB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrD,MAAM,IAAI,GAAG,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxC,MAAM,UAAU,GAAG,MAAM,KAAK,IAAI;YAChC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,aAAa,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,CAAC,CAAE,CAAC;YACpD,CAAC,CAAC,UAAU,KAAK,IAAI;gBACnB,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAE,EAAE,UAAU,CAAC,CAAC,CAAE,CAAC;gBAC7C,CAAC,CAAC,IAAI,KAAK,IAAI;oBACb,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,CAAE,CAAC;oBAClC,CAAC,CAAC,EAAE,CAAC;QACX,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC5B,QAAQ,CAAC,IAAI,CAAC,GAAG,OAAO,4BAA4B,IAAI,EAAE,CAAC,CAAC;YAC5D,SAAS;QACX,CAAC;QACD,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC;QAC/C,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC;QACvC,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC;QAC7C,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,QAAQ,EAAE,EAAE;YAC7B,MAAM,IAAI,GAAG,aAAa,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACrC,IAAI,IAAI,KAAK,IAAI;gBAAE,OAAO,CAAG,kDAAkD;YAC/E,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;YAC1B,IAAI,CAAC,KAAK,CAAC,IAAI,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;gBAAE,OAAO,CAAG,4DAA4D;YACvG,sFAAsF;YACtF,MAAM,KAAK,GAAG,IAAI,GAAG,EAAQ,CAAC;YAC9B,KAAK,MAAM,GAAG,IAAI,UAAU,EAAE,CAAC;gBAC7B,MAAM,CAAC,GAAG,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAE,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;gBAC3G,IAAI,CAAC,KAAK,SAAS;oBAAE,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;YACjD,CAAC;YACD,MAAM,KAAK,GAAG,GAAG,OAAO,UAAU,CAAC,KAAK,GAAG,OAAO,GAAG,CAAC,QAAQ,GAAG,CAAC;YAClE,gGAAgG;YAChG,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;YACpJ,sBAAsB;YACtB,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,OAAO,CAAC;YAC7E,IAAI,OAAO,KAAK,SAAS;gBAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,2BAA2B,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;iBACjG,IAAI,OAAO,KAAK,KAAK;gBAAE,QAAQ,CAAC,IAAI,CAAC,GAAG,KAAK,OAAO,OAAO,uBAAuB,KAAK,eAAe,CAAC,CAAC;QAC/G,CAAC,CAAC,CAAC;IACL,CAAC;IACD,MAAM,CAAC,SAAS,CAAC,QAAQ,EAAE,EAAE,EAAE,OAAO,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;AACjE,CAAC,CAAC,CAAC"}

package/dist/src/codegen/types.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * Printing East type VALUES as TypeScript type-constructor source (#628).
+ *
+ * The IR carries every type as an `EastTypeValue` — the homoiconic value of
+ * `EastTypeType` — and the printer needs the TypeScript expression that
+ * rebuilds it: `ArrayType(IntegerType)`, `StructType({ a: IntegerType })`,
+ * `OptionType(T)` for the exact Option shape, `RecursiveType(self => ...)`
+ * for a recursive wrapper (nested wrappers name their self-references
+ * `self`, `self2`, ...). A recursive `ref` resolves to the enclosing
+ * wrapper's lambda parameter; a free ref (a fragment lifted out of its
+ * wrapper) is an error. The python twin is `east/codegen/types.py`.
+ */
+import type { EastTypeValue } from "../type_of_type.js";
+import { type Doc } from "./doc.js";
+/** The names a printed module imports from `@elaraai/east` for type source. */
+export declare const TYPE_IMPORTS: readonly ["NullType", "NeverType", "BooleanType", "IntegerType", "FloatType", "StringType", "DateTimeType", "BlobType", "ArrayType", "SetType", "DictType", "StructType", "VariantType", "OptionType", "RefType", "VectorType", "MatrixType", "FunctionType", "AsyncFunctionType", "RecursiveType"];
+/** Whether `t` is the exact Option shape: `Variant{ none: Null, some: T }`. */
+export declare function isOptionValue(t: EastTypeValue): boolean;
+/** A struct field / variant case name as a JavaScript object key. */
+export declare function objectKey(name: string): string;
+/**
+ * An East type value as the layout document of the TypeScript source that
+ * rebuilds it: a struct, variant or parameter list breaks one entry per
+ * line when the line it sits on would pass the width (`codegen/doc`).
+ *
+ * @param t - The type value (the `type` field of an IR node, a type parameter)
+ * @param scope - The stack of enclosing recursive wrappers as `[id, parameter name]`
+ * @returns The document; {@link typeSource} is its one-line rendering
+ * @throws {Error} When a recursive `ref` has no enclosing wrapper in `scope`
+ */
+export declare function typeDoc(t: EastTypeValue, scope?: [bigint, string][]): Doc;
+/**
+ * Prints an East type value as the TypeScript source that rebuilds it, on
+ * one line.
+ *
+ * @param t - The type value (the `type` field of an IR node, a type parameter)
+ * @param scope - The stack of enclosing recursive wrappers as `[id, parameter name]`
+ * @returns TypeScript source such as `DictType(StringType, ArrayType(IntegerType))`
+ * @throws {Error} When a recursive `ref` has no enclosing wrapper in `scope`
+ *
+ * @example
+ * ```ts
+ * typeSource(toEastTypeValue(ArrayType(OptionType(IntegerType))));
+ * // "ArrayType(OptionType(IntegerType))"
+ * ```
+ */
+export declare function typeSource(t: EastTypeValue, scope?: [bigint, string][]): string;
+/**
+ * A structural key for deduplicating hoisted type constants: two type values
+ * that print to the same source rebuild the same type, whatever recursive
+ * ids they were minted with.
+ */
+export declare function typeKey(t: EastTypeValue): string;
+/**
+ * Adds to `into` the constructor names `typeSource(t)` spells — what a
+ * printed module must import for the type. A walk over the type, case for
+ * case with {@link typeSource}.
+ *
+ * @param t - The type value
+ * @param into - The set of imported names being collected
+ */
+export declare function typeConstructors(t: EastTypeValue, into: Set<string>): void;
+//# sourceMappingURL=types.d.ts.map

package/dist/src/codegen/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/codegen/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,KAAK,GAAG,EAAiB,MAAM,UAAU,CAAC;AAEnD,+EAA+E;AAC/E,eAAO,MAAM,YAAY,qSAKf,CAAC;AAOX,+EAA+E;AAC/E,wBAAgB,aAAa,CAAC,CAAC,EAAE,aAAa,GAAG,OAAO,CAKvD;AAID,qEAAqE;AACrE,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,aAAa,EAAE,KAAK,GAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAO,GAAG,GAAG,CAwC7E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,aAAa,EAAE,KAAK,GAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAO,GAAG,MAAM,CAEnF;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,aAAa,GAAG,MAAM,CAEhD;AAED;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI,CAmD1E"}

package/dist/src/codegen/types.js

@@ -0,0 +1,173 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import { bracket, flat } from "./doc.js";
+/** The names a printed module imports from `@elaraai/east` for type source. */
+export const TYPE_IMPORTS = [
+    "NullType", "NeverType", "BooleanType", "IntegerType", "FloatType", "StringType",
+    "DateTimeType", "BlobType", "ArrayType", "SetType", "DictType", "StructType",
+    "VariantType", "OptionType", "RefType", "VectorType", "MatrixType", "FunctionType",
+    "AsyncFunctionType", "RecursiveType",
+];
+const PRIMITIVES = {
+    Null: "NullType", Never: "NeverType", Boolean: "BooleanType", Integer: "IntegerType",
+    Float: "FloatType", String: "StringType", DateTime: "DateTimeType", Blob: "BlobType",
+};
+/** Whether `t` is the exact Option shape: `Variant{ none: Null, some: T }`. */
+export function isOptionValue(t) {
+    if (t.type !== "Variant")
+        return false;
+    const cases = t.value;
+    return cases.length === 2 && cases[0].name === "none" && cases[0].type.type === "Null"
+        && cases[1].name === "some";
+}
+const IDENT = /^[A-Za-z_$][\w$]*$/;
+/** A struct field / variant case name as a JavaScript object key. */
+export function objectKey(name) {
+    return IDENT.test(name) ? name : JSON.stringify(name);
+}
+/**
+ * An East type value as the layout document of the TypeScript source that
+ * rebuilds it: a struct, variant or parameter list breaks one entry per
+ * line when the line it sits on would pass the width (`codegen/doc`).
+ *
+ * @param t - The type value (the `type` field of an IR node, a type parameter)
+ * @param scope - The stack of enclosing recursive wrappers as `[id, parameter name]`
+ * @returns The document; {@link typeSource} is its one-line rendering
+ * @throws {Error} When a recursive `ref` has no enclosing wrapper in `scope`
+ */
+export function typeDoc(t, scope = []) {
+    const kind = t.type;
+    const primitive = PRIMITIVES[kind];
+    if (primitive !== undefined)
+        return primitive;
+    if (kind === "Array" || kind === "Set" || kind === "Ref" || kind === "Vector" || kind === "Matrix") {
+        return [`${kind}Type(`, typeDoc(t.value, scope), ")"];
+    }
+    if (kind === "Dict") {
+        const d = t.value;
+        return ["DictType(", typeDoc(d.key, scope), ", ", typeDoc(d.value, scope), ")"];
+    }
+    if (kind === "Struct") {
+        const fields = t.value
+            .map((f) => [objectKey(f.name), ": ", typeDoc(f.type, scope)]);
+        return ["StructType(", bracket("{", fields, "}", " "), ")"];
+    }
+    if (kind === "Variant") {
+        const cases = t.value;
+        if (isOptionValue(t))
+            return ["OptionType(", typeDoc(cases[1].type, scope), ")"];
+        const parts = cases.map((c) => [objectKey(c.name), ": ", typeDoc(c.type, scope)]);
+        return ["VariantType(", bracket("{", parts, "}", " "), ")"];
+    }
+    if (kind === "Function" || kind === "AsyncFunction") {
+        const f = t.value;
+        const inputs = bracket("[", f.inputs.map(i => typeDoc(i, scope)), "]");
+        return [`${kind}Type(`, inputs, ", ", typeDoc(f.output, scope), ")"];
+    }
+    if (kind === "Recursive") {
+        const payload = t.value;
+        if (payload.type === "ref") {
+            for (let i = scope.length - 1; i >= 0; i--) {
+                if (scope[i][0] === payload.value)
+                    return scope[i][1];
+            }
+            throw new Error(`recursive ref ${payload.value} outside its wrapper`);
+        }
+        const name = scope.length === 0 ? "self" : `self${scope.length + 1}`;
+        const body = typeDoc(payload.value.inner, [...scope, [payload.value.id, name]]);
+        return [`RecursiveType(${name} => `, body, ")"];
+    }
+    throw new Error(`unknown type kind ${kind}`);
+}
+/**
+ * Prints an East type value as the TypeScript source that rebuilds it, on
+ * one line.
+ *
+ * @param t - The type value (the `type` field of an IR node, a type parameter)
+ * @param scope - The stack of enclosing recursive wrappers as `[id, parameter name]`
+ * @returns TypeScript source such as `DictType(StringType, ArrayType(IntegerType))`
+ * @throws {Error} When a recursive `ref` has no enclosing wrapper in `scope`
+ *
+ * @example
+ * ```ts
+ * typeSource(toEastTypeValue(ArrayType(OptionType(IntegerType))));
+ * // "ArrayType(OptionType(IntegerType))"
+ * ```
+ */
+export function typeSource(t, scope = []) {
+    return flat(typeDoc(t, scope));
+}
+/**
+ * A structural key for deduplicating hoisted type constants: two type values
+ * that print to the same source rebuild the same type, whatever recursive
+ * ids they were minted with.
+ */
+export function typeKey(t) {
+    return typeSource(t);
+}
+/**
+ * Adds to `into` the constructor names `typeSource(t)` spells — what a
+ * printed module must import for the type. A walk over the type, case for
+ * case with {@link typeSource}.
+ *
+ * @param t - The type value
+ * @param into - The set of imported names being collected
+ */
+export function typeConstructors(t, into) {
+    const kind = t.type;
+    const primitive = PRIMITIVES[kind];
+    if (primitive !== undefined) {
+        into.add(primitive);
+        return;
+    }
+    if (kind === "Array" || kind === "Set" || kind === "Ref" || kind === "Vector" || kind === "Matrix") {
+        into.add(`${kind}Type`);
+        typeConstructors(t.value, into);
+        return;
+    }
+    if (kind === "Dict") {
+        const d = t.value;
+        into.add("DictType");
+        typeConstructors(d.key, into);
+        typeConstructors(d.value, into);
+        return;
+    }
+    if (kind === "Struct") {
+        into.add("StructType");
+        for (const f of t.value)
+            typeConstructors(f.type, into);
+        return;
+    }
+    if (kind === "Variant") {
+        const cases = t.value;
+        if (isOptionValue(t)) {
+            into.add("OptionType");
+            typeConstructors(cases[1].type, into);
+            return;
+        }
+        into.add("VariantType");
+        for (const c of cases)
+            typeConstructors(c.type, into);
+        return;
+    }
+    if (kind === "Function" || kind === "AsyncFunction") {
+        const f = t.value;
+        into.add(`${kind}Type`);
+        for (const i of f.inputs)
+            typeConstructors(i, into);
+        typeConstructors(f.output, into);
+        return;
+    }
+    if (kind === "Recursive") {
+        const payload = t.value;
+        if (payload.type === "wrapper") {
+            into.add("RecursiveType");
+            typeConstructors(payload.value.inner, into);
+        }
+        return;
+    }
+    throw new Error(`unknown type kind ${kind}`);
+}
+//# sourceMappingURL=types.js.map

package/dist/src/codegen/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/codegen/types.ts"],"names":[],"mappings":"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"}

package/dist/src/expr/block.d.ts

@@ -14,6 +14,7 @@ import { StringExpr } from "./string.js";
 import { ArrayExpr } from "./array.js";
 import { SetExpr } from "./set.js";
 import { DictExpr } from "./dict.js";
+import { RecursiveExpr } from "./recursive.js";
 import { type CallableFunctionExpr, FunctionExpr } from "./function.js";
 import type { PlatformFunction } from "../platform.js";
 import { type EastTypeValue } from "../type_of_type.js";
@@ -150,6 +151,73 @@ export declare const ge: typeof greaterEqual;
  * For immutable data types, such as integers and strings, this is equivalent to equality.
  */
 export declare function is<T>(left: Expr<T>, right: SubtypeExprOrValue<NoInfer<T>>): BooleanExpr;
+/**
+ * Calls an East builtin by name — the raw spelling for a builtin the surface
+ * has no method for, and the form the codegen printers fall back to for one
+ * (`RAW_ONLY`). The python twin is `East.builtin`.
+ *
+ * @param name - The builtin's IR name, e.g. `"ArrayGetKeys"`
+ * @param typeParameters - Its type parameters, in declaration order
+ * @param args - Its arguments in IR order — expressions, values, or callbacks
+ * @param outputType - The type of the result
+ * @returns The `Builtin` expression, typed `outputType`
+ * @throws {Error} When `name` is not a builtin, or the type-parameter or
+ *   argument counts do not match its declaration
+ *
+ * @example
+ * ```ts
+ * const size = East.function([ArrayType(IntegerType)], IntegerType, ($, xs) => {
+ *   $.return(East.builtin("ArraySize", [IntegerType], [xs], IntegerType));
+ * });
+ * const compiled = East.compile(size, []);
+ * compiled([1n, 2n, 3n]);  // 3n
+ * ```
+ */
+export declare function builtin(name: string, typeParameters: EastType[], args: unknown[], outputType: EastType): Expr;
+/**
+ * Widens a value to a declared supertype explicitly — an `As` node. The
+ * builder inserts the same node itself wherever a narrower value meets a
+ * wider declared type (a `$.const(x, T)`, a function argument), so this is
+ * the spelling for the other positions; the codegen printers spell every
+ * IR `As` with it. The python twin is `East.as_`.
+ *
+ * @param value - The value or expression to widen
+ * @param type - The wider type; the value's type must be a subtype of it
+ * @returns The value as an expression of `type`
+ * @throws {Error} When the value's type is not a subtype of `type`
+ *
+ * @example
+ * ```ts
+ * const Shape = VariantType({ circle: FloatType, square: FloatType });
+ * const widen = East.function([FloatType], Shape, ($, r) => {
+ *   $.return(East.as(East.value(variant("circle", r)), Shape));
+ * });
+ * const compiled = East.compile(widen, []);
+ * compiled(2.0);  // variant("circle", 2.0)
+ * ```
+ */
+export declare function as<T extends EastType>(value: SubtypeExprOrValue<NoInfer<T>>, type: T): ExprType<T>;
+/**
+ * Wraps a value or expression of a recursive type's node type in the
+ * recursive type — a `WrapRecursive` node; {@link RecursiveExpr.unwrap} is
+ * its inverse. The python twin is `East.wrap_recursive`.
+ *
+ * @param value - The value or expression of the wrapper's node type
+ * @param type - The recursive type to wrap it in
+ * @returns A `RecursiveExpr` of `type`
+ *
+ * @example
+ * ```ts
+ * const ListType = RecursiveType(self => VariantType({ nil: NullType, cons: StructType({ head: IntegerType, tail: self }) }));
+ * const singleton = East.function([IntegerType], ListType, ($, x) => {
+ *   const nil = $.const(East.wrapRecursive(variant("nil", null), ListType));
+ *   $.return(East.wrapRecursive(variant("cons", { head: x, tail: nil }), ListType));
+ * });
+ * const compiled = East.compile(singleton, []);
+ * compiled(1n);  // variant("cons", { head: 1n, tail: variant("nil", null) })
+ * ```
+ */
+export declare function wrapRecursive<T>(value: SubtypeExprOrValue<T>, type: RecursiveType<T>): RecursiveExpr<T>;
 /** Print a value as a string. */
 export declare function print(value: Expr): StringExpr;
 /** Compute the difference between two values of the same type.
@@ -169,6 +237,50 @@ export declare function composePatch<T extends EastType>(first: Expr<PatchTypeOf
  * Applying the inverted patch to the "after" value produces the "before" value.
  */
 export declare function invertPatch<T extends EastType>(patch: Expr<PatchTypeOf<T>>, type: T): ExprType<PatchTypeOf<T>>;
+/**
+ * The brand every declaration handle carries — a registered symbol, so a
+ * handle built by any copy of `@elaraai/east` in the process is recognised.
+ */
+export declare const PLATFORM_DECLARATION: unique symbol;
+/**
+ * What a platform declaration handle says about itself: the identity of the
+ * `Platform` node a call emits — its registered name, declared input and
+ * output types, asyncness, optionality and (generic) type parameter names —
+ * readable from the handle. A library exports its declarations under its
+ * own names (`Compression.Tar.create` is the handle for `tar_create`), so
+ * anything given the library's exports can spell a call as the library
+ * spells it: the codegen printer does (`toSource`'s `libraries`).
+ */
+export interface PlatformDeclaration {
+    /** The platform function's registered name — the `Platform` node's `name`. */
+    readonly name: string;
+    /** The declared input types (placeholder names for a generic declaration's parameters). */
+    readonly inputs: readonly (EastType | string)[];
+    /** The declared output type (or a placeholder name). */
+    readonly output: EastType | string;
+    /** Whether calls emit an async `Platform` node. */
+    readonly async: boolean;
+    /** Whether compiling succeeds with no implementation provided. */
+    readonly optional: boolean;
+    /** The type parameter names of a generic declaration; absent on a concrete one. */
+    readonly typeParameters?: readonly string[];
+}
+/**
+ * Whether `value` is a platform declaration handle — what `East.platform`,
+ * `East.asyncPlatform`, `East.genericPlatform` and `East.asyncGenericPlatform`
+ * return.
+ *
+ * @param value - Anything
+ * @returns True for a declaration handle, whose identity fields are then typed
+ *
+ * @example
+ * ```ts
+ * const log = East.platform("log", [StringType], NullType);
+ * isPlatformDeclaration(log);   // true
+ * log.name;                     // "log"
+ * ```
+ */
+export declare function isPlatformDeclaration(value: unknown): value is PlatformDeclaration;
 /** Callable helper type for synchronous platform functions. */
 export type PlatformDefinition<Inputs extends EastType[], Output extends EastType> = ((...args: {
     [K in keyof Inputs]: SubtypeExprOrValue<Inputs[K]>;
@@ -176,6 +288,14 @@ export type PlatformDefinition<Inputs extends EastType[], Output extends EastTyp
     implement: (fn: (...args: {
         [K in keyof Inputs]: ValueTypeOf<Inputs[K]>;
     }) => Output extends NullType ? null | undefined | void : ValueTypeOf<Output>) => PlatformFunction;
+    /** The registered platform function name. */
+    readonly name: string;
+    /** The declared input types. */
+    readonly inputs: Inputs;
+    /** The declared output type. */
+    readonly output: Output;
+    readonly async: false;
+    readonly optional: boolean;
 };
 /** Options for defining platform functions. */
 export interface PlatformOptions {
@@ -237,6 +357,14 @@ export type AsyncPlatformDefinition<Inputs extends EastType[], Output extends Ea
     implement: (fn: (...args: {
         [K in keyof Inputs]: ValueTypeOf<Inputs[K]>;
     }) => Output extends NullType ? Promise<null | undefined | void> : Promise<ValueTypeOf<Output>>) => PlatformFunction;
+    /** The registered platform function name. */
+    readonly name: string;
+    /** The declared input types. */
+    readonly inputs: Inputs;
+    /** The declared output type. */
+    readonly output: Output;
+    readonly async: true;
+    readonly optional: boolean;
 };
 /** Create a callable helper to invoke an asynchronous platform function.
  *
@@ -298,6 +426,16 @@ export type GenericPlatformDefinition<TParams extends readonly string[], Inputs
     implement: (factory: (...typeParams: {
         [K in keyof TParams]: EastTypeValue;
     }) => (...args: unknown[]) => unknown) => PlatformFunction;
+    /** The registered platform function name. */
+    readonly name: string;
+    /** The type parameter names. */
+    readonly typeParameters: TParams;
+    /** The declared input types, placeholders included. */
+    readonly inputs: Inputs;
+    /** The declared output type, or a placeholder. */
+    readonly output: Output;
+    readonly async: false;
+    readonly optional: boolean;
 };
 /** Create a callable helper to invoke a generic (polymorphic) platform function.
  *
@@ -367,6 +505,16 @@ export type AsyncGenericPlatformDefinition<TParams extends readonly string[], In
     implement: (factory: (...typeParams: {
         [K in keyof TParams]: EastTypeValue;
     }) => (...args: unknown[]) => Promise<unknown>) => PlatformFunction;
+    /** The registered platform function name. */
+    readonly name: string;
+    /** The type parameter names. */
+    readonly typeParameters: TParams;
+    /** The declared input types, placeholders included. */
+    readonly inputs: Inputs;
+    /** The declared output type, or a placeholder. */
+    readonly output: Output;
+    readonly async: true;
+    readonly optional: boolean;
 };
 /** Create a callable helper to invoke an asynchronous generic (polymorphic) platform function.
  *