@lotics/app-sdk 0.101.0 → 0.101.2

package/dist/index.js

@@ -16355,6 +16355,7 @@ function numberUnitRefusal(format2, unit) {
 function effectiveSelectOptions(field) {
   if (field === void 0) return null;
   if (field.type === "select") return field.options ?? null;
+  if (field.type === "formula") return field.formula?.options ?? null;
   if (field.type === "lookup" && field.lookup_field_type === "select") {
     return field.lookup_field_options ?? null;
   }
@@ -19152,6 +19153,9 @@ function resolveFilterType(field) {
           return "date";
         case "boolean":
           return "boolean";
+        // Its cell is a single select's: `[key]`.
+        case "select":
+          return "select";
         default:
           return "text";
       }
@@ -19399,7 +19403,7 @@ var tableLookupFieldSchema = tableFieldBaseSchema.extend({
 var tableFilesFieldSchema = tableFieldBaseSchema.extend({
   type: zod_default.literal("files").describe("Field type for file attachments (images, PDFs, documents)")
 });
-var formulaOutputTypeSchema = zod_default.enum(["number", "text", "date", "datetime", "boolean"]);
+var formulaOutputTypeSchema = zod_default.enum(["number", "text", "date", "datetime", "boolean", "select"]);
 var formulaInputSchema = zod_default.object({
   expression: zod_default.string().describe(
     "JavaScript expression. Uses {Field Name} for field references."
@@ -19410,10 +19414,13 @@ var formulaInputSchema = zod_default.object({
   currency: zod_default.string().optional().describe("ISO 4217 currency code, e.g. USD, VND, EUR"),
   unit: zod_default.string().optional().describe(UNIT_DESCRIPTION),
   unit_field: zod_default.string().optional().describe(UNIT_FIELD_DESCRIPTION),
-  currency_field: zod_default.string().optional().describe(CURRENCY_FIELD_DESCRIPTION)
+  currency_field: zod_default.string().optional().describe(CURRENCY_FIELD_DESCRIPTION),
+  options: zod_default.array(tableSelectFieldOptionSchema).min(1).optional().describe(
+    "The categories the formula yields, drawn as a single select's options are. The expression yields one option's `key` (text) or null; a key it does not declare computes an error. Omit for a formula yielding a plain value."
+  )
 });
 var formulaSchema = formulaInputSchema.extend({
-  output_type: formulaOutputTypeSchema.optional().describe("Output type of the formula. Inferred by the backend from the expression \u2014 read-only on input. `datetime` when the result carries a time of day (references a datetime field or a time-bearing helper)."),
+  output_type: formulaOutputTypeSchema.optional().describe("Output type of the formula. Inferred by the backend from the expression \u2014 read-only on input. `datetime` when the result carries a time of day (references a datetime field or a time-bearing helper); `select` when the formula declares `options`."),
   volatile: zod_default.boolean().optional().describe("Whether the formula's result depends on `now()` or other non-deterministic helpers. Inferred by the backend \u2014 read-only on input.")
 });
 var tableFormulaFieldSchema = tableFieldBaseSchema.extend({
@@ -19490,6 +19497,11 @@ var tableFieldInputSchema = zod_default.discriminatedUnion("type", [
   tableAutonumberFieldSchema
 ]);
 var tableFieldsSchema = zod_default.array(tableFieldSchema);
+function selectOptionsOf(field) {
+  if (field.type === "select") return field.options;
+  if (field.type === "formula") return field.formula.options;
+  return void 0;
+}
 var tableFieldCreateBaseSchema = zod_default.object({
   name: zod_default.string().describe("Display name"),
   description: zod_default.string().describe("Field description"),
@@ -19634,6 +19646,10 @@ function projectCell(field, value) {
     case "select_member":
       if (field.multi === true || !Array.isArray(value)) return value;
       return value.length === 0 ? null : value[0];
+    // A formula yielding one of its options holds a single select's cell.
+    case "formula":
+      if (field.formula.options === void 0 || !Array.isArray(value)) return value;
+      return value.length === 0 ? null : value[0];
     case "select_record_link":
       return Array.isArray(value) ? extractRecordLinkIds(value) : value;
     default:
@@ -25463,6 +25479,7 @@ async function evaluateRead(source, path, coerce, ctx) {
   return current;
 }
 function isScalarWrappedField(field) {
+  if (field.type === "formula") return field.formula.options !== void 0;
   return (field.type === "select" || field.type === "select_member") && field.multi !== true;
 }
 function unwrapScalarField(value) {
@@ -25485,7 +25502,10 @@ async function coerceFieldDisplay(value, field, ctx) {
   if (value === null || value === void 0) return value;
   switch (field.type) {
     case "select":
-      return coerceSelectDisplay(value, field);
+      return coerceSelectDisplay(value, field.options);
+    // One of its own options, named as a select's is.
+    case "formula":
+      return field.formula.options === void 0 ? value : coerceSelectDisplay(value, field.formula.options);
     case "select_record_link":
       return coerceRecordLinkDisplay(value, field, ctx);
     case "select_member":
@@ -25496,8 +25516,8 @@ async function coerceFieldDisplay(value, field, ctx) {
       return value;
   }
 }
-function coerceSelectDisplay(value, field) {
-  const optionMap = new Map(field.options.map((o) => [o.key, o.name]));
+function coerceSelectDisplay(value, options) {
+  const optionMap = new Map(options.map((o) => [o.key, o.name]));
   const resolve = (key) => {
     if (typeof key !== "string") return "";
     return optionMap.get(key) ?? key;
@@ -27317,6 +27337,10 @@ function getFieldDisplayValue(field, value) {
       return option?.name ?? selectValues[0] ?? "";
     }
     case "formula": {
+      if (field.formula.options !== void 0) {
+        const [key] = Array.isArray(value) ? value : [];
+        return key === void 0 ? "" : field.formula.options.find((option) => option.key === key)?.name ?? key;
+      }
       const formulaVal = getFormulaValue(value);
       return formulaVal !== null ? String(formulaVal) : "";
     }
@@ -27408,14 +27432,22 @@ var appWriteModelSchema = zod_default.object({
   tables: zod_default.array(zod_default.object({ id: zod_default.string(), name: zod_default.string(), fields: tableFieldsSchema })).describe("The tables the plans and queries touch, with only the fields they name.")
 });
 var PREDICTION_MISSES_MAX = 50;
-var predictionMissSchema = zod_default.object({
-  workflow: zod_default.string().max(200).describe("The alias of the workflow whose run was predicted."),
-  table_id: zod_default.string().max(64),
-  field_key: zod_default.string().max(64).nullable().describe("The field that missed; null for a whole row."),
-  column: zod_default.enum(["own", "via", "row"]).describe("A field of the row itself, one read through its link, or the row."),
-  kind: zod_default.enum(["cell", "not_removed"]).describe("A predicted value the stored one differs from, or a row predicted gone that the server still holds."),
-  count: zod_default.number().int().min(1).max(1e3)
-});
+var predictionMissSchema = zod_default.union([
+  zod_default.object({
+    kind: zod_default.enum(["cell", "not_removed"]).describe("A predicted value the stored one differs from, or a row predicted gone that the server still holds."),
+    workflow: zod_default.string().max(200).describe("The alias of the workflow whose run was predicted."),
+    table_id: zod_default.string().max(64),
+    field_key: zod_default.string().max(64).nullable().describe("The field that missed; null for a whole row."),
+    column: zod_default.enum(["own", "via", "row"]).describe("A field of the row itself, one read through its link, or the row."),
+    count: zod_default.number().int().min(1).max(1e3)
+  }).strict(),
+  zod_default.object({
+    kind: zod_default.enum(["model_unavailable", "predict_error"]).describe("The app's write model could not be read, or predicting a run threw: its writes wait for the server."),
+    workflow: zod_default.string().max(200).nullable().describe("The workflow whose run was not predicted; null for the model."),
+    error: zod_default.string().regex(/^[A-Za-z_$][\w$]{0,63}$/).describe("The error's class name alone (`TypeError`, `WorkflowEvalError`)."),
+    count: zod_default.number().int().min(1).max(1e3)
+  }).strict()
+]);
 var predictionMissesBodySchema = zod_default.object({ misses: zod_default.array(predictionMissSchema).min(1).max(PREDICTION_MISSES_MAX) });
 
 // src/new_record.ts
@@ -27526,6 +27558,7 @@ function loadModel() {
   attempt2.catch((cause) => {
     console.error("The app's write model could not be read; writes show once the server answers", cause);
     if (modelPromise === attempt2) failedAtMs = Date.now();
+    reportMisses([{ kind: "model_unavailable", workflow: null, error: errorName(cause), count: 1 }]);
   });
   modelPromise = attempt2;
 }
@@ -27687,7 +27720,7 @@ async function stageWrite(workflow, inputs) {
     });
   } catch (cause) {
     if (cause instanceof UnknownValue) return null;
-    console.error(`The write "${workflow}" could not be predicted; it shows once the server answers`, cause);
+    unpredicted(workflow, cause);
     return null;
   }
   if (prediction.outcome === "refused") return null;
@@ -27788,8 +27821,21 @@ function judgePredictions(shape, rows, askedAt) {
   }
   if (checked.size > 0) entries2 = entries2.map((entry) => checked.has(entry.token) ? { ...entry, checked: /* @__PURE__ */ new Set([...entry.checked, ...checked.get(entry.token) ?? []]) } : entry);
   if (counts.size === 0) return;
-  const misses = [...counts.values()].slice(0, PREDICTION_MISSES_MAX);
-  rpc("prediction_miss", { misses }).catch((cause) => console.warn("A drawn write the server stored differently could not be reported", cause));
+  reportMisses([...counts.values()]);
+}
+function errorName(cause) {
+  const name = cause instanceof Error ? cause.name : "";
+  return /^[A-Za-z_$][\w$]{0,63}$/.test(name) ? name : "Error";
+}
+function unpredicted(workflow, cause) {
+  console.error(`The write "${workflow}" could not be predicted; it shows once the server answers`, cause);
+  reportMisses([{ kind: "predict_error", workflow, error: errorName(cause), count: 1 }]);
+}
+function reportMisses(misses) {
+  if (misses.length === 0 || hasMockFlag()) return;
+  rpc("prediction_miss", { misses: misses.slice(0, PREDICTION_MISSES_MAX) }).catch(
+    (cause) => console.warn("Where the app's writes were drawn wrong or not at all could not be reported", cause)
+  );
 }
 function readsAfter(workflow, token2) {
   const described = loaded?.model.workflows[workflow];
@@ -27893,7 +27939,7 @@ async function runStaged(alias, inputs) {
   }
   const given = inputs ?? {};
   const staged = await stageWrite(alias, given).catch((cause) => {
-    console.error(`The write "${alias}" could not be shown before the server answers`, cause);
+    unpredicted(alias, cause);
     return null;
   });
   const token2 = staged?.token ?? null;
@@ -29500,11 +29546,10 @@ function compareFieldValues(aValue, bValue, field, blankPosition = "bottom", ord
   if (aValue === bValue) {
     return 0;
   }
-  if (field.type === "select") {
-    const selectField = field;
-    const options = selectField.options || [];
-    const aSelectArray = aValue;
-    const bSelectArray = bValue;
+  const options = selectOptionsOf(field);
+  if (options !== void 0) {
+    const aSelectArray = Array.isArray(aValue) ? aValue : null;
+    const bSelectArray = Array.isArray(bValue) ? bValue : null;
     const aSelectValue = aSelectArray?.[0];
     const bSelectValue = bSelectArray?.[0];
     const aIsEmpty2 = isArrayFieldEmpty(aSelectArray);
@@ -29661,6 +29706,10 @@ function referencedFieldKeys(expression, fields) {
   return prepareFormulaExpression(expression, fields).referencedKeys;
 }
 
+// ../shared/src/formula_language.ts
+var HELPERS2 = new Set(Object.keys(createTimezoneAwareFunctions()));
+var BY_LOWERCASE = new Map([...HELPERS2].map((name) => [name.toLowerCase(), name]));
+
 // ../shared/src/formula.ts
 function prepareFormulaContext(fields) {
   const formulaFields = fields.filter((field) => field.type === "formula");
@@ -29811,12 +29860,13 @@ function computeFormulaFieldsWithContext(row2, fields, context, linkedTableRecor
       continue;
     }
     const everyReferenceEmpty = referencedKeys.length > 0 && referencedKeys.every((fieldKey) => evaluationContext[fieldKey] === null);
-    const formulaResult = evaluateFormulaWithJS(
+    const evaluated2 = evaluateFormulaWithJS(
       prepared.refs.evaluable,
       { data: evaluationContext },
       timezone,
       everyReferenceEmpty
     );
+    const formulaResult = formulaField.formula.options === void 0 ? evaluated2 : selectResult(formulaField.formula.options, evaluated2);
     result[formulaField.key] = formulaResult;
     if (isFormulaError(formulaResult)) {
       erroredFormulaKeys.add(formulaField.key);
@@ -29835,6 +29885,12 @@ function computeFormulaFieldsWithContext(row2, fields, context, linkedTableRecor
   }
   return result;
 }
+function selectResult(options, evaluated2) {
+  if (evaluated2 === null || evaluated2 === "") return null;
+  if (isFormulaError(evaluated2)) return evaluated2;
+  if (typeof evaluated2 === "string" && options.some((option) => option.key === evaluated2)) return [evaluated2];
+  return `${FORMULA_ERROR_PREFIX}yields ${JSON.stringify(evaluated2)}, which is none of its options (${options.map((option) => option.key).join(", ")})`;
+}
 function normalizeEmptyToNull(value) {
   return isEmptyFieldValue(value) ? null : value;
 }

package/dist/shared_types.d.ts

@@ -4,5 +4,5 @@
  * tarball. Written at every build, never edited.
  */
 export type QueryAggregate = { by?: readonly string[]; day?: string; sum?: string; };
-export type TableField = { key: string; name: string; description: string; type: "number"; format: "number" | "currency" | "percentage"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; currency?: string | null | undefined; unit?: string | null | undefined; unit_field?: string | null | undefined; currency_field?: string | null | undefined; default_value?: number | null | undefined; } | { key: string; name: string; description: string; type: "text"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; unique?: boolean | undefined; format?: "text" | "link" | "markdown" | undefined; default_value?: string | null | undefined; } | { key: string; name: string; description: string; type: "date"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; format?: "date" | "datetime" | "date_range" | "datetime_range" | undefined; timezone?: string | undefined; derive_from?: "created_at" | "updated_at" | undefined; default_value?: string | null | undefined; } | { key: string; name: string; description: string; type: "boolean"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; default_value?: boolean | null | undefined; } | { key: string; name: string; description: string; type: "select"; options: { key: string; name: string; color: "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone"; mark?: { kind: string; name: string; } | undefined; }[]; confirm_before_update?: boolean | undefined; required?: boolean | undefined; multi?: boolean | undefined; default_value?: string[] | null | undefined; } | { key: string; name: string; description: string; type: "select_member"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; multi?: boolean | undefined; default_value?: string[] | null | undefined; } | { key: string; name: string; description: string; type: "select_record_link"; table_id: string; display_field_keys: string[]; confirm_before_update?: boolean | undefined; required?: boolean | undefined; display_field_widths?: Record<string, number> | undefined; paired_field_key?: string | undefined; cardinality?: "one" | "many" | undefined; } | { key: string; name: string; description: string; type: "rollup"; source_field_key: string; aggregate_option: { operation: "count"; field_key?: string | undefined; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique"; field_key: string; } | { operation: "min" | "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range"; field_key: string; } | { operation: "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "earliest" | "latest"; field_key: string; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "selected"; field_key: string; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "selected"; field_key: string; } | { operation: "empty" | "filled" | "percent_empty" | "percent_filled" | "selected"; field_key: string; } | { operation: "checked" | "unchecked" | "percent_checked" | "percent_unchecked"; field_key: string; } | { operation: "empty" | "filled" | "percent_empty" | "percent_filled" | "selected"; field_key: string; } | { operation: "min" | "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range" | "earliest" | "latest" | "checked" | "unchecked" | "percent_checked" | "percent_unchecked"; field_key: string; } | { operation: "min" | "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range" | "earliest" | "latest"; field_key: string; }; confirm_before_update?: boolean | undefined; required?: boolean | undefined; filter?: TableRecordFiltersGroupNode | undefined; aggregate_field_type?: "number" | "boolean" | "text" | "date" | "select" | "select_member" | "select_record_link" | "rollup" | "files" | "formula" | "lookup" | "button" | "autonumber" | undefined; aggregate_field_format?: string | undefined; aggregate_field_currency?: string | undefined; aggregate_field_unit?: string | undefined; aggregate_field_unit_field?: string | undefined; aggregate_field_currency_field?: string | undefined; } | { key: string; name: string; description: string; type: "lookup"; source_field_key: string; lookup_field_key: string; confirm_before_update?: boolean | undefined; required?: boolean | undefined; lookup_field_type?: "number" | "boolean" | "text" | "date" | "select" | "select_member" | "select_record_link" | "rollup" | "files" | "formula" | "lookup" | "button" | "autonumber" | undefined; lookup_field_format?: string | undefined; lookup_field_currency?: string | undefined; lookup_field_unit?: string | undefined; lookup_field_options?: { key: string; name: string; color?: string | undefined; mark?: { kind: string; name: string; } | undefined; }[] | undefined; order_by?: { field_key: string; direction: "asc" | "desc"; } | undefined; } | { key: string; name: string; description: string; type: "files"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; } | { key: string; name: string; description: string; type: "formula"; formula: { expression: string; format?: "number" | "currency" | "percentage" | "link" | undefined; currency?: string | undefined; unit?: string | undefined; unit_field?: string | undefined; currency_field?: string | undefined; output_type?: "number" | "boolean" | "text" | "date" | "datetime" | undefined; volatile?: boolean | undefined; }; confirm_before_update?: boolean | undefined; required?: boolean | undefined; } | { key: string; name: string; description: string; type: "button"; text: string; confirm_before_update?: boolean | undefined; required?: boolean | undefined; workflow_id?: string | null | undefined; } | { key: string; name: string; description: string; type: "autonumber"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; prefix?: string | undefined; padding?: number | undefined; template?: string | undefined; };
+export type TableField = { key: string; name: string; description: string; type: "number"; format: "number" | "currency" | "percentage"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; currency?: string | null | undefined; unit?: string | null | undefined; unit_field?: string | null | undefined; currency_field?: string | null | undefined; default_value?: number | null | undefined; } | { key: string; name: string; description: string; type: "text"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; unique?: boolean | undefined; format?: "text" | "link" | "markdown" | undefined; default_value?: string | null | undefined; } | { key: string; name: string; description: string; type: "date"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; format?: "date" | "datetime" | "date_range" | "datetime_range" | undefined; timezone?: string | undefined; derive_from?: "created_at" | "updated_at" | undefined; default_value?: string | null | undefined; } | { key: string; name: string; description: string; type: "boolean"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; default_value?: boolean | null | undefined; } | { key: string; name: string; description: string; type: "select"; options: { key: string; name: string; color: "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone"; mark?: { kind: string; name: string; } | undefined; }[]; confirm_before_update?: boolean | undefined; required?: boolean | undefined; multi?: boolean | undefined; default_value?: string[] | null | undefined; } | { key: string; name: string; description: string; type: "select_member"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; multi?: boolean | undefined; default_value?: string[] | null | undefined; } | { key: string; name: string; description: string; type: "select_record_link"; table_id: string; display_field_keys: string[]; confirm_before_update?: boolean | undefined; required?: boolean | undefined; display_field_widths?: Record<string, number> | undefined; paired_field_key?: string | undefined; cardinality?: "one" | "many" | undefined; } | { key: string; name: string; description: string; type: "rollup"; source_field_key: string; aggregate_option: { operation: "count"; field_key?: string | undefined; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique"; field_key: string; } | { operation: "min" | "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range"; field_key: string; } | { operation: "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "earliest" | "latest"; field_key: string; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "selected"; field_key: string; } | { operation: "unique" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "selected"; field_key: string; } | { operation: "empty" | "filled" | "percent_empty" | "percent_filled" | "selected"; field_key: string; } | { operation: "checked" | "unchecked" | "percent_checked" | "percent_unchecked"; field_key: string; } | { operation: "empty" | "filled" | "percent_empty" | "percent_filled" | "selected"; field_key: string; } | { operation: "min" | "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range" | "earliest" | "latest" | "checked" | "unchecked" | "percent_checked" | "percent_unchecked"; field_key: string; } | { operation: "min" | "unique" | "date_range" | "empty" | "filled" | "percent_empty" | "percent_filled" | "percent_unique" | "sum" | "avg" | "median" | "max" | "range" | "earliest" | "latest"; field_key: string; }; confirm_before_update?: boolean | undefined; required?: boolean | undefined; filter?: TableRecordFiltersGroupNode | undefined; aggregate_field_type?: "number" | "boolean" | "text" | "date" | "select" | "select_member" | "select_record_link" | "rollup" | "files" | "formula" | "lookup" | "button" | "autonumber" | undefined; aggregate_field_format?: string | undefined; aggregate_field_currency?: string | undefined; aggregate_field_unit?: string | undefined; aggregate_field_unit_field?: string | undefined; aggregate_field_currency_field?: string | undefined; } | { key: string; name: string; description: string; type: "lookup"; source_field_key: string; lookup_field_key: string; confirm_before_update?: boolean | undefined; required?: boolean | undefined; lookup_field_type?: "number" | "boolean" | "text" | "date" | "select" | "select_member" | "select_record_link" | "rollup" | "files" | "formula" | "lookup" | "button" | "autonumber" | undefined; lookup_field_format?: string | undefined; lookup_field_currency?: string | undefined; lookup_field_unit?: string | undefined; lookup_field_options?: { key: string; name: string; color?: string | undefined; mark?: { kind: string; name: string; } | undefined; }[] | undefined; order_by?: { field_key: string; direction: "asc" | "desc"; } | undefined; } | { key: string; name: string; description: string; type: "files"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; } | { key: string; name: string; description: string; type: "formula"; formula: { expression: string; format?: "number" | "currency" | "percentage" | "link" | undefined; currency?: string | undefined; unit?: string | undefined; unit_field?: string | undefined; currency_field?: string | undefined; options?: { key: string; name: string; color: "red" | "orange" | "amber" | "yellow" | "lime" | "green" | "emerald" | "teal" | "cyan" | "sky" | "blue" | "indigo" | "violet" | "purple" | "fuchsia" | "pink" | "rose" | "slate" | "gray" | "zinc" | "neutral" | "stone"; mark?: { kind: string; name: string; } | undefined; }[] | undefined; output_type?: "number" | "boolean" | "text" | "date" | "datetime" | "select" | undefined; volatile?: boolean | undefined; }; confirm_before_update?: boolean | undefined; required?: boolean | undefined; } | { key: string; name: string; description: string; type: "button"; text: string; confirm_before_update?: boolean | undefined; required?: boolean | undefined; workflow_id?: string | null | undefined; } | { key: string; name: string; description: string; type: "autonumber"; confirm_before_update?: boolean | undefined; required?: boolean | undefined; prefix?: string | undefined; padding?: number | undefined; template?: string | undefined; };
 export type TableRecordFilters = TableRecordFiltersConditionNode | TableRecordFiltersTraversalNode | TableRecordFiltersGroupNode;

package/dist/written.d.ts

@@ -44,6 +44,8 @@ export declare function writesRecords(workflow: string): boolean;
  * different times, when its oldest was (`since`).
  */
 export declare function noteAnswer(key: string, alias: string, askedAt: number, rows: readonly Row[], since?: number): void;
+/** A run whose writes wait for the server because predicting it threw: said in the console, reported by class. */
+export declare function unpredicted(workflow: string, cause: unknown): void;
 /**
  * The queries a successful run of `workflow` re-reads: those over a table its body names. Undefined — every
  * mounted query — until the model is read, or where a write names a table only at run time.

package/docs/ai.md

@@ -13,7 +13,7 @@ Don't run a structured extraction through `askAi` (the result is stranded in a c
 
 ## Declared agents — what `useAgentRun` runs
 
-An agent is **declared on the app server-side, by alias**, with the `set_app_agent` tool (removed with `remove_app_agent`) — the one way an agent is bound or changed, each write a new version of the app; a deploy never touches it, and `get_app_agent` reads one back. Invoking an alias that isn't bound fails with a "no agent alias" error naming `set_app_agent`, and a deploy warns about any alias the code calls that is not bound.
+An agent is **declared on the app server-side, by alias**, with the `set_app_agent` tool (removed with `remove_app_agent`) — the one way an agent is bound or changed, each write a new version of the app; a deploy never touches it, and `get_app_agent` reads one back. Invoking an alias that isn't bound fails with a "no agent alias" error naming `set_app_agent`, and a sandbox deploy warns about any alias the code calls that is not bound.
 
 A declaration carries:
 
@@ -38,7 +38,7 @@ A declaration carries:
 
 So an agent that reads or writes records needs a named query or workflow for each thing it touches — the same declaration the app's own UI uses. Declare only what that agent needs; a second agent in the same app can declare a narrower set.
 
-**Typing.** `.lotics/app_agents.d.ts`, generated from the app's live bindings whenever a sandbox session opens on the app, augments the SDK's `AppAgents` (alias → input shape) and `AppAgentResults` (alias → declared output shape) interfaces — `useAgentRun("recognize")` then types both `run(input)` and `output`. An alias it does not carry — every alias, in a project on your own machine — falls back to `Record<string, unknown>` input / `unknown` output.
+**Typing.** `.lotics/app_agents.d.ts`, generated from the app's live bindings whenever a sandbox session opens on the app and by `lotics app create --custom` and `lotics app deploy`, augments the SDK's `AppAgents` (alias → input shape) and `AppAgentResults` (alias → declared output shape) interfaces — `useAgentRun("recognize")` then types both `run(input)` and `output`. An alias it does not carry falls back to `Record<string, unknown>` input / `unknown` output.
 
 ---
 

package/docs/data_fetching.md

@@ -10,9 +10,9 @@ The read model in one paragraph: an app never sends a raw query. It invokes a **
 alias** (bound with `set_app_query`) and fills the template's declared `{{params.x}}`
 value holes; the server holds the canonical AST and runs it under the **app owner's** authority
 ([./security.md](./security.md)). The generated `.lotics/app_queries.d.ts` augments `AppQueries`,
-so an unbound alias is a compile-time error and params are typed per the binding. It is written
-from the app's live bindings whenever a sandbox session opens on the app; a project on your own
-machine has none, so every alias is accepted there as a plain string, untyped. Every hook reads through the SDK's own cache, over the host RPC bridge.
+so params are typed per the binding; an alias it does not carry is accepted as a plain string,
+untyped. It is written from the app's live bindings whenever a sandbox session opens on the app,
+and by `lotics app create --custom` and `lotics app deploy`. Every hook reads through the SDK's own cache, over the host RPC bridge.
 
 ## Choosing a read
 

package/docs/mutations.md

@@ -41,12 +41,11 @@ render: one callable per alias, each run exactly as `useWorkflow`'s.
 
 Typing comes from `.lotics/app_workflows.d.ts`, which augments the SDK's `AppWorkflows` and
 `AppWorkflowResults` interfaces from the app's bound declarations. The declarations are generated from the app's live bindings into `.lotics/` whenever a sandbox
-session opens on the app. A project on your own machine has none, so every alias is accepted as a
-plain string there, untyped. The result:
+session opens on the app, and by `lotics app create --custom` and `lotics app deploy`. The result:
 
 | Declaration | Call-site type |
 |---|---|
-| Alias not declared | Compile-time error at `useWorkflow("...")` |
+| Alias not declared | Accepted as a plain string: untyped `Record<string, unknown>` payload, `unknown` result |
 | Declared with `inputs` | `(inputs: <declared shape>) => Promise<WorkflowResult<TData>>` — inputs required and shaped |
 | Declared with an empty `inputs: {}` | `(inputs?: Record<string, never>)` — call with `{}` or nothing |
 | Declared without `inputs` | Untyped `Record<string, unknown>` payload (and unvalidated server-side — declare inputs for any real workflow) |
@@ -273,8 +272,8 @@ When the alias declares `inputs`, the server validates the payload before the wo
 - **`select` names its option set one of two ways — declare exactly one (both or neither is a
   set-time error).** *Inline* `options: [{label, value}]` freezes the set into the generated
   literal union and is **format-only at run time**: any well-formed key is accepted, and an
-  option added to the live field after deploy is valid at run time but fails the compile-time
-  type (widen or redeploy the declaration when the frozen union gets in the way).
+  option added to the live field after binding is valid at run time but fails the compile-time
+  type (widen or rebind the declaration when the frozen union gets in the way).
   *Field-referenced* `field: "fld_…"` (a select field's global key — `fld_…`, no table prefix)
   is **drift-proof**: the union is resolved from the field's *current* options at type-gen, and
   the submitted value is validated against the field's *current* options at run time — an option
@@ -539,7 +538,8 @@ every read before the request answers:
   asked after the write settled answers — the stored value then replaces the prediction, whatever
   it said, so a server that rounds or trims wins with no flicker back to the old value. Where the
   stored value differs from the one drawn, the SDK tells the server where — the workflow, table,
-  field and kind of miss, never the value.
+  field and kind of miss, never the value. A write model that cannot be read and a prediction that
+  throws are reported too, by the error's class name alone.
 
 What the steps cannot tell before they run is never guessed:
 

package/docs/queries.md

@@ -54,7 +54,7 @@ query's reach (a token in a `table_id` or field-key position fails validation).
 
 ### What deploy validates
 
-Deploy fails — with the compiler's own message, never raw SQL/Postgres text — when any alias:
+Binding fails — with the compiler's own message, never raw SQL/Postgres text — when any alias:
 
 1. isn't a valid identifier, or the declaration isn't `{ ast, params?, description? }` (a
    description over 300 characters is refused here too);
@@ -72,12 +72,12 @@ Deploy fails — with the compiler's own message, never raw SQL/Postgres text
    overrides, `writable_target` on a computed column;
 7. fails to **compile to SQL** — several rejections exist only in the compiler (the expression
    allowlist, link extraction over a composed parent, derived-filter operators with no
-   translation). Deploy compiles every query so these fail at deploy, not at first run;
+   translation). Binding compiles every query so these fail at bind, not at first run;
 8. has optional params and the **pruned** shape (all optional params omitted) fails any of the
    above — each omitted optional param executes a pruned variant of the template, and the
-   all-params shape compiling doesn't prove the pruned one does. Deploy validates both.
+   all-params shape compiling doesn't prove the pruned one does. Binding validates both.
 
-What deploy **cannot** catch: data-dependent failures (a statement timeout on a huge unindexed
+What binding **cannot** catch: data-dependent failures (a statement timeout on a huge unindexed
 scan, the file-presign ceiling) — those surface at run time as clean, safe errors (§10).
 
 ### Execution
@@ -162,7 +162,7 @@ only. Read what a row holds through your projection and the `read*` helpers, nev
 ## 2. The AST node reference
 
 Eleven node kinds. Every node except `from_table` wraps one or more child nodes; each subtree
-compiles to a derived `SELECT`. All structural errors below fail at **deploy** (the output
+compiles to a derived `SELECT`. All structural errors below fail at **bind** (the output
 schema + compile passes run there); only data-dependent errors fail at run time.
 
 ### `from_table` — the only leaf
@@ -179,7 +179,7 @@ Scans one table. Output = one column per field on the table (named by field key,
 plus the system columns. `filter`, `search` (AND-ed with `filter`), `sort`, and `limit` apply
 inside the scan — this is the **source layer**, where the richest operator support and all
 indexes live (§10). `sort` entries are `{ field_key, order: "asc"|"desc", blank_position?:
-"top"|"bottom" }` (blanks default to bottom). Unknown filter/sort field keys fail deploy.
+"top"|"bottom" }` (blanks default to bottom). Unknown filter/sort field keys fail binding.
 
 ### `project` — choose and compute columns
 
@@ -200,7 +200,7 @@ indexes live (§10). `sort` entries are `{ field_key, order: "asc"|"desc", blank
   `type`, is always nullable, and is never writable.
 - Output names must be unique and non-reserved.
 - A passthrough may declare a `type` **override** — realized as a *real, guarded SQL cast*
-  (§4), never a relabel. An uncastable combination is rejected at deploy.
+  (§4), never a relabel. An uncastable combination is rejected at bind.
 - **Project only what you render.** A bare `from_table` ships every column — including `files`
   cells with storage keys — to the client (over-exposure + the presign ceiling at scale).
 - **A files column takes `limit` — bound it when the surface renders a THUMBNAIL, not the
@@ -209,7 +209,7 @@ indexes live (§10). `sort` entries are `{ field_key, order: "asc"|"desc", blank
   without it the response pays to resolve every entry toward the presign ceiling (§10). The bound
   is per CELL, caps at `FILES_PROJECTION_MAX_LIMIT` (10), and is a different axis from the
   query's own `limit`, which counts ROWS; `limit` on any non-`files` column or computed source is
-  rejected at deploy. **On a UNION, set it on every arm** — arms align by name and type, not by
+  rejected at bind. **On a UNION, set it on every arm** — arms align by name and type, not by
   `limit`, so an arm that omits it still yields whole cells.
 
 ### `filter` — predicate over derived columns
@@ -238,7 +238,7 @@ source filter automatically (making it index-servable); otherwise it evaluates p
 
 Single **equality** predicate on one output column per side — no multi-column ON, no
 inequality/range joins. The two ON columns must share a SQL value category (text/number/…);
-mismatches are rejected at deploy (cast one side with a projection type override). Column-name
+mismatches are rejected at bind (cast one side with a projection type override). Column-name
 collisions between the sides are rejected — `project`-rename first. A `left` join makes every
 right-side column nullable. Addressing (write-through, `record_id` filtering) follows the
 **left** side only.
@@ -268,7 +268,7 @@ came from.
 ```
 
 Full semantics in §8. `by` may be empty (a single-row aggregate); `aggregates` needs ≥ 1 entry.
-Aggregate operation × input-column type is validated at deploy. Grouping collapses rows —
+Aggregate operation × input-column type is validated at bind. Grouping collapses rows —
 addressing is dropped.
 
 ### `window` — aggregate without collapsing
@@ -414,7 +414,7 @@ must be valid over `field`'s type — a refusal lists the valid ones.
   (`round`/`floor`/`ceil`/`abs` are 1-arg; `round` rounds to an integer.)
 - **Operators**: `+ - * / %`, `== === != !==`, `< > <= >=`, `&& ||`, `??` (→ `COALESCE`),
   unary `- + !`, and the ternary `cond ? a : b`.
-- **Not supported** (rejected at deploy): indexing `[…]`, nested access (`input.a.b`), list/map
+- **Not supported** (rejected at bind): indexing `[…]`, nested access (`input.a.b`), list/map
   literals, arrow functions, method calls, any other function. Project the raw columns and
   compute client-side instead.
 
@@ -424,7 +424,7 @@ must be valid over `field`'s type — a refusal lists the valid ones.
 ```
 
 Prefer the typed variants where one exists — expressions are strings and get less structural
-validation (though they still compile-check at deploy).
+validation (though they still compile-check at bind).
 
 ---
 
@@ -445,7 +445,7 @@ a **real SQL cast**, guarded so malformed values become NULL instead of aborting
 | `text` → `number` / `boolean` / `date` / `datetime` | guarded cast; a non-conforming value → NULL |
 | `json` → any scalar | via the JSON scalar text, guarded the same way |
 | scalar → `text` / `json` | plain cast |
-| array-valued (`select`/`member`/`link`/`files`) ↔ scalar | **impossible — rejected at deploy** |
+| array-valued (`select`/`member`/`link`/`files`) ↔ scalar | **impossible — rejected at bind** |
 
 The guarded-NULL rule means a query never aborts because one row holds `"n/a"` in a text column
 you cast to number — that row's cell is NULL. Use overrides to align UNION arms or to make a
@@ -469,7 +469,7 @@ derived surfaces share one implementation.
 | select_member | `select_member` | select ops + `is_current_member`, `is_not_current_member` (field-scoped, no value; `is_not_current_member` matches every cell not holding the requester, an empty one included) | same — `is_current_member` **works at the runtime layer** too | `unnest` fans member ids. Anonymous public request: current-member binds the app owner (§1). |
 | select_record_link | `select_record_link` | membership by linked-record **id**: `has_any_of`, `has_none_of`, `has_all_of`; text over the cached **display**: `contains`, `not_contains`, `starts_with`, `ends_with`; `is_empty`, `is_not_empty` | same — id-membership works at the runtime layer (converged `[{id}]` containment) | Sorting orders by raw JSON, not display text — project the display (link extraction / `display_output`) and sort that. `unnest` fans link ids (+ display). |
 | files | `files` | `has_filename`, `has_mime_type` (substring), `has_file_count` (exact count), `is_empty`, `is_not_empty` | same | Presign-enriched at delivery (§1); `unnest` fans file ids. Only presence-counting aggregates. |
-| formula | its declared output type (`number`/`text`/`boolean`/`date`/`datetime`; `json` until inferred) | filtered by the output type's operators; `#ERROR:` cells are guarded — they count as empty and never match value operators | same | Extracted as a real scalar, so numeric formulas feed `sum`/`avg`/sorts. A **datetime-output** formula matches day-level date filters (full-day expansion). |
+| formula | its declared output type (`number`/`text`/`boolean`/`date`/`datetime`, or `select` for one stating its own options, its cell a single select's; `json` until inferred) | filtered by the output type's operators; `#ERROR:` cells are guarded — they count as empty and never match value operators | same | Extracted as a real scalar, so numeric formulas feed `sum`/`avg`/sorts. A **datetime-output** formula matches day-level date filters (full-day expansion). |
 | rollup | decided by the OPERATION, never by the aggregated field: `earliest`/`latest` → `date`/`datetime` per that field's format; **every** other op → `number` | number or date operators per output type; text operators route as text | same | Datetime-format rollups match day-level date filters. `date_range` counts DAYS between the extremes, so it is a number despite its date input. A presence count (`filled`/`empty`/`percent_*`) is a number whatever it counts — including over `files`. |
 | lookup | the type of the VALUE the looked-up field yields — a formula's output type, a rollup's operation result, an autonumber's display string (`text`); never the word `formula`/`rollup` | operators of that type, evaluated with ANY-element semantics over the linked values (a row matches if *any* linked value matches) | array-typed lookups follow their column type's rules | **Projection returns the first element only.** Emptiness on a files-lookup checks the inner file arrays (a linked record with zero files counts empty). For all values across links: unnest the link column + join (§8). |
 | autonumber | `text` | text operators — filter by the visible composed string (`"ORD-0042"`) | same | Sorts numerically when the stored value is a bare integer, lexicographically otherwise — so `"ORD-0042"` orders by its padding and an unprefixed `"124"` orders after `"99"`, not before it. |
@@ -554,7 +554,7 @@ stay index-served. Two access classes:
 Tokens interpolate in **value positions**. A string that *is* exactly one token is replaced by
 the param's typed value (an array param yields an array); a token embedded in a larger string
 interpolates as text. Declared-but-unreferenced params are fine; referenced-but-undeclared
-tokens fail deploy.
+tokens fail binding.
 
 **Composable optional filters (one query, many scopes).** Expose several independent filter
 axes from ONE named query — don't shard into a query-per-combination. Mark each scoping param
@@ -653,7 +653,7 @@ anywhere in the record*.
 ### The 21 aggregate operations
 
 `group` and `window` share one operation vocabulary. `count` is `COUNT(*)` (no `input_column`);
-everything else requires an `input_column` whose type must be compatible — checked at deploy:
+everything else requires an `input_column` whose type must be compatible — checked at bind:
 
 | Operation | Valid input column types | Result | Notes |
 | --- | --- | --- | --- |
@@ -680,7 +680,7 @@ sizes on a shipment, the tags on a ticket) without a second query.
   "distinct": true, "separator": ", ", "max_values": 20 }
 ```
 
-- **`type` must be `text`** — declaring anything else is rejected at deploy.
+- **`type` must be `text`** — declaring anything else is rejected at bind.
 - **`distinct`** defaults to **true**: three containers sized 40HC/40HC/20DC give `20DC, 40HC`.
   Pass `false` to keep every occurrence. Values are always sorted, so the column doesn't
   reshuffle between reads.
@@ -713,7 +713,7 @@ over a `link` read of it is `true`.
 { "bucket": { "source": "created", "granularity": "month", "output": "period" } }
 ```
 
-- `source` must be a `date` or `datetime` **column** of the input (deploy-checked).
+- `source` must be a `date` or `datetime` **column** of the input (checked at bind).
 - `granularity`: `day` | `week` | `month` | `quarter` | `year`. **Weeks are ISO — Monday
   start.**
 - Buckets are computed on the stored **wall-clock** value in the field's timezone (a 23:30
@@ -737,7 +737,7 @@ the timeout for nothing.
 legal SQL window call are accepted: **`count`, `sum`, `avg`, `min`, `max`, `earliest`, `latest`,
 `filled`, `checked`, `unchecked`.** The rest cannot take an OVER clause (`median` is an
 ordered-set aggregate; `unique`/`percent_unique`/`string_agg` need DISTINCT;
-`range`/`empty`/`date_range`/`percent_*` compose multiple calls) — rejected at deploy. The optional `frame` applies **only**
+`range`/`empty`/`date_range`/`percent_*` compose multiple calls) — rejected at bind. The optional `frame` applies **only**
 to these; a `frame` on a window with no `aggregates` is rejected as dead config.
 
 **Window `functions` — ranking / navigation.** Each is `{ "output", "fn", … }` (its own arg shape, no
@@ -751,7 +751,7 @@ to these; a `frame` on a window with no `aggregates` is rejected as dead config.
 | `dense_rank` | — | `number`, non-null. Ties share a rank; the next rank does **not** skip (1,2,2,3). |
 | `percent_rank` / `cume_dist` | — | `number`, non-null. Relative position in [0, 1]. |
 | `ntile` | `buckets` (positive int) | `number`, non-null. The row's bucket (1..buckets) splitting the partition into equal groups. |
-| `lag` / `lead` | `input_column`, `offset?` (int ≥ 1, default 1), `default?` (literal) | the input column's type, **nullable**. The value `offset` rows before / after this one; at the partition edge, `default` if given else NULL. `default`'s type must match the input column (checked at deploy). |
+| `lag` / `lead` | `input_column`, `offset?` (int ≥ 1, default 1), `default?` (literal) | the input column's type, **nullable**. The value `offset` rows before / after this one; at the partition edge, `default` if given else NULL. `default`'s type must match the input column (checked at bind). |
 
 **Top-N per group** — rank within each partition, then filter on the derived rank column:
 
@@ -791,7 +791,7 @@ first. For a fixed, small set of columns, N filtered aggregate queries also work
 
 ## 9. Runtime refinement — filter / sort / limit / offset / count
 
-Each query request carries optional refinement the server wraps **around** the deployed
+Each query request carries optional refinement the server wraps **around** the bound
 template as derived nodes, in this order: `filter` (narrow) → `sort` (order) → `limit`+`offset`
 (page):
 
@@ -857,11 +857,11 @@ ordering and scoping into the template or its params.
 | Statement timeout | **15 s** per query execution | 400: `query timed out after 15s — narrow the filter or simplify the query` |
 | Concurrent query executions | server-configured bulkhead (bounded slots + bounded queue wait) | **503**: `The app is handling too many requests right now. Please retry in a moment.` — a distinct busy-retry outcome; back off and retry |
 | Signed file URLs per response | server-configured, default **2,000 file entries** | 400 naming the alias, the count, and the ceiling — project files columns only where rendered, narrow, or paginate |
-| Traversal depth | 3 hops | **silent match-nothing** — a longer path compiles to `FALSE` (deploys green, returns zero rows) |
-| Param schema depth | 8 | deploy reject |
+| Traversal depth | 3 hops | **silent match-nothing** — a longer path compiles to `FALSE` (binds green, returns zero rows) |
+| Param schema depth | 8 | bind reject |
 
 Any other execution failure returns a generic `query execution failed` (the real error — which
-may embed SQL — is server-logged only). Deploy-time and validation errors are always specific.
+may embed SQL — is server-logged only). Bind-time and validation errors are always specific.
 
 ### Index reality, in plain terms
 
@@ -872,20 +872,21 @@ Records are stored partitioned by workspace, so a query reads only its own works
   layer** — `select`/`select_member`/`select_record_link` `has_any_of` / `has_all_of`, and
   `is_current_member`. These compile to containment the JSONB GIN index serves.
 - **Trigram-served:** `from_table.search` (§7).
-- **B-tree-served (automatic for deployed queries):** text `equals`, number and date
-  comparisons (exact and range), and `sort` fields — for fields referenced in a **deployed
-  named query's template**. The platform provisions a partial expression index per referenced
-  field automatically: built online whenever a query is bound (`set_app_query` or `apply_model`), re-synced daily,
+- **B-tree-served (automatic for bound queries):** text `equals`, number and date
+  comparisons (exact and range), `from_table.sort` fields, and a one-key `sort` node over a
+  number or date field the rows pass unchanged — for fields referenced in a **bound named
+  query's template**. The platform provisions a partial expression index per referenced
+  field automatically: built online whenever `set_app_query` or `set_app_queries` binds a query, re-synced daily,
   capped at 8 per table (fields past the cap fall back to the scan tier, with a server WARN).
   A `{{params.…}}` value hole doesn't change this — the field key is static in the template,
   so it still gets its index. Index-seek speed at any table size once provisioned.
 - **Table scan (linear in table size):** everything else — text `contains`, negations
   (`has_none_of`, `is_none_of`, `not_*`), emptiness, files predicates, and predicates/sorts on
-  fields that appear **only** in the runtime `filter`/`sort` options rather than the deployed
+  fields that appear **only** in the runtime `filter`/`sort` options rather than the bound
   template. Fine on thousands of rows; on very large tables these dominate latency and are the
   usual timeout cause.
 
-**Filter shape drives latency.** Equality/range/sort predicates in the deployed template are
+**Filter shape drives latency.** Equality/range/sort predicates in the bound template are
 index-served; lead with those or a GIN-served membership filter / `search`, and let scan-shaped
 predicates refine the already-narrowed set. Derived-layer filters run over the subquery result
 (no index), so **filter at the source layer whenever the field exists there** — the runtime
@@ -893,14 +894,16 @@ filter is for caller-driven refinement, not for the main cut (a runtime-only fie
 managed index). (The engine pushes eligible filter-over-union predicates down automatically,
 but don't rely on that for other shapes.)
 
-**Sorted, paginated unions are index-served — write them plainly.** A `limit(sort(union(project(from_table) …)))`
-register (the "search all three tables, sort by one column, paginate" shape) is compiled to push
-`ORDER BY … LIMIT` into each arm and `MergeAppend` the per-arm sort-index scans — it does **not**
-scan every arm whole and heap-sort the union. So a single-key sort over a union of tables, each
-projecting that key as a direct field passthrough, is fast at any size. Don't hand-split it into
-per-table queries you merge client-side; the merge already happens in the index. (Requires the
-sort key to be a bare field projection — a computed/literal/type-overridden sort column falls back
-to the whole-union sort.)
+**A sorted page reads in its sort index — declare the order it is read in.** A page sorted by one
+column that passes a number or date field unchanged (a bare `project` source with no `type`
+override, an `unpivot` passthrough, or a row column that reads the same field in every row) reads
+the table in that field's sort index and stops at the page, instead of reading every row and
+sorting. Over a `union`, each arm is paged this way on its own and the arms are merged, so a
+register over several tables or `unpivot` sides is fast at any size — don't hand-split it into
+per-table queries you merge client-side. The index exists when a bound template sorts that field
+in the same direction and blank position: give the query its default order as a top-level `sort`,
+and a page the app sorts the same way is served. A text column, a computed, literal or cast column,
+a sort on more than one key, and a cursor (`keyset`) page sort every row.
 
 **An aggregate arm you cannot filter costs its whole table, every execution.** A `join` whose right
 side is a `group` over entire tables, keyed on a value the LEFT side supplies at run time, has no

package/docs/recipes.md

@@ -85,14 +85,14 @@ Filter **server-side** so the app never receives another row.
 ```
 
 - `{{params.<name>}}` resolves **only in value positions**. A token in `table_id` or `field_key` is
-  not a real identifier and fails the deploy.
+  not a real identifier and fails the binding.
 - `useQuery("lookupShipment", { code })` is reactive on `code`. Gate on a *submitted* code — an
   empty one matches nothing, so render a prompt rather than an empty table.
 - An **autonumber** field stores the composed string (`DL-2026-0006`), so `equals` / `contains`
   filter it directly as text. No reverse mapping.
 
 **A code lookup carries no viewer identity, so it is an enumerable IDOR.** Fine for an internal or
-embedded app; never ship it as a public per-user portal — see `lotics docs security`.
+embedded app; never ship it as a public per-user portal — see [security](./security.md).
 
 ## Compose many optional filter axes in one query
 
@@ -103,7 +103,7 @@ whose `{{params.x}}` the caller did not pass, and collapses emptied groups to ma
 So `useQuery("search", { keyword })` filters by keyword alone, and `{}` returns everything. A
 missing *required* param still fails.
 
-Full pattern, including the date-param trick for range filters: `lotics docs queries` →
+Full pattern, including the date-param trick for range filters: [queries](./queries.md) →
 "Composable optional filters".
 
 ## Decode cells with the accessors, never by hand
@@ -128,7 +128,7 @@ lotics run search_app_icons '{"query":"shipping"}'   → ["truck","ship","packag
 
 `theme.color` is a named palette colour: `red orange amber yellow lime green emerald teal cyan sky
 blue indigo violet purple fuchsia pink rose slate gray zinc neutral stone`. `null` clears either.
-`update_app` sets both; a deploy warns while they are unset.
+`update_app` sets both.
 
 **In-app palette** — the app's own `src/theme.ts`, exact hex. This is what the app *renders* with;
 the launcher colour does not feed it. Pick the named colour closest to your brand hex.

package/docs/security.md

@@ -22,7 +22,7 @@ Comments are the one deliberate exception: access is app-authority (any member w
 
 ## The caller boundary
 
-Callers never submit query ASTs or workflow definitions — the server holds the canonical, deploy-validated template and the caller supplies only an **alias plus typed values**. Three per-input constraints are enforced server-side on **workflow and agent-run inputs** at invocation time, so a hand-crafted request can't redirect a run executing under owner authority:
+Callers never submit query ASTs or workflow definitions — the server holds the canonical, bind-validated template and the caller supplies only an **alias plus typed values**. Three per-input constraints are enforced server-side on **workflow and agent-run inputs** at invocation time, so a hand-crafted request can't redirect a run executing under owner authority:
 
 | Input type | Server-enforced bound |
 |---|---|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.101.0",
+  "version": "0.101.2",
   "description": "The SDK a Lotics custom-code app reads and writes through \u2014 typed hooks over the host bridge, cell readers, mount() and AppRouter",
   "type": "module",
   "exports": {