@lotics/app-sdk 0.117.1 → 0.118.1

package/AGENTS.md

@@ -20,7 +20,7 @@ This file is the index. The **exact type** of anything is its shipped declaratio
 | [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. |
 | [docs/recipes.md](./docs/recipes.md) | Task-shaped how-tos — returning a generated file, returning structured data, parameterized lookups, composable optional filters, cell decoding, testing an AI action without spending credits. |
 | [docs/files.md](./docs/files.md) | Files end to end — `useFileUpload` and its `fidelity` and a photo's `place`, `renameFile` (a new file over the same bytes), `useAttachments`/`useAttachmentPiles`, `readFiles` and presigned URLs (a bearer credential — never logged or persisted), workflow-generated files, naming a zip's entries, the delivery bounds. |
-| [docs/members_and_options.md](./docs/members_and_options.md) | People, select options and comments — `useMembers`, `useFieldOptions`, `useViewer`, `useWorkspaceTimezone`/`useWorkspaceCurrency`, `useAppContext`, the workspace's zone at the root, `useComments`, a record's activity (`useRecordActivity`). |
+| [docs/members_and_options.md](./docs/members_and_options.md) | People, select options and comments — `useMembers`, `useFieldOptions`, `useViewer`, `useWorkspaceTimezone`/`useWorkspaceCurrency`, `useAppContext`, the workspace's zone at the root, `useComments`, a record's activity (`useRecordActivity`), a register's imports log (`useImportsLog`, `useImportRun`). |
 | [docs/navigation_and_state.md](./docs/navigation_and_state.md) | `AppRouter` (embedded/standalone URL model, the screens and `drawers` it reports to the host), `useUrlState` + `urlParam` codecs, `useRecents`, `useFolderPick`. |
 | [docs/ai.md](./docs/ai.md) | `useAgentRun` (structured vs free-text, streaming parts, the agent's ask-back), `askAi`, `useAiContext`, and what the member's own chat agent can do with the app while it is open. |
 | [docs/security.md](./docs/security.md) | **Read before shipping** — the owner-principal model, `is_current_member` scoping, write attribution, group gates, public-app bounds, why a per-input bound is a tenancy floor rather than an authorization check. |

package/dist/{chunk-IN4WP24U.js → chunk-XL5LZFGB.js}

@@ -992,6 +992,9 @@ function rpcStandalone(op, payload) {
       return rejectCommentsStandalone();
     case "activity.list":
       return Promise.reject(new Error("A record's activity is available only in embedded apps \u2014 a signed-in member is required."));
+    case "imports.list":
+    case "imports.run":
+      return Promise.reject(new Error("A register's imports log is available only in embedded apps \u2014 a signed-in member is required."));
     case "recording.start":
     case "recording.stop":
       return Promise.reject(

package/dist/imports.d.ts

@@ -0,0 +1,51 @@
+import type { ImportRow, ImportRun, ImportWorkflow } from "./shared_types.js";
+export interface ImportsLogState {
+    /** The workflows importing into the register's table, whether or not they have run. */
+    workflows: ImportWorkflow[];
+    /** Newest first. */
+    runs: ImportRun[];
+    /** Where the log goes on — pass it as `after` to read the page past this one; `undefined` at its end. */
+    next: string | undefined;
+    loading: boolean;
+    error: string | null;
+    /** A signed-in member, in a host that bridges the log, of a register keeping one; otherwise `runs` stays empty. */
+    available: boolean;
+    refetch: () => void;
+}
+export interface ImportRunState {
+    /** The run, as the log lists it; `undefined` until read. */
+    run: ImportRun | undefined;
+    /** In the order the run first wrote them. */
+    rows: ImportRow[];
+    /** Where its rows go on — pass it as `after`; `undefined` at their end. */
+    next: string | undefined;
+    loading: boolean;
+    error: string | null;
+    available: boolean;
+    refetch: () => void;
+}
+export interface ImportsPageOptions {
+    /** A page's `next`: read the page past it. Absent, the first page. */
+    after?: string;
+}
+/** No push over the register's rows for this long ends a burst: longer than the second the server waits at most
+ *  between pushes while a run writes. */
+export declare const IMPORTS_BURST_QUIET_MS = 2000;
+/**
+ * One page of the register's imports log. `entity` is the alias of the register's entity: the page is asked again once
+ * pushes naming its rows have gone quiet.
+ *
+ * ```tsx
+ * const { runs, next } = useImportsLog("order");
+ * ```
+ */
+export declare function useImportsLog(entity: string, options?: ImportsPageOptions): ImportsLogState;
+/**
+ * One page of one run's rows — `run_id` a run's `id` from `useImportsLog` — with the run beside them. Asked again after
+ * a burst of pushes over the register's rows only while the run runs: an ended run's rows are what they are.
+ *
+ * ```tsx
+ * const { run, rows, next } = useImportRun("order", runId);
+ * ```
+ */
+export declare function useImportRun(entity: string, run_id: string, options?: ImportsPageOptions): ImportRunState;

package/dist/index.d.ts

@@ -13,6 +13,9 @@ export { useComments, useCommentCounts } from "./comments.js";
 export type { AppComment, AppCommentAuthor, AppCommentFile, CommentsState, UseCommentsArgs, CommentCountsState, UseCommentCountsArgs, } from "./comments.js";
 export { useRecordActivity } from "./activity.js";
 export type { RecordActivityOptions, RecordActivityState } from "./activity.js";
+export { useImportRun, useImportsLog } from "./imports.js";
+export type { ImportRunState, ImportsLogState, ImportsPageOptions } from "./imports.js";
+export type { ImportRow, ImportRowKind, ImportRun, ImportRunEnd, ImportRunPage, ImportRunStop, ImportsLogPage, ImportWorkflow } from "./shared_types.js";
 export type { ActivityActor, ActivityActorKind, ActivityChange, ActivityComment, ActivityEntry, ActivityValue, RecordActivityPage, } from "./shared_types.js";
 export { useAppContext, useViewer, useWorkspaceCurrency, useWorkspaceTimezone } from "./viewer.js";
 export type { AppAbsence } from "./shared_types.js";

package/dist/index.js

@@ -25,7 +25,7 @@ import {
   subscribeRecordings,
   subscribeUrlParams,
   urlParam
-} from "./chunk-IN4WP24U.js";
+} from "./chunk-XL5LZFGB.js";
 
 // src/mount.tsx
 import { createRoot } from "react-dom/client";
@@ -493,6 +493,17 @@ var slots = /* @__PURE__ */ new Map();
 var clock = 0;
 var nextStaging = 1;
 var FOCUS_THROTTLE_MS = 5e3;
+var PAINT_CAP_MS = 1e3;
+function draw(paint) {
+  if (paint.drawn) return;
+  paint.drawn = true;
+  clearTimeout(paint.cap);
+  for (const settle2 of paint.held.splice(0)) settle2();
+}
+function release(paint, slot) {
+  paint.waiting.delete(slot);
+  if (paint.waiting.size === 0) draw(paint);
+}
 function slotOf(key, fetcher, aliases) {
   const held2 = slots.get(key);
   if (held2 !== void 0) {
@@ -507,6 +518,7 @@ function slotOf(key, fetcher, aliases) {
     inflight: null,
     stale: false,
     outdated: false,
+    paint: null,
     stagings: [],
     fetcher,
     aliases,
@@ -532,6 +544,8 @@ function ask(slot, fresh) {
     return slot.inflight;
   }
   const askedAt = tick();
+  const paint = slot.paint;
+  slot.paint = null;
   slot.outdated = false;
   slot.lastAskedMs = Date.now();
   const land = () => {
@@ -542,8 +556,21 @@ function ask(slot, fresh) {
       void ask(slot, false);
     }
   };
+  const settle2 = (apply) => {
+    if (paint === null || paint.drawn) {
+      apply();
+      return void 0;
+    }
+    return new Promise((resolve) => {
+      paint.held.push(() => {
+        apply();
+        resolve();
+      });
+      release(paint, slot);
+    });
+  };
   const inflight = slot.fetcher(askedAt, slot.answer).then(
-    (answer) => {
+    (answer) => settle2(() => {
       if (askedAt >= slot.askedAt) {
         slot.answer = answer;
         slot.askedAt = askedAt;
@@ -551,35 +578,45 @@ function ask(slot, fresh) {
         slot.stagings = slot.stagings.filter((one) => one.settledAt === null || one.settledAt >= askedAt);
       }
       land();
-    },
-    (cause) => {
+    }),
+    (cause) => settle2(() => {
       slot.error = cause instanceof Error ? cause : new Error(String(cause));
       land();
-    }
+    })
   );
   slot.inflight = inflight;
   changed(slot);
   return inflight;
 }
+function readNow(aliases) {
+  const named = [...slots.values()].filter((slot) => slot.aliases.size > 0 && (aliases === void 0 || aliases.some((alias) => slot.aliases.has(alias))));
+  for (const slot of named) if (slot.mounts.size === 0) slot.outdated = true;
+  return named.filter((slot) => slot.mounts.size > 0);
+}
 function refetchReads(aliases) {
-  for (const slot of slots.values()) {
-    if (slot.aliases.size === 0) continue;
-    if (aliases !== void 0 && !aliases.some((alias) => slot.aliases.has(alias))) continue;
-    if (slot.mounts.size === 0) slot.outdated = true;
-    else void ask(slot, true);
+  for (const slot of readNow(aliases)) void ask(slot, true);
+}
+function askInOnePaint(read2) {
+  if (read2.length === 0) return;
+  const paint = { waiting: new Set(read2), held: [], drawn: false, cap: setTimeout(() => draw(paint), PAINT_CAP_MS) };
+  for (const slot of read2) {
+    if (slot.paint !== null) release(slot.paint, slot);
+    slot.paint = paint;
   }
+  for (const slot of read2) void ask(slot, true);
+}
+function refetchPushed(aliases) {
+  askInOnePaint(readNow(aliases));
 }
 var listening = false;
 function listen() {
   if (listening || typeof window === "undefined") return;
   listening = true;
-  subscribeQueriesChanged((aliases) => refetchReads(aliases));
+  subscribeQueriesChanged(refetchPushed);
   const refocus = () => {
-    for (const slot of slots.values()) {
-      if (![...slot.mounts.values()].some((mount2) => mount2.focus)) continue;
-      if (Date.now() - slot.lastAskedMs < FOCUS_THROTTLE_MS) continue;
-      void ask(slot, false);
-    }
+    askInOnePaint(
+      [...slots.values()].filter((slot) => slot.inflight === null && [...slot.mounts.values()].some((mount2) => mount2.focus) && Date.now() - slot.lastAskedMs >= FOCUS_THROTTLE_MS)
+    );
   };
   window.addEventListener("focus", refocus);
   window.addEventListener("online", refocus);
@@ -25159,7 +25196,7 @@ var tableFilesFieldSchema = tableFieldBaseSchema.extend({
 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."
+    "JavaScript expression. A field is referenced as {fld_key}, stored so; a write also takes {Field Name}, stored as its key."
   ),
   notation: notationSchema.optional().describe(`${NOTATION_DESCRIPTION} For a formula yielding a number.`),
   link: zod_default.literal(true).optional().describe("The formula yields a URL as text, drawn as a link that opens."),
@@ -25207,6 +25244,9 @@ var workflowSchema = zod_default.object({
   metadata: workflowMetadataSchema.nullable().optional().describe("Metadata for the workflow"),
   current_version: zod_default.number().int().describe("Current version number"),
   enabled: zod_default.boolean().describe("Whether this workflow is active"),
+  imports_into: zod_default.string().nullable().optional().describe(
+    "The table this workflow brings data into: its runs are the imports log of a register over that table that keeps one (`register.imports`). Null, it imports into none."
+  ),
   workspace_id: zod_default.string().describe("ID of the workspace this workflow belongs to"),
   created_at: zod_default.string().describe("Timestamp when workflow was created"),
   updated_at: zod_default.string().describe("Timestamp of last update")
@@ -32244,6 +32284,9 @@ function useQuery(alias, params = {}, opts = {}) {
   if (modes.length > 1) throw new Error(`useQuery("${alias}") takes one of \`limit\`, \`page\` and \`more\`; it was given ${modes.length}.`);
   const enabled = opts.enabled ?? true;
   const focus = opts.revalidateOnFocus ?? true;
+  const live = opts.revalidateOnChange ?? true;
+  const aliases = live ? [alias] : [];
+  const apart = live ? [] : ["held"];
   const sort = opts.sort !== void 0 && opts.sort.length > 0 ? opts.sort : void 0;
   const filter2 = opts.filter;
   const wantsRows = opts.rows ?? true;
@@ -32257,7 +32300,7 @@ function useQuery(alias, params = {}, opts = {}) {
   const page = held2 !== void 0 ? Math.max(0, held2.at) : opts.page === void 0 || paging.call !== call ? 0 : paging.page;
   const turn2 = held2?.onChange;
   const setPage = useCallback5((next) => turn2 === void 0 ? setPaging({ call, page: Math.max(0, next) }) : turn2(Math.max(0, next)), [call, turn2]);
-  const rowsKey = !enabled || !wantsRows || opts.more !== void 0 ? null : JSON.stringify(["rows", alias, call, opts.limit ?? null, opts.page ?? null, page]);
+  const rowsKey = !enabled || !wantsRows || opts.more !== void 0 ? null : JSON.stringify(["rows", alias, call, opts.limit ?? null, opts.page ?? null, page, ...apart]);
   const rows = useKey(
     rowsKey,
     (askedAt) => askRows(rowsKey ?? "", alias, askedAt, {
@@ -32267,9 +32310,9 @@ function useQuery(alias, params = {}, opts = {}) {
       limit: opts.page ?? opts.limit,
       offset: opts.page === void 0 ? 0 : page * opts.page
     }),
-    { focus, aliases: [alias], known: mocking ? () => knownRows(alias, { params, filter: filter2, sort, limit: opts.page ?? opts.limit, offset: opts.page === void 0 ? 0 : page * opts.page }) : void 0 }
+    { focus, aliases, known: mocking ? () => knownRows(alias, { params, filter: filter2, sort, limit: opts.page ?? opts.limit, offset: opts.page === void 0 ? 0 : page * opts.page }) : void 0 }
   );
-  const feedKey = !enabled || !wantsRows || opts.more === void 0 ? null : JSON.stringify(["feed", alias, call, opts.more]);
+  const feedKey = !enabled || !wantsRows || opts.more === void 0 ? null : JSON.stringify(["feed", alias, call, opts.more, ...apart]);
   const feedSize = opts.more ?? 0;
   const feed = useKey(
     feedKey,
@@ -32294,7 +32337,7 @@ function useQuery(alias, params = {}, opts = {}) {
       return { pages };
     },
     // A feed re-read on arrival would reshuffle it under a reader scrolling it.
-    { focus, arrival: false, aliases: [alias] }
+    { focus, arrival: false, aliases }
   );
   const heldPages = feed.data?.pages.length ?? 0;
   const feedHasMore = feed.data?.pages.at(-1)?.next_cursor != null;
@@ -32304,11 +32347,11 @@ 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, where ?? null]);
+  const countKey = !enabled || totalAsked === false ? null : JSON.stringify(["count", alias, JSON.stringify([params, filter2 ?? null]), by ?? null, where ?? null, ...apart]);
   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],
+    aliases,
     known: mocking ? () => knownCount(alias, countCall) : void 0
   });
   const version3 = useWrittenVersion();
@@ -32607,6 +32650,75 @@ function useRecordActivity(entity, record_id, options = {}) {
   };
 }
 
+// src/imports.ts
+import { useEffect as useEffect5 } from "react";
+var NO_WORKFLOWS = [];
+var NO_RUNS = [];
+var NO_ROWS = [];
+var IMPORTS_BURST_QUIET_MS = 2e3;
+function useImportsLog(entity, options = {}) {
+  const { after } = options;
+  const { memberId, resolved } = useAppContext();
+  const member = memberId !== null;
+  const page = useKey(
+    member ? JSON.stringify(["imports", entity, after ?? null]) : null,
+    () => rpc("imports.list", after === void 0 ? {} : { after })
+  );
+  useAfterBurst(member ? entity : null, page.refetch);
+  const bridged = !refusedByHost(page.error, "imports.list");
+  const log = page.data?.kind === "log" ? page.data : void 0;
+  return {
+    workflows: log?.workflows ?? NO_WORKFLOWS,
+    runs: log?.runs ?? NO_RUNS,
+    next: log?.next,
+    // Waiting on the context counts as loading.
+    loading: member ? page.loading : !resolved,
+    error: bridged ? page.error?.message ?? null : null,
+    available: member && bridged && page.data?.kind !== "none",
+    refetch: page.refetch
+  };
+}
+function useImportRun(entity, run_id, options = {}) {
+  const { after } = options;
+  const { memberId, resolved } = useAppContext();
+  const member = memberId !== null;
+  const page = useKey(
+    member ? JSON.stringify(["import_run", entity, run_id, after ?? null]) : null,
+    () => rpc("imports.run", { run_id, ...after === void 0 ? {} : { after } })
+  );
+  const read2 = page.data?.kind === "run" ? page.data : void 0;
+  useAfterBurst(member && read2?.run.end === "running" ? entity : null, page.refetch);
+  const bridged = !refusedByHost(page.error, "imports.run");
+  return {
+    run: read2?.run,
+    rows: read2?.rows ?? NO_ROWS,
+    next: read2?.next,
+    loading: member ? page.loading : !resolved,
+    error: bridged ? page.error?.message ?? null : null,
+    available: member && bridged && page.data?.kind !== "none",
+    refetch: page.refetch
+  };
+}
+function useAfterBurst(entity, ask2) {
+  useEffect5(() => {
+    if (entity === null) return;
+    const alias = listQueryAlias(entity);
+    let quiet;
+    const unsubscribe = subscribeQueriesChanged((aliases) => {
+      if (!aliases.includes(alias)) return;
+      clearTimeout(quiet);
+      quiet = setTimeout(ask2, IMPORTS_BURST_QUIET_MS);
+    });
+    return () => {
+      clearTimeout(quiet);
+      unsubscribe();
+    };
+  }, [entity, ask2]);
+}
+function refusedByHost(error51, op) {
+  return error51?.message === `Unknown RPC op: ${op}`;
+}
+
 // src/recording.ts
 import { useCallback as useCallback7, useMemo as useMemo4, useSyncExternalStore as useSyncExternalStore3 } from "react";
 var NO_MOCKS = {};
@@ -32805,7 +32917,7 @@ function readSelect(value) {
 }
 
 // src/use_recents.ts
-import { useCallback as useCallback8, useEffect as useEffect5, useRef as useRef4, useState as useState4 } from "react";
+import { useCallback as useCallback8, useEffect as useEffect6, useRef as useRef4, useState as useState4 } from "react";
 var PREFIX = "lotics.recents.";
 function read(storageKey) {
   try {
@@ -32830,7 +32942,7 @@ function useRecents(key, options = {}) {
   const maxRef = useRef4(options.max ?? 5);
   maxRef.current = options.max ?? 5;
   const [recents, setRecents] = useState4(() => read(storageKey).slice(0, maxRef.current));
-  useEffect5(() => {
+  useEffect6(() => {
     setRecents(read(storageKey).slice(0, maxRef.current));
   }, [storageKey]);
   const remember = useCallback8(
@@ -32863,13 +32975,13 @@ function useRecents(key, options = {}) {
 }
 
 // src/use_url_state.ts
-import { useCallback as useCallback9, useEffect as useEffect6, useMemo as useMemo5, useRef as useRef5, useState as useState5 } from "react";
+import { useCallback as useCallback9, useEffect as useEffect7, useMemo as useMemo5, useRef as useRef5, useState as useState5 } from "react";
 function useUrlState(defs) {
   const defsRef = useRef5(defs);
   defsRef.current = defs;
   const [params, setParams] = useState5(peekUrlParams);
   const editedRef = useRef5(false);
-  useEffect6(() => {
+  useEffect7(() => {
     let active = true;
     const apply = (next) => {
       if (active) setParams((prev) => paramsEqual(prev, next) ? prev : next);
@@ -32961,6 +33073,8 @@ export {
   useFieldOptions,
   useFileUpload,
   useFolderPick,
+  useImportRun,
+  useImportsLog,
   useMembers,
   useNewRecord,
   useQueries,

package/dist/queries.d.ts

@@ -76,6 +76,12 @@ export interface QueryOptions<C extends string = string> {
     enabled?: boolean;
     /** `false` skips a re-read on focus and reconnect. Default `true`. */
     revalidateOnFocus?: boolean;
+    /**
+     * `false` skips a re-read when the host says the query's tables moved and when this app writes to them: the rows stay
+     * as first read until `refetch` — a moment's rows read beside a live screen, never joining the render its pushes
+     * draw. Default `true`.
+     */
+    revalidateOnChange?: boolean;
     /** Part of the read's key; empty keeps the query's own order. */
     sort?: QuerySortKey<C>[];
     /** Part of the read's key. */

package/dist/router.js

@@ -2,7 +2,7 @@ import {
   isEmbedded,
   postHostNotification,
   setUrlParams
-} from "./chunk-IN4WP24U.js";
+} from "./chunk-XL5LZFGB.js";
 
 // src/router.tsx
 import { useEffect } from "react";

package/dist/rpc.d.ts

@@ -9,7 +9,7 @@ import { type UrlParams, type UrlParamsPatch } from "./url_params.js";
  *   app  → host: { id, op, payload }
  *   host → app:  { id, type: "result", data } | { id, type: "error", message }
  */
-export type RpcOp = "query" | "export" | "field_options" | "workflow" | "agentRuns" | "agentRun.get" | "agentRun.cancel" | "upload" | "file.rename" | "members" | "context" | "write_model" | "prediction_miss" | "openExternal" | "openApp" | "askAi" | "urlState.get" | "urlState.set" | "folder.get" | "folder.set" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts" | "activity.list" | "recording.start" | "recording.stop";
+export type RpcOp = "query" | "export" | "field_options" | "workflow" | "agentRuns" | "agentRun.get" | "agentRun.cancel" | "upload" | "file.rename" | "members" | "context" | "write_model" | "prediction_miss" | "openExternal" | "openApp" | "askAi" | "urlState.get" | "urlState.set" | "folder.get" | "folder.set" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts" | "activity.list" | "imports.list" | "imports.run" | "recording.start" | "recording.stop";
 export interface AgentRunPayload {
     alias: string;
     session_id: string;

package/dist/shared_types.d.ts

@@ -3,8 +3,8 @@
  * `scripts/build_sdk.mjs`, because that package is private and ships in no
  * tarball. Written at every build, never edited.
  */
-export type ActivityEntry = { changes: { field_id: string; label: string; before: string | number | boolean | { key: string; label: string; }[] | { id: string; display: string; }[] | { id: string; name: string | null; image?: string | undefined; }[] | { id: string; filename: string; mime_type: string; file_storage_key?: string | undefined; url?: string | undefined; thumbnail_url?: string | undefined; preview_url?: string | undefined; size?: number | null | undefined; created_at?: string | undefined; document_template_id?: string | undefined; }[] | null; after: string | number | boolean | { key: string; label: string; }[] | { id: string; display: string; }[] | { id: string; name: string | null; image?: string | undefined; }[] | { id: string; filename: string; mime_type: string; file_storage_key?: string | undefined; url?: string | undefined; thumbnail_url?: string | undefined; preview_url?: string | undefined; size?: number | null | undefined; created_at?: string | undefined; document_template_id?: string | undefined; }[] | null; removed?: true | undefined; }[]; id: string; actor: { kind: "member" | "agent" | "workflow" | "import"; id: string; name: string; image?: string | undefined; }; at: string; until: string; kind: "change"; } | { comment: { id: string; body: string; mentions: { id: string; name: string; }[]; files?: { id: string; filename: string; mime_type: string; file_storage_key?: string | undefined; url?: string | undefined; thumbnail_url?: string | undefined; preview_url?: string | undefined; size?: number | null | undefined; created_at?: string | undefined; document_template_id?: string | undefined; }[] | undefined; }; id: string; actor: { kind: "member" | "agent" | "workflow" | "import"; id: string; name: string; image?: string | undefined; }; at: string; until: string; kind: "comment"; };
-export type AppAbsence = { member: { id: string; name: string; }; stand_in: { id: string; name: string; }; starts_on: string; ends_on: string; group_ids: string[]; };
+export type ActivityEntry = { changes: { field_id: string; label: string; before: string | number | boolean | { key: string; label: string; }[] | { id: string; display: string; }[] | { id: string; name: string | null; image?: string | undefined; }[] | { id: string; filename: string; mime_type: string; file_storage_key?: string | undefined; url?: string | undefined; thumbnail_url?: string | undefined; preview_url?: string | undefined; size?: number | null | undefined; created_at?: string | undefined; document_template_id?: string | undefined; }[] | null; after: string | number | boolean | { key: string; label: string; }[] | { id: string; display: string; }[] | { id: string; name: string | null; image?: string | undefined; }[] | { id: string; filename: string; mime_type: string; file_storage_key?: string | undefined; url?: string | undefined; thumbnail_url?: string | undefined; preview_url?: string | undefined; size?: number | null | undefined; created_at?: string | undefined; document_template_id?: string | undefined; }[] | null; removed?: true | undefined; }[]; id: string; actor: { kind: "member" | "agent" | "workflow" | "import"; id: string; name: string; image?: string | undefined; }; at: string; until: string; kind: "change"; created?: true | undefined; } | { comment: { id: string; body: string; mentions: ImportWorkflow[]; files?: { id: string; filename: string; mime_type: string; file_storage_key?: string | undefined; url?: string | undefined; thumbnail_url?: string | undefined; preview_url?: string | undefined; size?: number | null | undefined; created_at?: string | undefined; document_template_id?: string | undefined; }[] | undefined; }; id: string; actor: { kind: "member" | "agent" | "workflow" | "import"; id: string; name: string; image?: string | undefined; }; at: string; until: string; kind: "comment"; };
+export type AppAbsence = { member: ImportWorkflow; stand_in: ImportWorkflow; starts_on: string; ends_on: string; group_ids: string[]; };
 /** The file an app export made, as a link to download it: no workspace file, so no id, and kept a day. */
 export type ExportedFile = {
   filename: string;
@@ -16,6 +16,9 @@ export type ExportedFile = {
   /** When the server made it, ISO 8601. */
   created_at: string;
 };
+export type ImportRow = { record_id: string; kind: "removed" | "added" | "changed"; at: string; changes: { field_id: string; label: string; before: string | number | boolean | { key: string; label: string; }[] | { id: string; display: string; }[] | { id: string; name: string | null; image?: string | undefined; }[] | { id: string; filename: string; mime_type: string; file_storage_key?: string | undefined; url?: string | undefined; thumbnail_url?: string | undefined; preview_url?: string | undefined; size?: number | null | undefined; created_at?: string | undefined; document_template_id?: string | undefined; }[] | null; after: string | number | boolean | { key: string; label: string; }[] | { id: string; display: string; }[] | { id: string; name: string | null; image?: string | undefined; }[] | { id: string; filename: string; mime_type: string; file_storage_key?: string | undefined; url?: string | undefined; thumbnail_url?: string | undefined; preview_url?: string | undefined; size?: number | null | undefined; created_at?: string | undefined; document_template_id?: string | undefined; }[] | null; removed?: true | undefined; }[]; };
+export type ImportRun = { id: string; workflow: ImportWorkflow; at: string; end: "running" | "done" | "failed" | "partial"; added: number; changed: number; removed: number; until?: string | undefined; stopped?: { step?: string | undefined; reason?: string | undefined; } | undefined; };
+export type ImportWorkflow = { id: string; name: string; };
 /** What an aggregate asks: output columns to group by, an output date grouped by its day, an output number summed. */
 export type QueryAggregate = {
   by?: readonly string[];

package/dist/store.d.ts

@@ -4,6 +4,9 @@ export type Fetcher<T> = (askedAt: number, current: T | undefined) => Promise<T>
 export declare function tick(): number;
 /** Ask again every key reading one of `aliases` — every query key where none is named; an unmounted one on its next mount. */
 export declare function refetchReads(aliases: readonly string[] | undefined): void;
+/** The host's push, naming the aliases whose tables moved: each key reading one asked again (`refetchReads`), in one
+ *  paint. */
+export declare function refetchPushed(aliases: readonly string[]): void;
 export interface Held<T> {
     /** The answer shown: each staged value over it, else the answer; the last key's while a new key is first asked. */
     data: T | undefined;

package/docs/data_fetching.md

@@ -93,6 +93,7 @@ all its calls, and each call states its own `filter`, `sort`, `total` and `rows`
 |---|---|---|---|
 | `enabled` | `boolean` | `true` | `false` = no request is sent, `rows` is `[]`, `loading` is `false`. Flip to `true` to fetch. The gate for search-as-you-type and on-demand detail. Disabling also **hides** previously loaded rows (the cached answer survives; it re-renders instantly when re-enabled). |
 | `revalidateOnFocus` | `boolean` | `true` | `false` = no re-read on window focus / tab return / network reconnect (`refetch()` still works). Keep the default for dashboards; turn off for transient queries (a search bound to an ephemeral term) where a refocus re-run is wasted work and a visible reload. |
+| `revalidateOnChange` | `boolean` | `true` | `false` = no re-read on a realtime push or this app's own write over the query's tables: the rows stay as first read until `refetch()`, this app's own writes still drawn over them — a moment's rows (what an import touched, read beside a live register) that never join the render a push draws. A read of the same call left on the default is its own read, live. |
 | `sort` | `QuerySortKey[]` | — | Runtime sort, applied server-side **after** the named query, over its output columns, each key breaking the ties of the ones before: `{ field_key, order: "asc" \| "desc", blank_position? }` a column's order, or `{ first: [filter, …] }` the rows each filter keeps, in turn, before the rest ([queries](./queries.md)). An empty/omitted array leaves the query's own order intact. Part of the read's key — changing it re-queries. |
 | `filter` | `QueryFilter` | — | Runtime filter, applied server-side after the named query, over its output columns. A single condition or a recursive `{ node_type: "group", logic: "and" \| "or", children }`. Part of the read's key. |
 | `limit` | `number` | — | The first `limit` rows only — a **cap**, not pages; omit to read up to the server's row cap. |
@@ -145,9 +146,11 @@ write it as `{ node_type: "condition", type: "record_id", operator, value }`.
   renders the cached rows instantly *and* re-reads them in the background, so a list reflects what
   another screen changed while you were away. Identical concurrent reads share one request, and reads asked within a few milliseconds of each other go to the server together, each answered or refused on its own.
   Freshness comes from four places — arrival, window focus / tab return / network reconnect
-  (`revalidateOnFocus`, default on; a read asked within the last few seconds is not asked again),
-  a **realtime push**, and **this app's own successful write**, which re-reads the mounted queries
-  over the tables its body names without being asked (see [./mutations.md](./mutations.md)).
+  (`revalidateOnFocus`, default on; a read asked within the last few seconds is not asked again,
+  and the reads it asks again re-render together, as a push's do — so what changed while the tab
+  was hidden or offline lands in one piece), a **realtime push**, and **this app's own successful
+  write**, which re-reads the mounted queries over the tables its body names without being asked
+  (see [./mutations.md](./mutations.md)) — the last two never for a read with `revalidateOnChange: false`.
   `refetch()` covers what none of those can know about.
 - **This app's own writes show from the press.** Every read draws each write this app has made
   over its rows before the server answers — cells, membership, new rows, `total`, `counts` and
@@ -157,7 +160,9 @@ write it as `{ node_type: "condition", type: "record_id", operator, value }`.
 - **Realtime push keeps an already-open screen current.** When a table one of your queries reads
   changes — another member, a workflow, the chat agent, or an external agent writing over the CLI or
   MCP — that query refetches within about a second. Nothing to wire: it follows from the query's own
-  declaration, and only the aliases whose tables actually moved refetch. It carries RECORD
+  declaration, and only the aliases whose tables actually moved refetch. The queries one push names
+  re-render together — each answer held until all have landed, never past a second — so a screen never
+  shows one change in pieces and a slow query never holds the rest. It carries RECORD
   changes only (a schema edit does not push), and a **standalone/public app has no host**, so
   those apps keep focus/reconnect freshness alone. Push is absent whenever the channel cannot
   connect, so never treat it as a replacement for pull.

package/docs/members_and_options.md

@@ -392,7 +392,9 @@ const older = useRecordActivity("job", recordId, { after: next });
 - **One entry per save.** Edits by one actor on one record less than ten minutes apart read as one
   entry: each field from its value before the first edit to its value after the last, a field edited
   back to where it began dropped (and an entry left with nothing). A comment, another actor or a
-  longer pause starts another entry. `at` is the entry's first write, `until` its last.
+  longer pause starts another entry, and the save that made the record is an entry alone (`created`):
+  its maker's edits after it, however soon, are entries of their own. `at` is the entry's first
+  write, `until` its last.
 - **An entry** (`ActivityEntry`) is `kind: "change"` with `changes`, or `kind: "comment"` with
   `comment: { id, body, mentions }`. `actor`: `{ kind, id, name, image? }` — `member` (a person),
   `agent` (an AI acting for a member: the chat, an app's agent, an MCP client — named by that
@@ -410,6 +412,45 @@ const older = useRecordActivity("job", recordId, { after: next });
 - **Freshness:** read again when a push or this app's own write names the entity's reads, when a
   comment is written or deleted through `useComments`, on focus, and on `refetch()`.
 
+## A register's imports log: `useImportsLog`, `useImportRun`
+
+The workflows marked as importing into the register's table (an automation's `imports_into`) and
+their runs, each with how it ended and how many rows it added, changed and removed; and one run's
+rows, each with its fields before and after (`dist/imports.d.ts`). A JSON app whose model states
+`register.imports: true` keeps it. `entity` is the register's entity alias.
+
+```tsx
+const { workflows, runs, next, loading, error, available, refetch } = useImportsLog("order");
+const { run, rows } = useImportRun("order", runs[0]?.id ?? "");
+```
+
+- **Authority: the app's own reads**, as record activity's: only the fields the app reads appear, and
+  a row counts — and is listed — only where the register's own read reaches it for the viewer; a
+  removed row, where it reached it before it was removed. A row the viewer does not see is in no
+  count and does not make a failed run `partial`.
+- **Members of the app's organization only.** Standalone, in a host that bridges no imports log, and
+  where the register keeps none (the server answers `{ kind: "none" }`), `available` is `false`,
+  `error` is `null` and nothing is shown. Any other refusal is an `error`.
+- **The workflows** (`ImportWorkflow`): `{ id, name }`, every one importing into the table whether
+  or not it has run, by name.
+- **A run** (`ImportRun`): `{ id, workflow: { id, name }, at, until?, end, added, changed, removed,
+  stopped? }`. `end` is `running`, `done`, `failed` (it wrote none of the rows the viewer sees) or
+  `partial` (it failed after writing some). `until` is absent while it runs. A `failed` or `partial`
+  run carries `stopped: { step?, reason? }` (`ImportRunStop`): the description of the step it stopped
+  at, for every viewer; and the error it recorded there, only for a viewer who manages the automation
+  (it can quote data from tables the viewer cannot open) — each absent where the run recorded none.
+- **A run's row** (`ImportRow`): `{ record_id, kind, at, changes }`, one per row however many times
+  the run wrote it — `added`, `removed`, or `changed` (a field the viewer sees left other than the
+  run found it). `changes` are record activity's (`ActivityChange`): an added row's fields from
+  `null`, a removed row's to `null`. Rows come in the order the run first wrote them.
+- **Pages**: up to twenty runs — fewer where they wrote thousands of rows between them, always at
+  least one — or fifty rows; `next` continues — `undefined` at the end. A page of rows may hold fewer
+  and still say `next`, where the rows it looked through were ones the viewer does not see.
+- **Freshness:** the log is read again once pushes naming the entity's rows have stopped for two
+  seconds — an import's writes landing — never with each push, so the register's own rows never wait
+  on it; a run's rows only while it runs. Both are read again on focus and on `refetch()`. A run that
+  wrote nothing pushes nothing.
+
 ## Where each hook works
 
 | Surface | Embedded (signed-in member) | Standalone / public (anonymous) |
@@ -422,3 +463,4 @@ const older = useRecordActivity("job", recordId, { after: next });
 | `useWorkspaceTimezone` / `useWorkspaceCurrency` | ✓ | ✓ |
 | `useComments` / `useCommentCounts` | ✓ when capability declared | ✗ `available: false` |
 | `useRecordActivity` | ✓ the app's organization's members | ✗ `available: false` |
+| `useImportsLog` / `useImportRun` | ✓ the app's organization's members | ✗ `available: false` |

package/docs/security.md

@@ -11,6 +11,7 @@ Every data operation an app performs — queries, workflows, agent runs — exec
 | Agent runs (`useAgentRun`) | App owner | Yes — requires an authenticated member; runs are private to that member |
 | Comments (`useComments`) | App authority for **access**; the **author** is always the real member | Always — members-only, anonymous callers are rejected |
 | Record activity (`useRecordActivity`) | The app's own read of the record — the entity's read of one row, and only the fields it draws | Always — the app's organization's members only |
+| Imports log (`useImportsLog`, `useImportRun`) | The register's own read — only the rows it reaches for the viewer, and only the fields the app reads | Always — the app's organization's members only |
 
 Consequences of owner authority:
 
@@ -103,6 +104,7 @@ A publicly-shared app (its own origin, or its public link) is reachable by **any
 | Agent runs (`useAgentRun`) | **No** — rejected: agent runs require an authenticated member, and each member's run history is private to them (a guessed session id cannot read another member's thread) |
 | Comments (`useComments`) | **No** — members-only |
 | Record activity (`useRecordActivity`) | **No** — the app's organization's members only |
+| Imports log (`useImportsLog`, `useImportRun`) | **No** — the app's organization's members only |
 | Member roster (`useMembers`) | **No** — same-org members only (below) |
 
 **Warning — `is_current_member` on a public app resolves to the app owner.** An anonymous request has no viewer to bind, so both `is_current_member` and `current_member in_any_group` fall back to the owner's identity and the owner's groups. A "my items" query shows every anonymous visitor the *owner's* items, and a manager-only read template gated on a group the owner belongs to **passes for every anonymous visitor**. Never rely on viewer-bound predicates in a public app.

package/docs/workflows.md

@@ -704,7 +704,7 @@ tool calls it makes**, and the two cheapest wins are always the same: don't fetc
 have, and don't write one row at a time.
 
 **A write costs more than a read.** A create or update drags its computed-field cascades, rollups
-and `after_*` hooks behind it before the call returns, so trimming reads is worth less than
+and the table's checks behind it before the call returns, so trimming reads is worth less than
 trimming writes. Reach for the write-side reductions first.
 
 ### Batch every write — and build the array INLINE

package/package.json

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