@elaraai/e3-types 1.0.4 → 1.0.6

package/src/package.ts

@@ -15,7 +15,7 @@
  * - **Task**: A computation with input/output paths (stored separately)
  */
 
-import { StructType, StringType, IntegerType, VariantType, NullType, DictType, ValueTypeOf } from '@elaraai/east';
+import { StructType, StringType, IntegerType, VariantType, NullType, DictType, ValueTypeOf, decodeBeast2For } from '@elaraai/east';
 import { DatasetRefType } from './dataset-ref.js';
 import { StructureType } from './structure.js';
 
@@ -77,11 +77,50 @@ export const PackageObjectType = StructType({
   tasks: DictType(StringType, StringType),
   /** Data structure and initial values */
   data: PackageDataType,
+  /** Functions defined in this package: name -> FunctionObject hash.
+   *  BEAST2 encodes struct fields positionally in declaration order, so this
+   *  field MUST stay last — never insert between `tasks` and `data`. */
+  functions: DictType(StringType, StringType),
 });
 export type PackageObjectType = typeof PackageObjectType;
 
 export type PackageObject = ValueTypeOf<typeof PackageObjectType>;
 
+/**
+ * The pre-`functions` package object wire shape, kept only so
+ * {@link decodePackageObject} can read packages exported before functions
+ * existed.
+ */
+const LegacyPackageObjectType = StructType({
+  tasks: DictType(StringType, StringType),
+  data: PackageDataType,
+});
+
+const decodeCurrent = decodeBeast2For(PackageObjectType);
+const decodeLegacy = decodeBeast2For(LegacyPackageObjectType);
+
+/**
+ * Decode a `PackageObject` from BEAST2 bytes, tolerating the pre-`functions`
+ * wire format (dual-decode migration).
+ *
+ * Every package-read path — local AND cloud — must use this instead of
+ * `decodeBeast2For(PackageObjectType)` directly, so packages exported before
+ * the `functions` field existed keep decoding. Old bytes decode with
+ * `functions` defaulted to an empty map.
+ */
+export function decodePackageObject(data: Uint8Array): PackageObject {
+  try {
+    return decodeCurrent(data);
+  } catch (err) {
+    try {
+      const legacy = decodeLegacy(data);
+      return { tasks: legacy.tasks, data: legacy.data, functions: new Map() };
+    } catch {
+      throw err; // neither shape — surface the current-format error
+    }
+  }
+}
+
 // =============================================================================
 // Package Transfer Types
 // =============================================================================

package/src/runner.ts

@@ -0,0 +1,56 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+
+/**
+ * Runner wire types for e3 functions.
+ *
+ * `RunnerType` is the wire image of the SDK's `Runner` union (minus its
+ * `custom` raw-argv runtime — see the security note below). It pins the
+ * executable to a known runtime for every tag, so a function call can never
+ * name its own executable; only platform flags vary.
+ *
+ * A `platforms` entry is just a `-p <name>` flag on the wire; the SDK's
+ * `Platform<Known> | { custom }` distinction is authoring sugar that
+ * collapses to a string.
+ */
+
+import { VariantType, StructType, ArrayType, StringType, ValueTypeOf } from '@elaraai/east';
+
+/**
+ * Wire representation of a function's runner.
+ *
+ * Each tag names a known runtime binary; `platforms` are passed as `-p`
+ * flags. There is deliberately no raw-argv case: a resolved-argv field would
+ * let any caller choose the executable and every flag — arbitrary command
+ * execution by construction.
+ */
+export const RunnerType = VariantType({
+  east_node: StructType({ platforms: ArrayType(StringType) }),
+  east_py:   StructType({ platforms: ArrayType(StringType) }),
+  east_c:    StructType({ platforms: ArrayType(StringType) }),
+});
+export type RunnerType = typeof RunnerType;
+
+export type RunnerValue = ValueTypeOf<typeof RunnerType>;
+
+function flags(platforms: string[]): string[] {
+  return platforms.flatMap((p) => ['-p', p]);
+}
+
+/**
+ * Resolve a {@link RunnerType} value to the argv prefix (the wire-value
+ * analogue of the SDK's `runnerToCommand`). Lives in e3-types so both
+ * e3-core (local) and the cloud execution kernel import the one resolver.
+ *
+ * Variant tags use underscores (`east_node`) mapped to the binary name
+ * (`east-node`) here.
+ */
+export function runnerToArgv(r: RunnerValue): string[] {
+  switch (r.type) {
+    case 'east_node': return ['east-node', 'run', ...flags(r.value.platforms)];
+    case 'east_py':   return ['east-py',   'run', ...flags(r.value.platforms)];
+    case 'east_c':    return ['east-c',    'run', ...flags(r.value.platforms)];
+  }
+}