@elaraai/e3-ui 1.0.84 → 1.0.85

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

@@ -0,0 +1,444 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * The query builder's records and answers (#935): the saved queries a
+ * solution declares as one record, the data sources a query reads, and what a
+ * run of a query answers.
+ *
+ * A saved query is its program as written — a `JqType` tree, never text to
+ * parse again and never the IR the builder translates it to on each run — and
+ * the data sources it reads. Its types are never stored: they are what
+ * checking the program against those data sources gives (#1138). A solution
+ * declares the record as Studio's pages are declared, empty or with its value
+ * from `Query.value`, the queries it ships, checked:
+ *
+ * ```ts
+ * export const queries      = e3.record("queries", Query.Types.Saved, new Map());
+ * export const queriesPatch = e3.mutation.patch(queries);
+ * ```
+ *
+ * The types never depend on the data sources, so a deploy that adds or
+ * changes one runs no migration.
+ *
+ * @packageDocumentation
+ */
+import { ArrayType, BlobType, BooleanType, DateTimeType, DictType, IntegerType, OptionType, StringType, StructType, VariantType } from "@elaraai/east";
+/**
+ * A data source of a query's root: the root field a query reads it by, and
+ * the dataset it is.
+ *
+ * @property name - The root field: `orders` for `.orders`
+ * @property path - The dataset's path in the workspace
+ */
+export declare const QueryRootEntryType: StructType<{
+    readonly name: StringType;
+    readonly path: ArrayType<VariantType<{
+        readonly field: StringType;
+    }>>;
+}>;
+/** Type representing a data source of a query's root. */
+export type QueryRootEntryType = typeof QueryRootEntryType;
+/**
+ * A dataset a run read: its root field, its path, and the hash it was pinned
+ * at, so an answer can be reproduced and a stale one noticed.
+ *
+ * @property hash - The dataset's content hash when the run read it
+ * @property name - Its root field
+ * @property path - Its path in the workspace
+ */
+export declare const QueryInputType: StructType<{
+    readonly hash: StringType;
+    readonly name: StringType;
+    readonly path: ArrayType<VariantType<{
+        readonly field: StringType;
+    }>>;
+}>;
+/** Type representing a dataset a run read. */
+export type QueryInputType = typeof QueryInputType;
+/**
+ * What a run of a query answered.
+ *
+ * @property inputs - The datasets it read, each pinned at its hash, in the
+ *   order the query reads them; empty when nothing ran
+ * @property outcome - How it ended:
+ *   - `error` — the checker's problems, or the error the query raised as it
+ *     ran (`runtime`, located in the jq), or a dataset with no value yet;
+ *   - `needs_platform` — it calls functions this server cannot run;
+ *   - `ok` — `result` is the answer, self-describing beast2; `outputs` counts
+ *     the outputs it holds, and `truncated` says a `many` query gave more than
+ *     it was allowed, the rest left out;
+ *   - `timed_out` — it ran out of time after `ms`;
+ *   - `too_large` — its answer was `bytes` long, over `limit`
+ */
+export declare const QueryResultType: StructType<{
+    readonly inputs: ArrayType<StructType<{
+        readonly hash: StringType;
+        readonly name: StringType;
+        readonly path: ArrayType<VariantType<{
+            readonly field: StringType;
+        }>>;
+    }>>;
+    readonly outcome: VariantType<{
+        readonly error: ArrayType<StructType<{
+            readonly code: StringType;
+            readonly fixes: ArrayType<StructType<{
+                readonly edits: ArrayType<StructType<{
+                    readonly insert: StringType;
+                    readonly length: IntegerType;
+                    readonly offset: IntegerType;
+                }>>;
+                readonly label: StringType;
+            }>>;
+            readonly message: StringType;
+            readonly severity: VariantType<{
+                readonly error: import("@elaraai/east").NullType;
+                readonly warning: import("@elaraai/east").NullType;
+            }>;
+            readonly span: OptionType<StructType<{
+                readonly column: IntegerType;
+                readonly length: IntegerType;
+                readonly line: IntegerType;
+                readonly offset: IntegerType;
+            }>>;
+            readonly suggestions: ArrayType<StringType>;
+        }>>;
+        readonly needs_platform: StructType<{
+            readonly functions: ArrayType<StringType>;
+        }>;
+        readonly ok: StructType<{
+            readonly outputs: IntegerType;
+            readonly result: BlobType;
+            readonly truncated: BooleanType;
+        }>;
+        readonly timed_out: StructType<{
+            readonly ms: IntegerType;
+        }>;
+        readonly too_large: StructType<{
+            readonly bytes: IntegerType;
+            readonly limit: IntegerType;
+        }>;
+    }>;
+}>;
+/** Type representing what a run of a query answered. */
+export type QueryResultType = typeof QueryResultType;
+/**
+ * A saved query.
+ *
+ * @property name - Its name, which is its key in the record
+ * @property description - One sentence, at most 140 characters; with none,
+ *   the sentence generated from its steps shows instead
+ * @property program - The program as written, checked against the whole root
+ *   it was saved on: a query saves only once it checks. Its types are what
+ *   checking it against its data sources gives, and are never stored.
+ * @property root - The data sources it reads, in root order. It opens only
+ *   where each is bound, by the same name and at the same path, so it never
+ *   reads another page's dataset of the same name.
+ * @property saved_at - When it was last saved
+ */
+export declare const SavedQueryType: StructType<{
+    readonly name: StringType;
+    readonly description: OptionType<StringType>;
+    readonly program: import("@elaraai/east").RecursiveType<VariantType<{
+        readonly alternative: StructType<{
+            readonly left: import("@elaraai/east").RecursiveTypeMarker;
+            readonly right: import("@elaraai/east").RecursiveTypeMarker;
+        }>;
+        readonly array: OptionType<import("@elaraai/east").RecursiveTypeMarker>;
+        readonly binary: StructType<{
+            readonly left: import("@elaraai/east").RecursiveTypeMarker;
+            readonly op: StringType;
+            readonly right: import("@elaraai/east").RecursiveTypeMarker;
+        }>;
+        readonly bind: StructType<{
+            readonly body: import("@elaraai/east").RecursiveTypeMarker;
+            readonly patterns: ArrayType<import("@elaraai/east").RecursiveType<VariantType<{
+                readonly array: ArrayType<import("@elaraai/east").RecursiveTypeMarker>;
+                readonly object: ArrayType<StructType<{
+                    readonly key: StringType;
+                    readonly value: OptionType<import("@elaraai/east").RecursiveTypeMarker>;
+                }>>;
+                readonly variable: StringType;
+            }>>>;
+            readonly source: import("@elaraai/east").RecursiveTypeMarker;
+        }>;
+        readonly break: StringType;
+        readonly call: StructType<{
+            readonly args: ArrayType<import("@elaraai/east").RecursiveTypeMarker>;
+            readonly name: StringType;
+        }>;
+        readonly comma: StructType<{
+            readonly left: import("@elaraai/east").RecursiveTypeMarker;
+            readonly right: import("@elaraai/east").RecursiveTypeMarker;
+        }>;
+        readonly def: StructType<{
+            readonly body: import("@elaraai/east").RecursiveTypeMarker;
+            readonly name: StringType;
+            readonly params: ArrayType<StringType>;
+            readonly rest: import("@elaraai/east").RecursiveTypeMarker;
+        }>;
+        readonly descend: import("@elaraai/east").NullType;
+        readonly field: StructType<{
+            readonly name: StringType;
+            readonly optional: BooleanType;
+            readonly target: import("@elaraai/east").RecursiveTypeMarker;
+        }>;
+        readonly foreach: StructType<{
+            readonly extract: OptionType<import("@elaraai/east").RecursiveTypeMarker>;
+            readonly init: import("@elaraai/east").RecursiveTypeMarker;
+            readonly pattern: import("@elaraai/east").RecursiveType<VariantType<{
+                readonly array: ArrayType<import("@elaraai/east").RecursiveTypeMarker>;
+                readonly object: ArrayType<StructType<{
+                    readonly key: StringType;
+                    readonly value: OptionType<import("@elaraai/east").RecursiveTypeMarker>;
+                }>>;
+                readonly variable: StringType;
+            }>>;
+            readonly source: import("@elaraai/east").RecursiveTypeMarker;
+            readonly update: import("@elaraai/east").RecursiveTypeMarker;
+        }>;
+        readonly format: StructType<{
+            readonly name: StringType;
+            readonly string: OptionType<import("@elaraai/east").RecursiveTypeMarker>;
+        }>;
+        readonly identity: import("@elaraai/east").NullType;
+        readonly if: StructType<{
+            readonly branches: ArrayType<StructType<{
+                readonly condition: import("@elaraai/east").RecursiveTypeMarker;
+                readonly then: import("@elaraai/east").RecursiveTypeMarker;
+            }>>;
+            readonly otherwise: OptionType<import("@elaraai/east").RecursiveTypeMarker>;
+        }>;
+        readonly index: StructType<{
+            readonly index: import("@elaraai/east").RecursiveTypeMarker;
+            readonly optional: BooleanType;
+            readonly target: import("@elaraai/east").RecursiveTypeMarker;
+        }>;
+        readonly iterate: StructType<{
+            readonly optional: BooleanType;
+            readonly target: import("@elaraai/east").RecursiveTypeMarker;
+        }>;
+        readonly label: StructType<{
+            readonly body: import("@elaraai/east").RecursiveTypeMarker;
+            readonly name: StringType;
+        }>;
+        readonly literal: VariantType<{
+            readonly boolean: BooleanType;
+            readonly float: import("@elaraai/east").FloatType;
+            readonly integer: IntegerType;
+            readonly null: import("@elaraai/east").NullType;
+            readonly string: StringType;
+        }>;
+        readonly negate: import("@elaraai/east").RecursiveTypeMarker;
+        readonly object: ArrayType<StructType<{
+            readonly key: VariantType<{
+                readonly computed: import("@elaraai/east").RecursiveTypeMarker;
+                readonly name: StringType;
+                readonly variable: StringType;
+            }>;
+            readonly value: OptionType<import("@elaraai/east").RecursiveTypeMarker>;
+        }>>;
+        readonly pipe: StructType<{
+            readonly left: import("@elaraai/east").RecursiveTypeMarker;
+            readonly right: import("@elaraai/east").RecursiveTypeMarker;
+        }>;
+        readonly reduce: StructType<{
+            readonly init: import("@elaraai/east").RecursiveTypeMarker;
+            readonly pattern: import("@elaraai/east").RecursiveType<VariantType<{
+                readonly array: ArrayType<import("@elaraai/east").RecursiveTypeMarker>;
+                readonly object: ArrayType<StructType<{
+                    readonly key: StringType;
+                    readonly value: OptionType<import("@elaraai/east").RecursiveTypeMarker>;
+                }>>;
+                readonly variable: StringType;
+            }>>;
+            readonly source: import("@elaraai/east").RecursiveTypeMarker;
+            readonly update: import("@elaraai/east").RecursiveTypeMarker;
+        }>;
+        readonly slice: StructType<{
+            readonly from: OptionType<import("@elaraai/east").RecursiveTypeMarker>;
+            readonly optional: BooleanType;
+            readonly target: import("@elaraai/east").RecursiveTypeMarker;
+            readonly to: OptionType<import("@elaraai/east").RecursiveTypeMarker>;
+        }>;
+        readonly string: ArrayType<VariantType<{
+            readonly interpolate: import("@elaraai/east").RecursiveTypeMarker;
+            readonly text: StringType;
+        }>>;
+        readonly try: StructType<{
+            readonly body: import("@elaraai/east").RecursiveTypeMarker;
+            readonly catch: OptionType<import("@elaraai/east").RecursiveTypeMarker>;
+        }>;
+        readonly update: StructType<{
+            readonly op: StringType;
+            readonly path: import("@elaraai/east").RecursiveTypeMarker;
+            readonly value: import("@elaraai/east").RecursiveTypeMarker;
+        }>;
+        readonly variable: StringType;
+    }>>;
+    readonly root: ArrayType<StructType<{
+        readonly name: StringType;
+        readonly path: ArrayType<VariantType<{
+            readonly field: StringType;
+        }>>;
+    }>>;
+    readonly saved_at: DateTimeType;
+}>;
+/** Type representing a saved query. */
+export type SavedQueryType = typeof SavedQueryType;
+/**
+ * The saved queries record's type — every saved query, by name. A solution
+ * declares its record with it: `e3.record("queries", Query.Types.Saved, new Map())`.
+ */
+export declare const SavedQueriesType: DictType<StringType, StructType<{
+    readonly name: StringType;
+    readonly description: OptionType<StringType>;
+    readonly program: import("@elaraai/east").RecursiveType<VariantType<{
+        readonly alternative: StructType<{
+            readonly left: import("@elaraai/east").RecursiveTypeMarker;
+            readonly right: import("@elaraai/east").RecursiveTypeMarker;
+        }>;
+        readonly array: OptionType<import("@elaraai/east").RecursiveTypeMarker>;
+        readonly binary: StructType<{
+            readonly left: import("@elaraai/east").RecursiveTypeMarker;
+            readonly op: StringType;
+            readonly right: import("@elaraai/east").RecursiveTypeMarker;
+        }>;
+        readonly bind: StructType<{
+            readonly body: import("@elaraai/east").RecursiveTypeMarker;
+            readonly patterns: ArrayType<import("@elaraai/east").RecursiveType<VariantType<{
+                readonly array: ArrayType<import("@elaraai/east").RecursiveTypeMarker>;
+                readonly object: ArrayType<StructType<{
+                    readonly key: StringType;
+                    readonly value: OptionType<import("@elaraai/east").RecursiveTypeMarker>;
+                }>>;
+                readonly variable: StringType;
+            }>>>;
+            readonly source: import("@elaraai/east").RecursiveTypeMarker;
+        }>;
+        readonly break: StringType;
+        readonly call: StructType<{
+            readonly args: ArrayType<import("@elaraai/east").RecursiveTypeMarker>;
+            readonly name: StringType;
+        }>;
+        readonly comma: StructType<{
+            readonly left: import("@elaraai/east").RecursiveTypeMarker;
+            readonly right: import("@elaraai/east").RecursiveTypeMarker;
+        }>;
+        readonly def: StructType<{
+            readonly body: import("@elaraai/east").RecursiveTypeMarker;
+            readonly name: StringType;
+            readonly params: ArrayType<StringType>;
+            readonly rest: import("@elaraai/east").RecursiveTypeMarker;
+        }>;
+        readonly descend: import("@elaraai/east").NullType;
+        readonly field: StructType<{
+            readonly name: StringType;
+            readonly optional: BooleanType;
+            readonly target: import("@elaraai/east").RecursiveTypeMarker;
+        }>;
+        readonly foreach: StructType<{
+            readonly extract: OptionType<import("@elaraai/east").RecursiveTypeMarker>;
+            readonly init: import("@elaraai/east").RecursiveTypeMarker;
+            readonly pattern: import("@elaraai/east").RecursiveType<VariantType<{
+                readonly array: ArrayType<import("@elaraai/east").RecursiveTypeMarker>;
+                readonly object: ArrayType<StructType<{
+                    readonly key: StringType;
+                    readonly value: OptionType<import("@elaraai/east").RecursiveTypeMarker>;
+                }>>;
+                readonly variable: StringType;
+            }>>;
+            readonly source: import("@elaraai/east").RecursiveTypeMarker;
+            readonly update: import("@elaraai/east").RecursiveTypeMarker;
+        }>;
+        readonly format: StructType<{
+            readonly name: StringType;
+            readonly string: OptionType<import("@elaraai/east").RecursiveTypeMarker>;
+        }>;
+        readonly identity: import("@elaraai/east").NullType;
+        readonly if: StructType<{
+            readonly branches: ArrayType<StructType<{
+                readonly condition: import("@elaraai/east").RecursiveTypeMarker;
+                readonly then: import("@elaraai/east").RecursiveTypeMarker;
+            }>>;
+            readonly otherwise: OptionType<import("@elaraai/east").RecursiveTypeMarker>;
+        }>;
+        readonly index: StructType<{
+            readonly index: import("@elaraai/east").RecursiveTypeMarker;
+            readonly optional: BooleanType;
+            readonly target: import("@elaraai/east").RecursiveTypeMarker;
+        }>;
+        readonly iterate: StructType<{
+            readonly optional: BooleanType;
+            readonly target: import("@elaraai/east").RecursiveTypeMarker;
+        }>;
+        readonly label: StructType<{
+            readonly body: import("@elaraai/east").RecursiveTypeMarker;
+            readonly name: StringType;
+        }>;
+        readonly literal: VariantType<{
+            readonly boolean: BooleanType;
+            readonly float: import("@elaraai/east").FloatType;
+            readonly integer: IntegerType;
+            readonly null: import("@elaraai/east").NullType;
+            readonly string: StringType;
+        }>;
+        readonly negate: import("@elaraai/east").RecursiveTypeMarker;
+        readonly object: ArrayType<StructType<{
+            readonly key: VariantType<{
+                readonly computed: import("@elaraai/east").RecursiveTypeMarker;
+                readonly name: StringType;
+                readonly variable: StringType;
+            }>;
+            readonly value: OptionType<import("@elaraai/east").RecursiveTypeMarker>;
+        }>>;
+        readonly pipe: StructType<{
+            readonly left: import("@elaraai/east").RecursiveTypeMarker;
+            readonly right: import("@elaraai/east").RecursiveTypeMarker;
+        }>;
+        readonly reduce: StructType<{
+            readonly init: import("@elaraai/east").RecursiveTypeMarker;
+            readonly pattern: import("@elaraai/east").RecursiveType<VariantType<{
+                readonly array: ArrayType<import("@elaraai/east").RecursiveTypeMarker>;
+                readonly object: ArrayType<StructType<{
+                    readonly key: StringType;
+                    readonly value: OptionType<import("@elaraai/east").RecursiveTypeMarker>;
+                }>>;
+                readonly variable: StringType;
+            }>>;
+            readonly source: import("@elaraai/east").RecursiveTypeMarker;
+            readonly update: import("@elaraai/east").RecursiveTypeMarker;
+        }>;
+        readonly slice: StructType<{
+            readonly from: OptionType<import("@elaraai/east").RecursiveTypeMarker>;
+            readonly optional: BooleanType;
+            readonly target: import("@elaraai/east").RecursiveTypeMarker;
+            readonly to: OptionType<import("@elaraai/east").RecursiveTypeMarker>;
+        }>;
+        readonly string: ArrayType<VariantType<{
+            readonly interpolate: import("@elaraai/east").RecursiveTypeMarker;
+            readonly text: StringType;
+        }>>;
+        readonly try: StructType<{
+            readonly body: import("@elaraai/east").RecursiveTypeMarker;
+            readonly catch: OptionType<import("@elaraai/east").RecursiveTypeMarker>;
+        }>;
+        readonly update: StructType<{
+            readonly op: StringType;
+            readonly path: import("@elaraai/east").RecursiveTypeMarker;
+            readonly value: import("@elaraai/east").RecursiveTypeMarker;
+        }>;
+        readonly variable: StringType;
+    }>>;
+    readonly root: ArrayType<StructType<{
+        readonly name: StringType;
+        readonly path: ArrayType<VariantType<{
+            readonly field: StringType;
+        }>>;
+    }>>;
+    readonly saved_at: DateTimeType;
+}>>;
+/** Type representing the saved queries record. */
+export type SavedQueriesType = typeof SavedQueriesType;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/query/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EACH,SAAS,EACT,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,QAAQ,EACR,WAAW,EAEX,UAAU,EAEV,UAAU,EACV,UAAU,EACV,WAAW,EACd,MAAM,eAAe,CAAC;AAOvB;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB;;;;;EAG7B,CAAC;AAEH,yDAAyD;AACzD,MAAM,MAAM,kBAAkB,GAAG,OAAO,kBAAkB,CAAC;AAE3D;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc;;;;;;EAIzB,CAAC;AAEH,8CAA8C;AAC9C,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC;AAMnD;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAS1B,CAAC;AAEH,wDAAwD;AACxD,MAAM,MAAM,eAAe,GAAG,OAAO,eAAe,CAAC;AAMrD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAMzB,CAAC;AAEH,uCAAuC;AACvC,MAAM,MAAM,cAAc,GAAG,OAAO,cAAc,CAAC;AAEnD;;;GAGG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAAuC,CAAC;AAErE,kDAAkD;AAClD,MAAM,MAAM,gBAAgB,GAAG,OAAO,gBAAgB,CAAC"}

package/dist/src/query/types.js

@@ -0,0 +1,113 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+/**
+ * The query builder's records and answers (#935): the saved queries a
+ * solution declares as one record, the data sources a query reads, and what a
+ * run of a query answers.
+ *
+ * A saved query is its program as written — a `JqType` tree, never text to
+ * parse again and never the IR the builder translates it to on each run — and
+ * the data sources it reads. Its types are never stored: they are what
+ * checking the program against those data sources gives (#1138). A solution
+ * declares the record as Studio's pages are declared, empty or with its value
+ * from `Query.value`, the queries it ships, checked:
+ *
+ * ```ts
+ * export const queries      = e3.record("queries", Query.Types.Saved, new Map());
+ * export const queriesPatch = e3.mutation.patch(queries);
+ * ```
+ *
+ * The types never depend on the data sources, so a deploy that adds or
+ * changes one runs no migration.
+ *
+ * @packageDocumentation
+ */
+import { ArrayType, BlobType, BooleanType, DateTimeType, DictType, IntegerType, JqType, OptionType, QueryErrorType, StringType, StructType, VariantType, } from "@elaraai/east";
+import { TreePathType } from "@elaraai/e3-types";
+// ============================================================================
+// The root
+// ============================================================================
+/**
+ * A data source of a query's root: the root field a query reads it by, and
+ * the dataset it is.
+ *
+ * @property name - The root field: `orders` for `.orders`
+ * @property path - The dataset's path in the workspace
+ */
+export const QueryRootEntryType = StructType({
+    name: StringType,
+    path: TreePathType,
+});
+/**
+ * A dataset a run read: its root field, its path, and the hash it was pinned
+ * at, so an answer can be reproduced and a stale one noticed.
+ *
+ * @property hash - The dataset's content hash when the run read it
+ * @property name - Its root field
+ * @property path - Its path in the workspace
+ */
+export const QueryInputType = StructType({
+    hash: StringType,
+    name: StringType,
+    path: TreePathType,
+});
+// ============================================================================
+// A run's answer
+// ============================================================================
+/**
+ * What a run of a query answered.
+ *
+ * @property inputs - The datasets it read, each pinned at its hash, in the
+ *   order the query reads them; empty when nothing ran
+ * @property outcome - How it ended:
+ *   - `error` — the checker's problems, or the error the query raised as it
+ *     ran (`runtime`, located in the jq), or a dataset with no value yet;
+ *   - `needs_platform` — it calls functions this server cannot run;
+ *   - `ok` — `result` is the answer, self-describing beast2; `outputs` counts
+ *     the outputs it holds, and `truncated` says a `many` query gave more than
+ *     it was allowed, the rest left out;
+ *   - `timed_out` — it ran out of time after `ms`;
+ *   - `too_large` — its answer was `bytes` long, over `limit`
+ */
+export const QueryResultType = StructType({
+    inputs: ArrayType(QueryInputType),
+    outcome: VariantType({
+        error: ArrayType(QueryErrorType),
+        needs_platform: StructType({ functions: ArrayType(StringType) }),
+        ok: StructType({ outputs: IntegerType, result: BlobType, truncated: BooleanType }),
+        timed_out: StructType({ ms: IntegerType }),
+        too_large: StructType({ bytes: IntegerType, limit: IntegerType }),
+    }),
+});
+// ============================================================================
+// The saved queries
+// ============================================================================
+/**
+ * A saved query.
+ *
+ * @property name - Its name, which is its key in the record
+ * @property description - One sentence, at most 140 characters; with none,
+ *   the sentence generated from its steps shows instead
+ * @property program - The program as written, checked against the whole root
+ *   it was saved on: a query saves only once it checks. Its types are what
+ *   checking it against its data sources gives, and are never stored.
+ * @property root - The data sources it reads, in root order. It opens only
+ *   where each is bound, by the same name and at the same path, so it never
+ *   reads another page's dataset of the same name.
+ * @property saved_at - When it was last saved
+ */
+export const SavedQueryType = StructType({
+    name: StringType,
+    description: OptionType(StringType),
+    program: JqType,
+    root: ArrayType(QueryRootEntryType),
+    saved_at: DateTimeType,
+});
+/**
+ * The saved queries record's type — every saved query, by name. A solution
+ * declares its record with it: `e3.record("queries", Query.Types.Saved, new Map())`.
+ */
+export const SavedQueriesType = DictType(StringType, SavedQueryType);
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/query/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EACH,SAAS,EACT,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,QAAQ,EACR,WAAW,EACX,MAAM,EACN,UAAU,EACV,cAAc,EACd,UAAU,EACV,UAAU,EACV,WAAW,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,+EAA+E;AAC/E,WAAW;AACX,+EAA+E;AAE/E;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,UAAU,CAAC;IACzC,IAAI,EAAE,UAAU;IAChB,IAAI,EAAE,YAAY;CACrB,CAAC,CAAC;AAKH;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,UAAU,CAAC;IACrC,IAAI,EAAE,UAAU;IAChB,IAAI,EAAE,UAAU;IAChB,IAAI,EAAE,YAAY;CACrB,CAAC,CAAC;AAKH,+EAA+E;AAC/E,iBAAiB;AACjB,+EAA+E;AAE/E;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,UAAU,CAAC;IACtC,MAAM,EAAE,SAAS,CAAC,cAAc,CAAC;IACjC,OAAO,EAAE,WAAW,CAAC;QACjB,KAAK,EAAE,SAAS,CAAC,cAAc,CAAC;QAChC,cAAc,EAAE,UAAU,CAAC,EAAE,SAAS,EAAE,SAAS,CAAC,UAAU,CAAC,EAAE,CAAC;QAChE,EAAE,EAAE,UAAU,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,WAAW,EAAE,CAAC;QAClF,SAAS,EAAE,UAAU,CAAC,EAAE,EAAE,EAAE,WAAW,EAAE,CAAC;QAC1C,SAAS,EAAE,UAAU,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC;KACpE,CAAC;CACL,CAAC,CAAC;AAKH,+EAA+E;AAC/E,oBAAoB;AACpB,+EAA+E;AAE/E;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,UAAU,CAAC;IACrC,IAAI,EAAE,UAAU;IAChB,WAAW,EAAE,UAAU,CAAC,UAAU,CAAC;IACnC,OAAO,EAAE,MAAM;IACf,IAAI,EAAE,SAAS,CAAC,kBAAkB,CAAC;IACnC,QAAQ,EAAE,YAAY;CACzB,CAAC,CAAC;AAKH;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC,CAAC"}

package/dist/src/ui.d.ts

@@ -13,10 +13,15 @@
  */
 import { type DatasetDef, type Runner, type TaskDef } from '@elaraai/e3/browser';
 import { UIComponentType } from '@elaraai/east-ui';
-import { type EastType, type CallableFunctionExpr, type CallableAsyncFunctionExpr, variant } from '@elaraai/east';
+import { type CallableFunctionExpr, type CallableAsyncFunctionExpr, variant } from '@elaraai/east';
 /**
  * Create a UI task — an e3 task that produces a UIComponentType value.
  *
+ * Its function returns `UIComponentType`, exactly: a task in the `ui` role is
+ * rendered by its role alone, so its output is never anything else. The
+ * signature takes no other function, and one that slips past it, through a
+ * cast, is refused here, so no package deploys one.
+ *
  * The task's manifest combines:
  * - **Compute-time reads** — every dataset in `inputs` (the runner passes
  *   their values to `fn` as positional args).
@@ -27,6 +32,14 @@ import { type EastType, type CallableFunctionExpr, type CallableAsyncFunctionExp
  * Paths used in `Data.bind` must be JS-side constants captured at IR-build
  * time (typically `e3.input(name, T).path`). Dynamic paths throw.
  *
+ * @param name - The task's name
+ * @param inputs - The datasets the runner passes `fn`, in order
+ * @param fn - Builds the UI component: returns `UIComponentType`
+ * @param options - `runner`, which defaults to east-c with no platforms
+ * @returns The task, whose output is the UI component
+ * @throws {Error} When `fn` returns another type than `UIComponentType`,
+ *   naming the task and the type.
+ *
  * @example
  * ```ts
  * import e3 from '@elaraai/e3';
@@ -51,7 +64,7 @@ import { type EastType, type CallableFunctionExpr, type CallableAsyncFunctionExp
  * // Manifest: { reads: [name.path], writes: [] }
  * ```
  */
-export declare function ui<Name extends string, Inputs extends readonly DatasetDef[], O extends EastType = typeof UIComponentType>(name: Name, inputs: [...Inputs], fn: CallableFunctionExpr<any, O> | CallableAsyncFunctionExpr<any, O>, options?: {
+export declare function ui<Name extends string, Inputs extends readonly DatasetDef[]>(name: Name, inputs: [...Inputs], fn: CallableFunctionExpr<any, UIComponentType> | CallableAsyncFunctionExpr<any, UIComponentType>, options?: {
     runner?: Runner;
-}): TaskDef<O, [variant<'field', 'tasks'>, variant<'field', Name>, variant<'field', 'output'>]>;
+}): TaskDef<UIComponentType, [variant<'field', 'tasks'>, variant<'field', Name>, variant<'field', 'output'>]>;
 //# sourceMappingURL=ui.d.ts.map

package/dist/src/ui.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../../src/ui.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;GAQG;AAMH,OAAO,EAAQ,KAAK,UAAU,EAAE,KAAK,MAAM,EAAE,KAAK,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACvF,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EACL,KAAK,QAAQ,EACb,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,OAAO,EACR,MAAM,eAAe,CAAC;AAIvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,wBAAgB,EAAE,CAChB,IAAI,SAAS,MAAM,EACnB,MAAM,SAAS,SAAS,UAAU,EAAE,EACpC,CAAC,SAAS,QAAQ,GAAG,OAAO,eAAe,EAE3C,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC,EACnB,EAAE,EAAE,oBAAoB,CAAC,GAAG,EAAE,CAAC,CAAC,GAAG,yBAAyB,CAAC,GAAG,EAAE,CAAC,CAAC,EACpE,OAAO,CAAC,EAAE;IACR,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GACA,OAAO,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,CAK7F"}
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../../src/ui.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;GAQG;AAMH,OAAO,EAAQ,KAAK,UAAU,EAAE,KAAK,MAAM,EAAE,KAAK,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACvF,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAKL,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,OAAO,EACR,MAAM,eAAe,CAAC;AAIvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AACH,wBAAgB,EAAE,CAChB,IAAI,SAAS,MAAM,EACnB,MAAM,SAAS,SAAS,UAAU,EAAE,EAEpC,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC,EACnB,EAAE,EAAE,oBAAoB,CAAC,GAAG,EAAE,eAAe,CAAC,GAAG,yBAAyB,CAAC,GAAG,EAAE,eAAe,CAAC,EAChG,OAAO,CAAC,EAAE;IACR,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GACA,OAAO,CAAC,eAAe,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC,CAK3G"}

package/dist/src/ui.js

@@ -17,11 +17,16 @@
 // that reach `ui()` via this package's main barrel (issue #99).
 import { task } from '@elaraai/e3/browser';
 import { UIComponentType } from '@elaraai/east-ui';
-import { variant, } from '@elaraai/east';
+import { Expr, isTypeEqual, printTypeSummary, variant, } from '@elaraai/east';
 import { deriveManifest } from './utils/derive.js';
 /**
  * Create a UI task — an e3 task that produces a UIComponentType value.
  *
+ * Its function returns `UIComponentType`, exactly: a task in the `ui` role is
+ * rendered by its role alone, so its output is never anything else. The
+ * signature takes no other function, and one that slips past it, through a
+ * cast, is refused here, so no package deploys one.
+ *
  * The task's manifest combines:
  * - **Compute-time reads** — every dataset in `inputs` (the runner passes
  *   their values to `fn` as positional args).
@@ -32,6 +37,14 @@ import { deriveManifest } from './utils/derive.js';
  * Paths used in `Data.bind` must be JS-side constants captured at IR-build
  * time (typically `e3.input(name, T).path`). Dynamic paths throw.
  *
+ * @param name - The task's name
+ * @param inputs - The datasets the runner passes `fn`, in order
+ * @param fn - Builds the UI component: returns `UIComponentType`
+ * @param options - `runner`, which defaults to east-c with no platforms
+ * @returns The task, whose output is the UI component
+ * @throws {Error} When `fn` returns another type than `UIComponentType`,
+ *   naming the task and the type.
+ *
  * @example
  * ```ts
  * import e3 from '@elaraai/e3';
@@ -60,6 +73,13 @@ export function ui(name, inputs, fn, options) {
     return buildUiTask(name, inputs, fn, options);
 }
 function buildUiTask(name, inputs, fn, options) {
+    // A ui task is rendered by its role alone, so its output is UIComponentType,
+    // exactly: a function that slipped past the signature is refused (#1118).
+    const output = Expr.type(fn).output;
+    if (!isTypeEqual(output, UIComponentType)) {
+        throw new Error(`ui '${name}': its function returns ${printTypeSummary(output)}, not UIComponentType — ` +
+            `a ui() task's function returns UIComponentType`);
+    }
     const derived = deriveManifest(fn);
     const inputPaths = inputs.map(i => i.path);
     const seen = new Set();