@lotics/app-sdk 0.108.0 → 0.110.0

package/AGENTS.md

@@ -14,7 +14,7 @@ This file is the index. The **exact type** of anything is its shipped declaratio
 
 | Doc | Read it for |
 |---|---|
-| [docs/data_fetching.md](./docs/data_fetching.md) | The reads: `useQuery(alias, params, opts)` — its rows (`limit`), numbered pages (`page`), a keyset feed (`more`), its `total` or the total alone, with `total: { by }` a count per value of one column — `useQueries` for reads known only at render, `queryAll` outside React, `exportQuery` for a file of them the server makes; every hook answers one `QueryState`. The ROW type (`RowOf` — the alias's projected columns and nothing else), runtime `sort`/`filter` keys, cell readers (`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`, `readCreatedAt`/`readUpdatedAt`), the SDK's own cache — **arrival revalidates** — **realtime push**, a write drawn on every read from the press, a count as its own full scan, and the search-as-you-type and record-picker patterns. |
+| [docs/data_fetching.md](./docs/data_fetching.md) | The reads: `useQuery(alias, params, opts)` — its rows (`limit`), numbered pages (`page`), a keyset feed (`more`), its `total` or the total alone, with `total: { by }` a count per value of one column and `total: { where }` a count per named filter, from one scan — `useQueries` for reads known only at render, `queryAll` outside React, `exportQuery` for a file of them the server makes; every hook answers one `QueryState`. The ROW type (`RowOf` — the alias's projected columns and nothing else), runtime `sort`/`filter` keys, cell readers (`row.*`, `readSelect`, `readMembers`, `readLinks`, `readFiles`, `readLocked`, `readCreatedAt`/`readUpdatedAt`), the SDK's own cache — **arrival revalidates** — **realtime push**, a write drawn on every read from the press, a count as its own full scan, and the search-as-you-type and record-picker patterns. |
 | [docs/queries.md](./docs/queries.md) | **The query engine reference** — AST node kinds, per-field-type operators, filters/params/pruning, free-text search, combining tables, shaping (aggregates, date buckets, windows), runtime refinement bounds, limits and the efficiency playbook. |
 | [docs/mutations.md](./docs/mutations.md) | `useWorkflow` (the ONLY write path; `useWorkflows` for writes that are data), the `WorkflowResult` resolve-never-throw contract (`field_errors`), typed inputs, every write drawn on every read from the press — predicted from the workflow's own steps, taken back on a refusal, `pending` meanwhile — the re-read a successful write triggers over the tables its body names, diff-before-update, locked records, `useNewRecord`, read-after-write ordering (`writesSettled()`), `useRecording`, `useRecordings` over several aliases. |
 | [docs/workflows.md](./docs/workflows.md) | **The workflow-BODY reference** — the JS subset a body may use, opaque `fld_*`/`opt_*` keys, every step form, the accepted sugar, helpers, record-write surfaces, the traps and the verify loop. |

package/dist/index.js

@@ -15261,6 +15261,198 @@ function isEmptyFieldValue(value) {
   return false;
 }
 
+// ../shared/src/schemas/files.ts
+var processedFileSchema = zod_default.object({
+  id: zod_default.string().describe("Unique identifier for the processed file"),
+  filename: zod_default.string().describe("Original filename of the uploaded file"),
+  mime_type: zod_default.string().describe("MIME type of the file (e.g., 'image/png', 'application/pdf')"),
+  // Stable proxy URL (`/v1/files/<file_storage_key>`), resolved at serving time
+  // — never stored in the DB.
+  url: zod_default.string().optional().describe("Stable file serving URL, resolved at serving time"),
+  thumbnail_url: zod_default.string().optional().describe("Thumbnail URL for image files, resolved at serving time"),
+  preview_url: zod_default.string().optional().describe("Preview URL for legacy Excel files, resolved at serving time"),
+  provider: zod_default.string().describe("Storage provider name (e.g., 'aws', 'gcs')"),
+  file_storage_key: zod_default.string().describe("Storage key/path where the file is stored"),
+  workspace_id: zod_default.string().describe("ID of the workspace this file belongs to"),
+  size: zod_default.number().nullish().describe("Byte size of the stored object (null until backfilled)"),
+  created_at: zod_default.string().describe("Timestamp when file was uploaded"),
+  metadata: zod_default.unknown().describe("Additional metadata about the file"),
+  data: zod_default.unknown().describe("File-type-specific data (e.g., {width, height, orientation} for images)")
+});
+var fileUploadErrorSchema = zod_default.object({
+  filename: zod_default.string().describe("Original filename that failed to upload"),
+  error: zod_default.string().describe("Error message describing the failure reason")
+});
+var fileUploadResponseSchema = zod_default.object({
+  files: zod_default.array(processedFileSchema).describe("Successfully uploaded files"),
+  errors: zod_default.array(fileUploadErrorSchema).describe("Files that failed to upload with error details")
+});
+var fileFieldValueSchema = zod_default.object({
+  id: zod_default.string().describe("Unique identifier for the file"),
+  /**
+   * Present on a STORED cell and on its way off responses.
+   *
+   * Optional here because this schema types both, and a response is the half
+   * that loses it — no client reads it, and one that required it would reject
+   * the first response without it. Nothing weakens at write time: a file cell
+   * is written from file IDS and `resolveFileFieldIds` mints this from the
+   * `files` row, so a caller never supplies it and a stored cell always has it.
+   * Code that derives a serving URL guards for it (`file_url_resolver.ts`).
+   */
+  file_storage_key: zod_default.string().optional().describe("Storage key for the file"),
+  filename: zod_default.string().describe("Original filename"),
+  mime_type: zod_default.string().describe("MIME type of the file"),
+  url: zod_default.string().optional().describe("Public URL for the file, resolved at serving time"),
+  thumbnail_url: zod_default.string().optional().describe("Thumbnail URL for image files, resolved at serving time"),
+  preview_url: zod_default.string().optional().describe("Preview URL for legacy Excel files, resolved at serving time"),
+  // Immutable file-object metadata, resolved at serving time from the `files`
+  // row (never stored on the denormalized cell) — like `url`. `size` may be
+  // absent for older files not yet backfilled.
+  size: zod_default.number().nullish().describe("Byte size, resolved at serving time from the file object (null/absent until backfilled)"),
+  created_at: zod_default.string().optional().describe("Upload timestamp, resolved at serving time from the file object"),
+  document_template_id: zod_default.string().optional().describe("The document template the file was generated from, resolved at serving time from the file object; absent on a file a person brought")
+});
+function storedFileIds(list2) {
+  if (!Array.isArray(list2)) return [];
+  return list2.flatMap((entry) => {
+    if (typeof entry === "string") return [entry];
+    const id = typeof entry === "object" && entry !== null ? Reflect.get(entry, "id") : void 0;
+    return typeof id === "string" ? [id] : [];
+  });
+}
+function cellFileIds(cell) {
+  if (!Array.isArray(cell)) return [];
+  return cell.flatMap((entry) => Array.isArray(entry) ? cellFileIds(entry) : storedFileIds([entry]));
+}
+var servedFileSchema = zod_default.object({
+  id: zod_default.string(),
+  filename: zod_default.string(),
+  mime_type: zod_default.string(),
+  url: zod_default.string().optional().describe("Serving URL, signed for 24 hours."),
+  thumbnail_url: zod_default.string().optional().describe("Signed thumbnail, for an image."),
+  preview_url: zod_default.string().optional(),
+  size: zod_default.number().nullish().describe("Bytes, where the object records it."),
+  created_at: zod_default.string().optional().describe("When the file was uploaded."),
+  document_template_id: zod_default.string().optional().describe("The document template the file was generated from.")
+});
+var SERVED_FILE_KEYS = servedFileSchema.keyof().options;
+var MAX_UPLOAD_FILE_SIZE = 2 * 1024 * 1024 * 1024;
+var PROFILE_IMAGE_MAX_SIZE = 10 * 1024 * 1024;
+var UPLOAD_TICKET_TTL_SECONDS = 5 * 60;
+var MAX_TICKET_UPLOAD_BYTES = 20 * 1024 * 1024;
+var uploadTicketRequestSchema = zod_default.object({
+  filename: zod_default.string().min(1),
+  mime_type: zod_default.string().optional(),
+  /** Declared up front so an oversize file is refused before its bytes move,
+   *  rather than after the transfer is already spent. Optional because a caller
+   *  streaming from a pipe may genuinely not know; the PUT enforces the cap
+   *  either way. */
+  size_bytes: zod_default.number().int().positive().optional()
+});
+var uploadTicketResponseSchema = zod_default.object({
+  upload_url: zod_default.string(),
+  ticket_id: zod_default.string(),
+  method: zod_default.literal("PUT"),
+  expires_at: zod_default.string(),
+  max_bytes: zod_default.number(),
+  required_headers: zod_default.record(zod_default.string(), zod_default.string())
+});
+var uploadTicketResultSchema = zod_default.object({
+  file_id: zod_default.string(),
+  file_name: zod_default.string(),
+  mime_type: zod_default.string(),
+  size_bytes: zod_default.number(),
+  sha256: zod_default.string(),
+  /** True when these bytes were already in the workspace and no second copy was
+   *  stored. Stated rather than left to inference, because the caller then gets
+   *  back a `file_name` it did not send — the stored file's, not the one it
+   *  uploaded under — and a silent difference reads as a bug. */
+  deduplicated: zod_default.boolean()
+});
+var fileSizeSchema = zod_default.number().int().positive().max(MAX_UPLOAD_FILE_SIZE);
+var directUploadInitRequestSchema = zod_default.object({
+  file_id: zod_default.string().optional(),
+  filename: zod_default.string(),
+  mime_type: zod_default.string(),
+  file_size: fileSizeSchema
+});
+var directUploadInitResponseSchema = zod_default.object({
+  file_id: zod_default.string(),
+  file_storage_key: zod_default.string(),
+  upload_url: zod_default.string()
+});
+var directUploadCompleteRequestSchema = zod_default.object({
+  file_id: zod_default.string(),
+  file_storage_key: zod_default.string(),
+  filename: zod_default.string(),
+  mime_type: zod_default.string(),
+  original_file_id: zod_default.string().optional().describe(
+    "When set, this upload becomes a new version of the original file. The server resolves the current latest, links the new row via source_file_id, and bumps the original's latest_version_id pointer."
+  )
+});
+var multipartInitRequestSchema = zod_default.object({
+  file_id: zod_default.string().optional(),
+  filename: zod_default.string(),
+  mime_type: zod_default.string(),
+  file_size: fileSizeSchema,
+  network_effective_type: zod_default.enum(["slow-2g", "2g", "3g", "4g"]).optional(),
+  network_rtt_ms: zod_default.number().nonnegative().optional()
+});
+var multipartInitResponseSchema = zod_default.object({
+  file_id: zod_default.string(),
+  upload_id: zod_default.string(),
+  file_storage_key: zod_default.string(),
+  part_size: zod_default.number(),
+  parts: zod_default.array(
+    zod_default.object({
+      part_number: zod_default.number(),
+      url: zod_default.string()
+    })
+  )
+});
+var multipartCompleteRequestSchema = zod_default.object({
+  file_id: zod_default.string(),
+  upload_id: zod_default.string(),
+  file_storage_key: zod_default.string(),
+  filename: zod_default.string(),
+  mime_type: zod_default.string(),
+  parts: zod_default.array(
+    zod_default.object({
+      part_number: zod_default.number(),
+      etag: zod_default.string()
+    })
+  ),
+  original_file_id: zod_default.string().optional().describe(
+    "When set, this upload becomes a new version of the original file. The server resolves the current latest, links the new row via source_file_id, and bumps the original's latest_version_id pointer."
+  )
+});
+var multipartAbortRequestSchema = zod_default.object({
+  upload_id: zod_default.string(),
+  file_storage_key: zod_default.string()
+});
+var fileVersionEntrySchema = zod_default.object({
+  id: zod_default.string(),
+  filename: zod_default.string(),
+  /**
+   * Resolved by the server, because deriving it needs the storage key and a
+   * caller that derives is a caller that must be handed one. Every other file
+   * shape already resolves its URL at serving time; this one did not, which is
+   * the whole reason the key still travels here.
+   */
+  url: zod_default.string(),
+  /** @deprecated Unread by any client — resolve bytes through `url` or `id`. */
+  file_storage_key: zod_default.string(),
+  mime_type: zod_default.string(),
+  created_at: zod_default.string(),
+  is_current: zod_default.boolean(),
+  source_file_id: zod_default.string().nullable()
+});
+var fileVersionListResponseSchema = zod_default.object({
+  original_file_id: zod_default.string(),
+  current_version_id: zod_default.string(),
+  versions: zod_default.array(fileVersionEntrySchema).describe("Ordered newest \u2192 oldest. Index 0 is the current version.")
+});
+
 // ../../node_modules/date-fns/constants.js
 var daysInYear = 365.2425;
 var maxTime = Math.pow(10, 8) * 24 * 60 * 60 * 1e3;
@@ -15812,7 +16004,7 @@ function aggregateByField(records, fieldType, option, subject) {
         operation
       );
     case "files":
-      return aggregateGenericField(values2, operation);
+      return aggregateGenericField(values2.map((value) => Array.isArray(value) ? storedFileIds(value) : value), operation);
     case "rollup":
       return aggregateRollupField(
         values2,
@@ -27401,9 +27593,6 @@ function lookupElementToString(element) {
     if (element.length > 0 && typeof element[0] === "object" && element[0] !== null && "display" in element[0]) {
       return element.map((item) => item.display).filter(Boolean).join(", ");
     }
-    if (element.length > 0 && typeof element[0] === "object" && element[0] !== null && "filename" in element[0]) {
-      return element.map((file2) => file2.filename).filter(Boolean).join(", ");
-    }
     return element.filter(Boolean).join(", ");
   }
   return String(element);
@@ -27453,6 +27642,10 @@ function getFieldDisplayValue(field, value) {
     case "lookup": {
       if (typeof value === "string") return value;
       if (!Array.isArray(value)) return String(value);
+      if (field.lookup_field_type === "files") {
+        const count = cellFileIds(value).length;
+        return count === 0 ? "" : `${count} file(s)`;
+      }
       return value.map(lookupElementToString).filter(Boolean).join(", ");
     }
     case "autonumber":
@@ -29015,7 +29208,16 @@ function filterTraversalPaths(filter2) {
   visit(filter2);
   return paths;
 }
-function filterRecords(records, fields, filters, memberContext, traversalContext) {
+var FileNamesUnavailableError = class extends Error {
+  constructor(fieldKey, operator) {
+    super(
+      `Filter on "${fieldKey}": '${operator}' reads a file's name or type, and the cell names its files by id \u2014 the files' rows must be supplied to evaluate it.`
+    );
+    this.name = "FileNamesUnavailableError";
+  }
+};
+var FILE_NAME_OPERATORS = /* @__PURE__ */ new Set(["has_filename", "has_mime_type"]);
+function filterRecords(records, fields, filters, memberContext, traversalContext, fileFacts) {
   if (!filters) {
     return records;
   }
@@ -29027,23 +29229,23 @@ function filterRecords(records, fields, filters, memberContext, traversalContext
     fieldByKey[field.key] = field;
   });
   return records.filter(
-    (record2) => filterRecord(record2, fieldByKey, filters, memberContext, traversalContext)
+    (record2) => filterRecord(record2, fieldByKey, filters, memberContext, traversalContext, fileFacts)
   );
 }
-function filterRecord(record2, fields, filters, memberContext, traversalContext) {
+function filterRecord(record2, fields, filters, memberContext, traversalContext, fileFacts) {
   if (!filters) {
     return true;
   }
   if (filters.node_type !== "group") {
-    const result = evaluateFilterNode(record2, fields, filters, memberContext, traversalContext);
+    const result = evaluateFilterNode(record2, fields, filters, memberContext, traversalContext, fileFacts);
     return result ?? true;
   }
   if (!filters.children || filters.children.length === 0) {
     return true;
   }
-  return evaluateFilterNode(record2, fields, filters, memberContext, traversalContext);
+  return evaluateFilterNode(record2, fields, filters, memberContext, traversalContext, fileFacts);
 }
-function evaluateFilterNode(record2, fields, node, memberContext, traversalContext) {
+function evaluateFilterNode(record2, fields, node, memberContext, traversalContext, fileFacts) {
   if (node.node_type === "group") {
     const evaluatedResults = [];
     for (const child of node.children) {
@@ -29052,7 +29254,8 @@ function evaluateFilterNode(record2, fields, node, memberContext, traversalConte
         fields,
         child,
         memberContext,
-        traversalContext
+        traversalContext,
+        fileFacts
       );
       if (childResult !== null) {
         evaluatedResults.push(childResult);
@@ -29063,14 +29266,14 @@ function evaluateFilterNode(record2, fields, node, memberContext, traversalConte
     }
     return node.logic === "and" ? evaluatedResults.every((result) => result) : evaluatedResults.some((result) => result);
   } else if (node.node_type === "traversal") {
-    const result = evaluateTraversal(record2, fields, node, memberContext, traversalContext);
+    const result = evaluateTraversal(record2, fields, node, memberContext, traversalContext, fileFacts);
     return result ?? true;
   } else {
-    const result = evaluateCondition(record2, fields, node, memberContext);
+    const result = evaluateCondition(record2, fields, node, memberContext, fileFacts);
     return result ?? true;
   }
 }
-function evaluateTraversal(record2, fields, node, memberContext, traversalContext) {
+function evaluateTraversal(record2, fields, node, memberContext, traversalContext, fileFacts) {
   if (node.condition.type !== "locked" && node.condition.type !== "current_member" && (typeof node.condition.field_key !== "string" || !node.condition.field_key)) {
     return null;
   }
@@ -29098,12 +29301,12 @@ function evaluateTraversal(record2, fields, node, memberContext, traversalContex
     if (currentRecords.length === 0) return true;
     const positiveCondition = { ...inner, operator: positiveOp };
     return !currentRecords.some(
-      (r) => evaluateCondition(r, currentFields, positiveCondition, memberContext) === true
+      (r) => evaluateCondition(r, currentFields, positiveCondition, memberContext, fileFacts) === true
     );
   }
   if (currentRecords.length === 0) return false;
   return currentRecords.some(
-    (r) => evaluateCondition(r, currentFields, inner, memberContext) === true
+    (r) => evaluateCondition(r, currentFields, inner, memberContext, fileFacts) === true
   );
 }
 function requireMemberContext(memberContext, operator) {
@@ -29114,7 +29317,7 @@ function requireMemberContext(memberContext, operator) {
   }
   return memberContext;
 }
-function evaluateCondition(record2, fieldByKey, looseCondition, memberContext) {
+function evaluateCondition(record2, fieldByKey, looseCondition, memberContext, fileFacts) {
   if (looseCondition.type === "locked") {
     const locked = record2.locked;
     if (locked === void 0) return null;
@@ -29153,26 +29356,26 @@ function evaluateCondition(record2, fieldByKey, looseCondition, memberContext) {
       const factor = rowUnitFactor(reading.unit, data);
       if (factor === void 0) return false;
       const inBase = { ...filterCondition, value: filterCondition.value * reading.unit.factor };
-      return matchCell(columnValue, field, inBase, looseCondition, memberContext, factor);
+      return matchCell(columnValue, field, inBase, looseCondition, memberContext, fileFacts, factor);
     }
   }
   if (field?.type === "lookup" && (Array.isArray(columnValue) || columnValue == null)) {
     const values2 = Array.isArray(columnValue) ? columnValue : [];
-    return matchLookup(values2, field, filterCondition, looseCondition, memberContext);
+    return matchLookup(values2, field, filterCondition, looseCondition, memberContext, fileFacts);
   }
-  return matchCell(columnValue, field, filterCondition, looseCondition, memberContext);
+  return matchCell(columnValue, field, filterCondition, looseCondition, memberContext, fileFacts);
 }
 function flattenLookupValues(values2) {
   return values2.flatMap((value) => Array.isArray(value) ? flattenLookupValues(value) : [value]);
 }
-function matchLookup(cell, field, filterCondition, looseCondition, memberContext) {
+function matchLookup(cell, field, filterCondition, looseCondition, memberContext, fileFacts) {
   switch (filterCondition.type) {
     case "select":
     case "select_member":
     case "select_record_link":
     case "files": {
       const union2 = cell.flatMap((list2) => Array.isArray(list2) ? list2 : []);
-      return matchCell(union2, field, filterCondition, looseCondition, memberContext);
+      return matchCell(union2, field, filterCondition, looseCondition, memberContext, fileFacts);
     }
     case "text":
     case "number":
@@ -29192,7 +29395,7 @@ function matchLookup(cell, field, filterCondition, looseCondition, memberContext
   let anyMatched = false;
   for (const value of values2) {
     const element = filterCondition.type === "text" && typeof value !== "string" && value !== null && value !== void 0 ? String(value) : value;
-    const result = matchCell(element, field, positive, looseCondition, memberContext);
+    const result = matchCell(element, field, positive, looseCondition, memberContext, fileFacts);
     if (result !== null) allSkipped = false;
     if (result === true) {
       anyMatched = true;
@@ -29202,7 +29405,16 @@ function matchLookup(cell, field, filterCondition, looseCondition, memberContext
   if (values2.length > 0 && allSkipped) return null;
   return positiveOperator ? !anyMatched : anyMatched;
 }
-function matchCell(cell, field, filterCondition, looseCondition, memberContext, figureFactor = 1) {
+function fileProperty(entry, property, fileFacts, fieldKey, operator) {
+  if (fileFacts) {
+    const [id] = storedFileIds([entry]);
+    return id === void 0 ? "" : fileFacts.get(id)?.[property] ?? "";
+  }
+  if (typeof entry === "string") throw new FileNamesUnavailableError(fieldKey, operator);
+  const own = typeof entry === "object" && entry !== null ? Reflect.get(entry, property) : void 0;
+  return typeof own === "string" ? own : "";
+}
+function matchCell(cell, field, filterCondition, looseCondition, memberContext, fileFacts, figureFactor = 1) {
   let columnValue = cell;
   const resolvedType = filterCondition.type;
   const fieldKey = filterCondition.field_key;
@@ -29574,7 +29786,7 @@ function matchCell(cell, field, filterCondition, looseCondition, memberContext,
       if (typeof filterCondition.value !== "string") return null;
       const term = filterCondition.value.trim().toLowerCase();
       if (!term) return null;
-      matches = files !== null && files.some((file2) => String(file2?.[property] ?? "").toLowerCase().includes(term));
+      matches = files !== null && files.some((entry) => fileProperty(entry, property, fileFacts, fieldKey, filterCondition.operator).toLowerCase().includes(term));
     }
   } else {
     const op = typeof looseCondition.operator === "string" ? looseCondition.operator : "(unset)";
@@ -29593,6 +29805,7 @@ function condition(node, subject) {
   if (node.field_key === void 0 || node.unit_option !== void 0) return "unknown";
   if (typeof node.value === "string" && node.value.includes("{{")) return "unknown";
   if (BY_VIEWER.has(node.operator) && subject.member_id === null) return "unknown";
+  if (FILE_NAME_OPERATORS.has(node.operator)) return "unknown";
   const field = subject.field(node.field_key);
   const held2 = subject.cell(node.field_key);
   if (field === void 0 || held2 === void 0) return "unknown";
@@ -29845,7 +30058,7 @@ function prepareFormulaContext(fields) {
     nonFormulaFields
   };
 }
-function computeFormulaFieldsWithContext(row2, fields, context, linkedTableRecords = /* @__PURE__ */ new Map(), linkedTableFields = /* @__PURE__ */ new Map(), timezone, loadedLinkKeys, linkExpandedTableIds) {
+function computeFormulaFieldsWithContext(row2, fields, context, linkedTableRecords = /* @__PURE__ */ new Map(), linkedTableFields = /* @__PURE__ */ new Map(), timezone, loadedLinkKeys, linkExpandedTableIds, fileFacts) {
   const result = { ...row2 };
   const mayRecompute = (linkKey) => loadedLinkKeys === void 0 || loadedLinkKeys.has(linkKey) || isEmptyFieldValue(row2[linkKey]);
   for (const { field, sourceField } of context.rollupFields) {
@@ -29890,7 +30103,8 @@ function computeFormulaFieldsWithContext(row2, fields, context, linkedTableRecor
           definition: `Rollup "${field.name}" (${field.key})`,
           source: `"${linkedFieldType.name}" (${linkedFieldType.key})`
         } : void 0,
-        traversal.context
+        traversal.context,
+        fileFacts
       );
       result[field.key] = rollupValue;
     } else {
@@ -30213,13 +30427,13 @@ function planFilterTraversal(filter2, aggregatedTableId, aggregatedFields, linke
     }
   };
 }
-function calculateRollupValue(value, fieldType, allLinkedTableRecords, aggregateOption, filter2, linkedTableFields, subject, traversalContext) {
+function calculateRollupValue(value, fieldType, allLinkedTableRecords, aggregateOption, filter2, linkedTableFields, subject, traversalContext, fileFacts) {
   if (aggregateOption?.operation === "count") {
     if (!value) return 0;
     const recordIds2 = extractRecordLinkIds(value);
     let relevantRecords2 = allLinkedTableRecords.filter((r) => recordIds2.includes(r.id));
     if (filter2 && linkedTableFields) {
-      relevantRecords2 = filterRecords(relevantRecords2, linkedTableFields, filter2, null, traversalContext);
+      relevantRecords2 = filterRecords(relevantRecords2, linkedTableFields, filter2, null, traversalContext, fileFacts);
     }
     return relevantRecords2.length;
   }
@@ -30232,7 +30446,7 @@ function calculateRollupValue(value, fieldType, allLinkedTableRecords, aggregate
     return null;
   }
   if (filter2 && linkedTableFields) {
-    relevantRecords = filterRecords(relevantRecords, linkedTableFields, filter2, null, traversalContext);
+    relevantRecords = filterRecords(relevantRecords, linkedTableFields, filter2, null, traversalContext, fileFacts);
   }
   if (relevantRecords.length === 0) {
     return null;
@@ -30761,13 +30975,25 @@ function pageOf(mocked, call) {
 function countOf(mocked, by) {
   return { total: mocked.length, ...by === void 0 ? {} : { counts: countsOf(mocked, by) } };
 }
+function within(filter2, named) {
+  return filter2 === void 0 ? named : { node_type: "group", logic: "and", children: [filter2, named] };
+}
+function mockCount(alias, call) {
+  const mocked = getMockRows(alias, { params: call.params, filter: call.filter });
+  if (mocked === null) return null;
+  const where = Object.entries(call.where ?? {});
+  const named = where.map(([, one]) => getMockRows(alias, { params: call.params, filter: within(call.filter, one) }) ?? []);
+  const answer = (rows, each) => call.where === void 0 ? countOf(rows, call.by) : { total: rows.length, counts: Object.fromEntries(where.map(([name], at2) => [name, each[at2]?.length ?? 0])) };
+  if (Array.isArray(mocked) && named.every((one) => Array.isArray(one))) return answer(mocked, named.filter((one) => Array.isArray(one)));
+  return Promise.all([mocked, ...named]).then(([rows = [], ...each]) => answer(rows, each));
+}
 function knownRows(alias, call) {
   const mocked = getMockRows(alias, call);
   return Array.isArray(mocked) ? pageOf(mocked, call) : void 0;
 }
 function knownCount(alias, call) {
-  const mocked = getMockRows(alias, { params: call.params, filter: call.filter });
-  return Array.isArray(mocked) ? countOf(mocked, call.by) : void 0;
+  const counted = mockCount(alias, call);
+  return counted === null || counted instanceof Promise ? void 0 : counted;
 }
 async function askRows(key, alias, askedAt, call, since = askedAt) {
   const mocked = getMockRows(alias, call);
@@ -30784,18 +31010,22 @@ async function askRows(key, alias, askedAt, call, since = askedAt) {
   return answer;
 }
 async function askCount(key, alias, askedAt, call) {
-  const mocked = getMockRows(alias, { params: call.params, filter: call.filter });
-  if (mocked !== null) return countOf(await mocked, call.by);
+  const mocked = mockCount(alias, call);
+  if (mocked !== null) return mocked;
   const answer = await rpc("query", {
     alias,
     params: call.params,
     count: true,
     ...call.filter === void 0 ? {} : { filter: call.filter },
-    ...call.by === void 0 ? {} : { count_by: call.by }
+    ...call.by === void 0 ? {} : { count_by: call.by },
+    ...call.where === void 0 ? {} : { count_where: call.where }
   });
   noteAnswer(key, alias, askedAt, []);
   return answer;
 }
+function namedCounts(named) {
+  return { rows: Object.fromEntries(named.map(([name, one]) => [name, one.rows])), pending: named.some(([, one]) => one.pending) };
+}
 var feedWants = /* @__PURE__ */ new Map();
 function ignore() {
 }
@@ -30808,7 +31038,8 @@ function useQuery(alias, params = {}, opts = {}) {
   const filter2 = opts.filter;
   const wantsRows = opts.rows ?? true;
   const totalAsked = opts.total ?? opts.page !== void 0;
-  const by = typeof totalAsked === "object" ? totalAsked.by : void 0;
+  const by = typeof totalAsked === "object" && "by" in totalAsked ? totalAsked.by : void 0;
+  const where = typeof totalAsked === "object" && "where" in totalAsked ? totalAsked.where : void 0;
   const call = JSON.stringify([params, filter2 ?? null, sort ?? null]);
   const mocking = hasMockFlag();
   const [paging, setPaging] = useState3({ call, page: 0 });
@@ -30863,11 +31094,12 @@ function useQuery(alias, params = {}, opts = {}) {
     feedWants.set(feedKey, heldPages + 1);
     feed.refetch();
   }, [feedKey, feedHasMore, heldPages, feed]);
-  const countKey = !enabled || totalAsked === false ? null : JSON.stringify(["count", alias, JSON.stringify([params, filter2 ?? null]), by ?? null]);
-  const count = useKey(countKey, (askedAt) => askCount(countKey ?? "", alias, askedAt, { params, filter: filter2, by }), {
+  const countKey = !enabled || totalAsked === false ? null : JSON.stringify(["count", alias, JSON.stringify([params, filter2 ?? null]), by ?? null, where ?? null]);
+  const countCall = { params, ...filter2 === void 0 ? {} : { filter: filter2 }, ...by === void 0 ? {} : { by }, ...where === void 0 ? {} : { where } };
+  const count = useKey(countKey, (askedAt) => askCount(countKey ?? "", alias, askedAt, countCall), {
     focus,
     aliases: [alias],
-    known: mocking ? () => knownCount(alias, { params, filter: filter2, by }) : void 0
+    known: mocking ? () => knownCount(alias, countCall) : void 0
   });
   const version3 = useWrittenVersion();
   const drawn2 = useMemo3(() => {
@@ -30883,9 +31115,10 @@ function useQuery(alias, params = {}, opts = {}) {
   const counted = useMemo3(() => {
     if (count.data === void 0) return void 0;
     const total2 = overlayCount(alias, params, filter2, count.askedAt, count.data.total);
-    const counts = by === void 0 || count.data.counts === void 0 ? void 0 : overlayCounts(alias, params, filter2, by, count.askedAt, count.data.counts);
+    const answered2 = count.data.counts;
+    const counts = answered2 === void 0 ? void 0 : where !== void 0 ? namedCounts(Object.entries(where).map(([name, one]) => [name, overlayCount(alias, params, within(filter2, one), count.askedAt, answered2[name] ?? 0)])) : by === void 0 ? void 0 : overlayCounts(alias, params, filter2, by, count.askedAt, answered2);
     return { total: total2.rows, counts: counts?.rows, pending: total2.pending || (counts?.pending ?? false) };
-  }, [alias, call, by, count.data, count.askedAt, version3]);
+  }, [alias, call, countKey, count.data, count.askedAt, version3]);
   const total = counted?.total;
   const pageCount = opts.page === void 0 || total === void 0 ? void 0 : Math.max(1, Math.ceil(total / opts.page));
   const pageHasMore = opts.page === void 0 ? false : total !== void 0 ? (page + 1) * opts.page < total : drawn2.rows.length === opts.page;

package/dist/queries.d.ts

@@ -89,10 +89,13 @@ export interface QueryOptions<C extends string = string> {
     more?: number;
     /**
      * The total the rows come to — a count of the whole set, its own read, so the rows never wait for it —
-     * or with `by` a count per value of that column from the same scan. On by default with `page`.
+     * with `by` a count per value of that column from the same scan, or with `where` a count per named filter
+     * of the rows it keeps within the set, every one from the same scan. On by default with `page`.
      */
     total?: boolean | {
         by: C;
+    } | {
+        where: Readonly<Record<string, QueryFilter<C>>>;
     };
     /** `false` reads no rows: a total alone. Default `true`. */
     rows?: boolean;
@@ -103,7 +106,8 @@ export interface QueryState<R> {
     truncated: boolean;
     /** The whole set's count, where `total` is asked; `undefined` until it answers. */
     total: number | undefined;
-    /** Rows per value of `total.by`, keyed as a row carries it (an option's `opt_…`); a value no row holds is absent. */
+    /** Rows per value of `total.by`, keyed as a row carries it (an option's `opt_…`), a value no row holds absent;
+     *  or per name of `total.where`. */
     counts: Readonly<Record<string, number>> | undefined;
     /** Only the first read of a key with nothing to show; a re-read and a new key keep the rows on screen. */
     loading: boolean;

package/docs/data_fetching.md

@@ -21,7 +21,7 @@ untyped. It is written from the app's live bindings by `lotics app create --cust
 | `useQuery(alias, params?, opts?)` | `rows` up to the server's cap, or the first `limit` | a detail read, a dashboard block, a combobox's top-N — anything that is not a long list |
 | `useQuery(alias, params?, { page: n })` | one numbered page of `n` rows, `total`, `pageCount`, `setPage` | numbered, jumpable pages |
 | `useQuery(alias, params?, { more: n })` | accumulated `rows` + `loadMore` | infinite scroll / "load more" feeds |
-| `useQuery(alias, params?, { rows: false, total: true })` | `total` only, no rows (`total: { by: column }` adds `counts`) | a facet chip, a queue badge, an "N awaiting approval" tile — the size of a set you are not listing |
+| `useQuery(alias, params?, { rows: false, total: true })` | `total` only, no rows (`total: { by: column }` or `total: { where: { name: filter } }` adds `counts`) | a facet chip, a queue badge, an "N awaiting approval" tile — the size of a set you are not listing |
 | `useQueries(calls, opts?)` | one state per `{ alias, params?, filter?, sort?, aggregate?, total?, rows? }`, in order — a `sort` orders that call's rows before the cap cuts them | reads that are DATA — a list known only at render, one read per item, or one count per stage (`rows: false, total: true`, each state's `.total`); the deploy's alias scan reads a list as dynamic, so every alias in it is still declared. With `aggregate` a call answers the groups of its filtered rows instead of the rows ([queries](./queries.md)) |
 | `queryAll(alias, params?, { filter, sort })` | a promise of every row | outside React, for a job that must hold the whole narrowed set in the browser (the ids an act runs on): it asks page after page until the server says the set ended, never stopping at the 10,000-row cap. The server's rows as stored — no write of this app is drawn over them |
 | `exportQuery(alias, { params, filter, sort, tabs?, report, file })` | a promise of the file | every row the narrowed set holds, made into one file by the server — no row reaches the browser. `tabs` (2 to 5, each `{ tab, label, filter?, sort? }`) are each read as the export's own rows are — same query and params, under the tab's own filter and sort (absent, the declared order) — and a template reads each one's rows under its `tab`, a name none of the report's keys nor the template's `rows` key holds. `report` is `{ title, lines, readings, dates?, period?, per?, filename? }` — `dates` each date filter's `{ from?, to? }` by field alias, each bound a day (`yyyy-MM-dd`) or a minute of one (`yyyy-MM-ddTHH:mm`) with no zone; `period` the tabs' `{ from, to }`, bounds of the same form; `per` the value the report was picked for, in the reader's words; `filename` the file's name in the template grammar over one value each — `title`, `at` (the moment the server made the file), `dates.<field>.from` or `.to`, `period.from` or `.to`, `per`, `lines | lookup:<n>` — at most 200 bytes once filled (absent, the template's name, or `title`); `file` is `{ kind: "workbook", language, sheet, columns }` (the default report workbook, its head closing with the moment the server made it, each column `{ key, header, type }` an output column of the query — a `number` one on a number column, a `date` one on a date or datetime; with `tabs`, one sheet per tab named by its `label` in place of `sheet`) or `{ kind: "template", template }`, one the query declares under `templates` by name ([queries](./queries.md)). Past 20,000 rows, in any tab, it rejects, never cuts; each caller makes at most 60 exports a minute. The file's `url` is signed for the caller: open it with `openExternal` |
@@ -63,7 +63,15 @@ const { total, counts } = useQuery("orders", { q }, { rows: false, total: { by:
 // counts?.["opt_shipped"] — the rows in that stage over the whole set, however few are loaded
 ```
 
-A `useQueries` call's `total` is `true` or absent — it takes no `by`.
+Several counts of one set — a tab each, a share each — are **one read with `total: { where }`**: each
+named filter's rows within the read's `filter`, as `counts` by name, from the same scan.
+
+```tsx
+const { total, counts } = useQuery("orders", {}, { rows: false, total: { where: { late: lateFilter, mine: mineFilter } } });
+// counts?.late, counts?.mine — one scan, however many names
+```
+
+A `useQueries` call's `total` is `true` or absent — it takes no `by` or `where`.
 
 ### Why not hand-roll it
 

package/docs/members_and_options.md

@@ -321,15 +321,14 @@ updateComment, deleteComment, refetch }`.
 - `comments` — newest first on the wire (server order); a thread usually reads oldest-first, so
   reverse it for display. Each `AppComment`: `{ id, record_id,
   table_id, member_id, author, content, files, workspace_id, created_at, updated_at }`. Attachments
-  (`AppCommentFile`) carry `id` / `filename` / `mime_type` — a file's identity is its `id`, and
-  the server re-reads every attachment from storage by that id, so nothing else you hold about a
-  file can affect what is stored. The `url` / `thumbnail_url` / `preview_url` fields exist on the type
-  but the server does not populate them today — render attachments by name and type (what
-  `Timeline`'s default file row does), never by counting on a fetchable URL.
+  (`AppCommentFile`) carry `id` / `filename` / `mime_type` and a presigned `url` (plus
+  `thumbnail_url` for an image), valid 24 hours and refreshed by every read. A file's identity is
+  its `id`: the server reads every attachment from the file by that id, so nothing else you hold
+  about a file can affect what is stored.
 - `createComment({ content, file_ids? })` — posts as the viewing member. `file_ids` come from
   `useFileUpload` / `useAttachments` (see [files](./files.md)). A comment must have content or at
-  least one file (empty input is a client no-op; the server enforces the same rule). Content max
-  10,000 characters.
+  least one file (empty input is a client no-op; the server enforces the same rule). A file id
+  that names no live file in this workspace refuses the comment. Content max 10,000 characters.
 - `updateComment(id, { content, files? })` — omit `files` to keep the current attachment set (a
   text-only edit never drops attachments); pass `files` to replace the whole set.
 - All three mutations apply **optimistically** with rollback on error, then repopulate from the

package/docs/mutations.md

@@ -526,7 +526,7 @@ every read before the request answers:
   leaves it; a created row it admits joins it, standing by the read's order (the call's `sort`,
   then the query's own) where its sort cells are numbers or dates, else first. A row the read does
   not hold that a write may move into it waits for the server, and `pending` says so.
-- **Totals.** A `total`, a count per value (`total: { by }`), a group asked with `aggregate` or
+- **Totals.** A `total`, a count per value (`total: { by }`) or per named filter (`total: { where }`), a group asked with `aggregate` or
   declared by the query, and a parent's count or sum rollup move by exactly what the written row adds
   or takes away; a group the last row leaves is gone, and a count per value gains the value a row
   first holds. A mean, an extreme, a distinct count, a group by day, an aggregate with its own

package/docs/queries.md

@@ -844,7 +844,10 @@ template as derived nodes, in this order: `filter` (narrow) → `sort` (order)
 - **`count: true`** — returns `{ total }` only: a COUNT over the *filtered* set, ignoring
   sort/limit/offset. Drives "Page 1 of N". With **`count_by: "<column>"`** the same scan also
   returns `counts` — rows per value of that projected column (a multi-value row under each value,
-  a row holding none in `total` only); a column whose values are not plain (a link) → 400. It is a
+  a row holding none in `total` only); a column whose values are not plain (a link) → 400. With
+  **`count_where: { <name>: <filter> }`** (not beside `count_by`) the same scan returns `counts` by
+  name — the rows each filter keeps within `filter`, each filter bounded and resolved as `filter` is,
+  at most 32. It is a
   **second full execution** of the template — sent only where a read asks for its `total`, and
   one count serves every read of the same set ([data_fetching](./data_fetching.md)).
 - **`aggregate: { by?, day?, sum? }`** — the groups of the *filtered* set in place of its rows: one

package/docs/security.md

@@ -111,7 +111,7 @@ Listing members (`useMembers`) takes an authenticated member of the app's own or
 
 ## What runtime refinement cannot widen
 
-The query RPC accepts runtime `filter` and `sort` (for search boxes, sortable tables, pickers) — but these are **bounded to the named query's output columns**. A `field_key` naming a column the query does not project is rejected, so a caller can never filter or sort by — and thereby probe — a field the author didn't expose. The caller's `limit` is clamped to the server row cap, params fill the template's *value holes* only — filter values and the search term; tables, joins, and projections are author-fixed — and `count` mode returns a total — with `count_by`, one per value of a projected column — over the same bounded filter. Full mechanics in [queries](./queries.md).
+The query RPC accepts runtime `filter` and `sort` (for search boxes, sortable tables, pickers) — but these are **bounded to the named query's output columns**. A `field_key` naming a column the query does not project is rejected, so a caller can never filter or sort by — and thereby probe — a field the author didn't expose. The caller's `limit` is clamped to the server row cap, params fill the template's *value holes* only — filter values and the search term; tables, joins, and projections are author-fixed — and `count` mode returns a total — with `count_by`, one per value of a projected column; with `count_where`, one per named filter, each bounded as `filter` is — over the same bounded filter. Full mechanics in [queries](./queries.md).
 
 **Warning — templated free-text search is not output-bounded.** A `search` term in the query template (typically a `{{params.q}}` hole) matches against the record's **whole search document**: every searchable field of the table — text, numbers, dates (in three formats), select option names, member names, linked-record display text, formula/rollup/lookup values, and autonumbers (only booleans, buttons, and file fields are excluded). It is *not* restricted to the columns the query projects. A caller who controls the search term can therefore probe the *contents* of unprojected fields by watching which rows match — a row-membership oracle. Put a `search` hole only in queries over tables where every searchable field is acceptable to probe for that audience; for a search box over a table with sensitive unprojected fields, use runtime `filter` with `contains` on the projected columns instead, or AND the `search` with a template `contains` OR-group over the fields that may be probed — every row that group matches also matches the search, so the pair answers only for those fields.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.108.0",
+  "version": "0.110.0",
   "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": {