@colixsystems/widget-sdk 0.268.1 → 0.270.0

package/README.md

@@ -50,7 +50,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **CORE** | `useTranslate()` | `{ translate, translating, error, language, available }` | `ctx.i18n.translate` — no scope. Machine-translates **user-generated content** (record text, file names, API payloads) into the app user's language; `useI18n().t()` is still the answer for your own copy. `translate(str)` → `Promise<string>`, `translate(str[])` → `Promise<string[]>` in ONE request. Target defaults to the app user's language. Cached per session, per pod, and durably per workspace, so repeat text is free. Limits: 50 segments / 5 000 chars each / 20 000 total. Rejects with `TranslateError`; `available` is false where the host cannot translate. |
 | **CORE** | `useLinkPreview(url)` | `{ preview, loading, error, available }` — `preview` is `{ url, title, description, site_name, image_url } \| null` | `ctx.linkPreviews.get` — no scope. A link's title, description, site name and image, fetched by the platform (the device never contacts the linked site). A page with nothing to show resolves with null fields, not an error — render the plain link. A non-http(s) `url` makes no request. Memoized for up to an hour across widgets; concurrent calls for one URL share a request. `error` is a `LinkPreviewError` (`VALIDATION` \| `AUTH_REQUIRED` \| `RATE_LIMITED` \| `NETWORK` \| `INTERNAL`). `available` is false on a host with no link-preview client |
 | **CORE** | `useStableQuery(buildQuery)` | `T \| undefined` (whatever `buildQuery()` returns) | No context slice, no scope. Keeps `buildQuery()`'s result at a STABLE reference across renders when its (JSON-serialised) content hasn't changed, so `useDatastoreQuery(tableId, useStableQuery(() => ({...})))` replaces a hand-rolled `useMemo` with an easy-to-get-wrong deps array. Never throws: a `buildQuery` that itself throws degrades to a stable `undefined`; a result that can't be diffed (e.g. circular) degrades to "always a new reference". |
-| **DATASTORE** (`ctx.datastore`) | `useDatastoreQuery(table, options)` (optional: options) | `{ data, total, loading, fetching, error, refetch }` — `loading` only until the first result for the table; a changed query / refetch keeps `data` while `fetching`; `total` is the envelope's `meta.total` | `records(table).list` (unwraps `{ data, meta }` to `data: []`) — `datastore.read:*`. `options` is `{ filter, filterMode, q, sort, limit, offset, includeCapabilities }`, applied on the server: see *Querying records*. |
+| **DATASTORE** (`ctx.datastore`) | `useDatastoreQuery(table, options)` (optional: options) | `{ data, total, loading, fetching, error, refetch }` — `loading` only until the first result for the table; a changed query / refetch keeps `data` while `fetching`; `total` is the envelope's `meta.total` | `records(table).list` (unwraps `{ data, meta }` to `data: []`) — `datastore.read:*`. `options` is `{ filter, filterMode, q, sort, limit, offset, includeCapabilities, live }`, applied on the server: see *Querying records*. `live: true` re-reads when anyone else changes the table: see *Live lists*. |
 | **DATASTORE** | `useDatastoreFigure(table, { aggregate, column, filter })` (optional: options) | `{ value, text, truncated, loading, fetching, error, refetch }` | `records(table).list` (a count reads the envelope total; a sum or average up to 1000 rows) — `datastore.read:*`. One count / sum / average for a `<Stat>`, computed exactly as the built-in Stat widget does. |
 | **DATASTORE** | `useDatastoreRecord(table, id, options)` (optional: options) | `{ data, loading, fetching, error, refetch }` — a refetch of the same record keeps `data` while `fetching`; `{ includeCapabilities: true }` adds `data._capabilities` | `records(table).get` — `datastore.read:<table>` |
 | **DATASTORE** | `useDatastoreSchema(tableId)` | `{ schema, loading, error, refetch }` | `schema(tableId)` — `datastore.read:<table>` |
@@ -58,8 +58,8 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **DATASTORE** | `useInterpretDraft(tableId)` | `{ interpret, interpreting, error, result, available }` | `interpret(tableId, body)` — `datastore.read:<table>`. Turns ONE sentence a user typed ("walk at 11 am tomorrow") into DRAFT column values so a form can prefill itself. IMPERATIVE: call `interpret(text, { fields?, timeZone? })` from an event handler, never on mount. It DRAFTS and writes nothing — show the values for review, then submit through `useDatastoreMutation().create`. Resolves to `{ values, unresolved }`; `values` is keyed by column NAME (the shape `create()` takes) and `unresolved` names the fields the sentence did not state. Only text / number / boolean / date / datetime / array columns are drafted — `FILE`, `RELATION`, `USER` and `USER_GROUP` carry ids and are never guessed. Fails closed to an empty draft. **Every call spends the workspace's AI credits** and is rate-limited per actor, so call it once per user action (never on mount or in a render loop); once the workspace runs out the call is refused with a generic 429 — an app user is deliberately **not** told the workspace's billing state, since they have never heard of an AI credit and cannot buy one. Never surface a raw error to the person filling the form: say drafting is unavailable and keep every field editable by hand. `available` is false where the host brokers no interpreter. |
 | **AGENTS** | `useAgent(agentRef)` | `{ send, cancel, reset, messages, sending, resuming, error, available }` | `ctx.agents` — `ai.invoke:*`. Hold a conversation with one of the WORKSPACE's own AI agents (an author-written name + system prompt). Sending is IMPERATIVE: call `send(text)` from an event handler, never on mount — the first send opens the conversation, so a widget nobody types into costs nothing. On mount the hook DOES reopen the caller's most recent thread with this agent, so a refresh or a navigation keeps the conversation instead of starting a blank one; that resume only READS and spends no credit. `resuming` is true while it runs — render a loading state, not an empty thread. `messages` is the running transcript, oldest first. You **cannot** set or read the system prompt, replay an edited transcript, or pick a model: the server assembles every turn from the stored prompt plus the stored history, and `content` is the only thing that reaches the wire. `reset()` drops the thread (a "new chat" affordance), and the new thread is the one a later mount resumes. **Every send spends the workspace's AI credits** and is rate-limited per caller AND per workspace. Rejects with `AgentError`; branch on `.code` — `AI_QUOTA_EXCEEDED` (429) is the workspace's credit ceiling and will NOT clear on a retry, unlike `RATE_LIMITED`, so never offer "try again" for it, and `AGENT_DISABLED` (409) means the author turned it off, so hide the affordance. Never surface a raw error or the workspace's billing state to an app user. `available` is false when no agent is bound or the host brokers none — render a visible unbound state, never a blank box. An assistant message that used a tool also carries **`activity`** — what the agent DID with the user's data: the table it read (with the `search` text and `filters` it read with), or the table and columns it CHANGED (never the values, and never a row the permissions refused). **Render a write.** A reply saying "done!" is not evidence a row was written, and if the agent got it wrong the user has no other way to notice. A talk-only turn omits the key entirely. |
 | **ACTIONS** | `useAction(actionRef)` | `{ available, run, running, result, error }` | `ctx.actions` — `actions.run:*`. Run one of the workspace's Actions from an event handler (never on mount) and read the value it passed to `respond()`. The Action needs the app trigger. `available` is false when nothing is bound or the host brokers no client. Errors are `ActionError` with a stable `code`. |
-| **DATASTORE** | `useDatastoreMutation(table)` | `{ create, update, delete }` | `records(table).{ create, update (PATCH), delete }` — `datastore.write:*`. **To CLEAR a cell, pass it empty** — `update(id, { when: null })` (also `""` or `[]`) empties that cell and it reads back as `null` (`[]` on an array column). There is no separate clear call, so never write a sentinel such as `0` or a placeholder date to mean "no value". `false` and `0` are values, not clears, and a REQUIRED column cannot be cleared. |
-| **DATASTORE** | `useDatastoreSubscription(table, handlers, options)` (optional: options) | `{ status }` — `"connecting" \| "live" \| "reconnecting" \| "fallback"` | `records(table).subscribe` — `datastore.read:<table>`. Live `onCreated` / `onUpdated` / `onDeleted` off the realtime socket; never throws, resolving to `{ status: "fallback" }` so the widget polls instead. A whole-table subscribe is gated on read-EVERY-row, because one envelope reaches every subscriber of the table — so for a table governed by per-record grants pass `options.scope`: `{ kind: "record", record_id }` for one row, or `{ kind: "parent", relation_column, record_id }` for the rows whose RELATION column points at that parent (the column must carry `inheritAcl`, else the subscribe reports `"fallback"`). For a live list of the signed-in user's own rows pass `{ kind: "granted" }`: every row they read through a grant to them or one of their groups, plus `onAccessGained(record)` / `onAccessLost({ id })` as rows enter and leave that set. Re-subscribes on the scope's VALUES, so a fresh object literal each render is fine. |
+| **DATASTORE** | `useDatastoreMutation(table)` | `{ create, update, delete }` | `records(table).{ create, update (PATCH), delete }` — `datastore.write:*`. A successful write re-reads every query, record, figure and aggregate on that table in every widget on the screen (a run of writes at most once a second, always once more after the last), so never refetch after it, and never write from an effect that re-runs on the data it reads unless a ref or Set marks what it already wrote. **To CLEAR a cell, pass it empty** — `update(id, { when: null })` (also `""` or `[]`) empties that cell and it reads back as `null` (`[]` on an array column). There is no separate clear call, so never write a sentinel such as `0` or a placeholder date to mean "no value". `false` and `0` are values, not clears, and a REQUIRED column cannot be cleared. |
+| **DATASTORE** | `useDatastoreSubscription(table, handlers, options)` (optional: options) | `{ status }` — `"connecting" \| "live" \| "reconnecting" \| "fallback"` | `records(table).subscribe` — `datastore.read:<table>`. To keep a list, record or figure current, pass `live: true` to its read hook instead (*Live lists*); this hook is for acting on each change. Live `onCreated` / `onUpdated` / `onDeleted` off the realtime socket; never throws, resolving to `{ status: "fallback" }` so the widget polls instead. A whole-table subscribe is gated on read-EVERY-row, because one envelope reaches every subscriber of the table — so for a table governed by per-record grants pass `options.scope`: `{ kind: "record", record_id }` for one row, or `{ kind: "parent", relation_column, record_id }` for the rows whose RELATION column points at that parent (the column must carry `inheritAcl`, else the subscribe reports `"fallback"`). For a live list of the signed-in user's own rows pass `{ kind: "granted" }`: every row they read through a grant to them or one of their groups, plus `onAccessGained(record)` / `onAccessLost({ id })` as rows enter and leave that set. Re-subscribes on the scope's VALUES, so a fresh object literal each render is fine. |
 | **DATASTORE** | `useTyping(tableId, recordId)` | `{ typingUserIds, setTyping, status }` — status `"connecting" \| "live" \| "unavailable"` | `records(table).typing` — `datastore.read:<table>`. Who else is typing in one record, over the same socket as `useDatastoreSubscription`. Call `setTyping(true)` on every keystroke (throttled to one signal per 3 s; `false` is sent after 5 s idle) and `setTyping(false)` on send, clear or blur. `typingUserIds` lists the OTHER users' ids; each drops out 6 s after their last signal. Needs a signed-in user who can read the record. Never throws: an anonymous visitor, a refused subscription or a host whose client lacks `typing` reads `{ typingUserIds: [], status: "unavailable" }`. Re-subscribes when either id changes. |
 | **DATASTORE** | `useRecordPermissions(tableId, recordId)` | `{ permissions, loading, error, grant, revoke, update, refetch }` | `records(table).permissions(record).{ list, grant, update, revoke }` — `acl.write:records` (+ `can_grant` on the record) |
 | **DATASTORE** | `useCanWrite(tableId, options)` (optional: options) | `{ canWrite, loading, error, refetch }` | `myPermissions(tableId, { recordId? })` — scope `datastore.read:<table>`. A FLOOR, not a full replacement for domain-specific write rules: answers "may this caller write", reading the same table-ACL answer the write endpoint enforces — so a table granting Create to Everyone answers `true` for a logged-out visitor, and this hook alone is the right gate for a widget meant to work without signing in. Pass `{ recordId }` for a per-row check. A widget whose own rule is MORE SPECIFIC than the table ACL (e.g. "only the assigned user may edit this row") must still hand-check that in addition. Pair with `useUser()` to also tell "not signed in" apart from "signed in but forbidden" — both resolve `canWrite: false` here. Falsy `tableId`, or a host that hasn't injected `myPermissions` (an older host), collapses to `{ canWrite: false, loading: false, error: null, refetch: async () => undefined }` rather than throwing. |
@@ -86,7 +86,39 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.268.1` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.270.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.270.0 (contract 1.220.0)
+
+**Live lists.** Add `live: true` to the object you already pass `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreFigure` or `useDatastoreAggregate`, and the read stays current when anyone else changes the table: `useDatastoreQuery(tableId, { sort: "created_at:desc", limit: 50, live: true })`. See *Live lists* below. The publish checker refuses a `setInterval` that re-reads records (`widget.refetchPoll`).
+
+#### Live lists
+
+- **What it does.** The read rides the table's realtime stream on the widget's one datastore socket (the same subscription `useDatastoreSubscription` uses), and each pushed change re-reads it the way a write does: a burst folds into one read, a busy table re-reads at most once a second and always once more after the last change. Without `live`, a read behaves exactly as before.
+- **Permissions.** The server admits the whole-table stream only for a viewer who can read every row. Otherwise a signed-in viewer streams the rows granted to them, filtered per row, and a signed-out visitor gets no stream. The re-read is the ordinary permission-checked read, so a change to a row the viewer cannot read never changes what they see. Where nothing can stream (no socket, a refused visitor) the read re-checks every 30 seconds.
+- **Table ids.** Pass the table id a `tableRef` property binds. A table name still reads, but only re-checks every 30 seconds.
+- **No jumping.** A live re-read keeps `data` on screen with `loading: false`; render rows with `key={row.id}` so the ones already shown keep their place. For a newest-first list people scroll, hold new rows behind an "N new" button instead of pushing the list down:
+
+```jsx
+const { data, loading } = useDatastoreQuery(tableId, { sort: "created_at:desc", limit: 50, live: true });
+const [seen, setSeen] = useState(null);
+useEffect(() => {
+  if (!loading && seen === null) setSeen(new Set(data.map((r) => r.id)));
+}, [loading, data, seen]);
+const shown = seen ? data.filter((r) => seen.has(r.id)) : data;
+const fresh = seen ? data.length - shown.length : 0;
+// {fresh > 0 ? <Button title={`${fresh} new`} onPress={() => setSeen(new Set(data.map((r) => r.id)))} /> : null}
+```
+
+- **Never hand-poll.** Don't call `refetch()` from `setInterval`, and don't wire `useDatastoreSubscription` just to refresh a list. Keep that hook for acting on each change (a toast, a sound).
+
+### What's new in 0.269.1 (contract 1.219.0)
+
+**Re-reads after a write are paced, and a write loop is refused.** A run of writes re-reads each widget at most once a second, and always once more after the last write; a reader that fetched on its own after the write is not re-read again. So a bulk loop of 500 saves costs each reader about one read a second, not 500, and the list still ends on the last save. An effect that saves and re-runs on the data it reads (or has no dependency list) would now save forever, because every save re-reads that data: keep the rows it already saved in a ref or a Set and return early, or save from the user's action. The publish checker refuses such an effect (`widget.writeLoopEffect`).
+
+### What's new in 0.269.0 (contract 1.219.0)
+
+**A write refreshes every widget that shows the table.** After a successful `create`, `update` or `delete` through `useDatastoreMutation`, every `useDatastoreQuery`, `useDatastoreRecord`, `useDatastoreFigure` and `useDatastoreAggregate` on the same table re-reads itself, in the widget that wrote and in every other widget on the screen, on the web Player and in the native app alike. Drop the `refetch()` you called after your own writes and any subscription you wired for them; `useDatastoreSubscription` stays for changes other people make. Widgets must address the table the same way (its id, as a `tableRef` property binds it) for the refresh to reach them.
 
 ### What's new in 0.268.1 (contract 1.218.0)
 

package/dist/contract.cjs

@@ -1354,7 +1354,8 @@ const HOOKS = [
       "keeps it in `data` with loading false while `fetching` is true; a " +
       "different table or record id resets to loading. " +
       "`{ includeCapabilities: true }` adds `_capabilities` to the row, as " +
-      "for useDatastoreQuery.",
+      "for useDatastoreQuery. `{ live: true }` re-reads it when anyone else " +
+      "changes the table.",
     returnShape: {
       data: "Record | null",
       loading: "boolean",
@@ -1938,7 +1939,15 @@ const HOOKS = [
       "enforce, computed for the whole page in one lookup. Gate a row's " +
       "Edit on `row._capabilities?.can_write` and Delete on `can_delete`. " +
       "`total` is how many rows the query matches in all (the envelope's " +
-      "meta.total), not just the page in `data`; null until known.",
+      "meta.total), not just the page in `data`; null until known. A " +
+      "successful useDatastoreMutation write to the table, from this widget " +
+      "or any other on the screen, re-reads it on its own: never refetch or " +
+      "subscribe for your own writes. Add `live: true` to the options to also " +
+      "re-read when anyone else changes the table (a pushed change, paced like " +
+      "a write; the re-read is the same permission-checked read, and keeps the " +
+      "rows on screen with loading false). Use it for lists other people " +
+      "change: queues, bookings, chat, dashboards. Never poll with setInterval " +
+      "or wire useDatastoreSubscription for that.",
     returnShape: {
       data: "Record[]",
       total: "number | null",
@@ -1952,8 +1961,8 @@ const HOOKS = [
   },
   {
     name: "useDatastoreFigure",
-    signature: "useDatastoreFigure(tableId, { aggregate, column, filter })",
-    optionalArgs: ["aggregate", "column", "filter"],
+    signature: "useDatastoreFigure(tableId, { aggregate, column, filter, live })",
+    optionalArgs: ["aggregate", "column", "filter", "live"],
     description:
       "ONE live figure over a table, for a `<Stat>`: `aggregate` is " +
       "\"count\" (the default; the rows, or the rows `filter` matches), \"sum\" " +
@@ -1968,7 +1977,8 @@ const HOOKS = [
       "or average reads up to 1000 rows, skips blank cells rather than counting " +
       "them as zero, and past that reads \"≈ n\" (`truncated: true`). The stock " +
       "Stat widget computes its figure through this hook, so use it rather than " +
-      "reducing useDatastoreQuery rows by hand. Call it once per figure.",
+      "reducing useDatastoreQuery rows by hand. Call it once per figure. " +
+      "`live: true` re-reads it when anyone else changes the table.",
     returnShape: {
       value: "number | null",
       text: "string | null  // the formatted figure for <Stat value>",
@@ -1986,8 +1996,8 @@ const HOOKS = [
   {
     name: "useDatastoreAggregate",
     signature:
-      "useDatastoreAggregate(tableId, { groupBy, bucket, from, to, sumColumn, filter, order, limit })",
-    optionalArgs: ["groupBy", "bucket", "from", "to", "sumColumn", "filter", "order", "limit"],
+      "useDatastoreAggregate(tableId, { groupBy, bucket, from, to, sumColumn, filter, order, limit, live })",
+    optionalArgs: ["groupBy", "bucket", "from", "to", "sumColumn", "filter", "order", "limit", "live"],
     description:
       "Counts rows on the server over EVERY row the viewer can read, so it is " +
       "exact past the 1000-row page a list read returns — never group " +
@@ -2006,7 +2016,8 @@ const HOOKS = [
       "them out with a `nempty:` filter. Encrypted, array, file and relation " +
       "columns cannot be grouped (VALIDATION). `filter` takes the same shapes " +
       "as useDatastoreQuery's, created_at ranges included. Pass null as the " +
-      "table until a bound table is known.",
+      "table until a bound table is known. `live: true` re-reads it when " +
+      "anyone else changes the table.",
     returnShape: {
       buckets:
         "Array<{ date, count, sum }>  // date = the bucket's start, YYYY-MM-DD; sum is 0 without sumColumn",
@@ -2212,6 +2223,15 @@ const HOOKS = [
   {
     name: "useDatastoreMutation",
     signature: "useDatastoreMutation(tableId)",
+    description:
+      "Creates, updates (partial) and deletes rows. A successful write re-reads " +
+      "every useDatastoreQuery, useDatastoreRecord, useDatastoreFigure and " +
+      "useDatastoreAggregate on the same table reference, in every widget on " +
+      "the screen, so no widget calls refetch() or subscribes for it. Readers " +
+      "must name the table the same way (its id, as a tableRef property binds it). " +
+      "A run of writes re-reads each reader at most once a second, always once " +
+      "more after the last. Never write from a useEffect that re-runs on the data " +
+      "it reads unless a ref or Set marks each row as already written: it loops.",
     returnShape: {
       create:
         "(record) => Promise<Record>  // rejects with DatastoreError { code, message, retryable } — render the message when retryable is false, never 'try again'",
@@ -2862,6 +2882,9 @@ const HOOKS = [
     signature: "useDatastoreSubscription(tableId, handlers, options)",
     optionalArgs: ["options"],
     description:
+      "To keep a list, record, figure or aggregate current, pass `live: true` " +
+      "to its read hook instead; this hook is for acting on each change " +
+      "(a toast, a sound, merging rows yourself). " +
       "Subscribe to a table's realtime change stream via the injected " +
       "datastore-client at ctx.datastore.records(tableId).subscribe(...). " +
       "handlers is { onCreated?, onUpdated?, onDeleted? }; each receives the " +
@@ -6481,7 +6504,11 @@ const CONTRACT = deepFreeze({
   // 1.218.0: additive (sc-14224) — the actions client's `status(actionId)`;
   //    `useAction().available` turns false when the server says a run would
   //    not reach the script.
-  version: "1.218.0",
+  // 1.219.0: behaviour (sc-14407) — a useDatastoreMutation write re-reads
+  //    every query, record, figure and aggregate on that table, app-wide.
+  // 1.220.0: additive (sc-14423) — `live: true` on useDatastoreQuery,
+  //    useDatastoreRecord, useDatastoreFigure and useDatastoreAggregate.
+  version: "1.220.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1351,7 +1351,8 @@ const HOOKS = [
       "keeps it in `data` with loading false while `fetching` is true; a " +
       "different table or record id resets to loading. " +
       "`{ includeCapabilities: true }` adds `_capabilities` to the row, as " +
-      "for useDatastoreQuery.",
+      "for useDatastoreQuery. `{ live: true }` re-reads it when anyone else " +
+      "changes the table.",
     returnShape: {
       data: "Record | null",
       loading: "boolean",
@@ -1935,7 +1936,15 @@ const HOOKS = [
       "enforce, computed for the whole page in one lookup. Gate a row's " +
       "Edit on `row._capabilities?.can_write` and Delete on `can_delete`. " +
       "`total` is how many rows the query matches in all (the envelope's " +
-      "meta.total), not just the page in `data`; null until known.",
+      "meta.total), not just the page in `data`; null until known. A " +
+      "successful useDatastoreMutation write to the table, from this widget " +
+      "or any other on the screen, re-reads it on its own: never refetch or " +
+      "subscribe for your own writes. Add `live: true` to the options to also " +
+      "re-read when anyone else changes the table (a pushed change, paced like " +
+      "a write; the re-read is the same permission-checked read, and keeps the " +
+      "rows on screen with loading false). Use it for lists other people " +
+      "change: queues, bookings, chat, dashboards. Never poll with setInterval " +
+      "or wire useDatastoreSubscription for that.",
     returnShape: {
       data: "Record[]",
       total: "number | null",
@@ -1949,8 +1958,8 @@ const HOOKS = [
   },
   {
     name: "useDatastoreFigure",
-    signature: "useDatastoreFigure(tableId, { aggregate, column, filter })",
-    optionalArgs: ["aggregate", "column", "filter"],
+    signature: "useDatastoreFigure(tableId, { aggregate, column, filter, live })",
+    optionalArgs: ["aggregate", "column", "filter", "live"],
     description:
       "ONE live figure over a table, for a `<Stat>`: `aggregate` is " +
       "\"count\" (the default; the rows, or the rows `filter` matches), \"sum\" " +
@@ -1965,7 +1974,8 @@ const HOOKS = [
       "or average reads up to 1000 rows, skips blank cells rather than counting " +
       "them as zero, and past that reads \"≈ n\" (`truncated: true`). The stock " +
       "Stat widget computes its figure through this hook, so use it rather than " +
-      "reducing useDatastoreQuery rows by hand. Call it once per figure.",
+      "reducing useDatastoreQuery rows by hand. Call it once per figure. " +
+      "`live: true` re-reads it when anyone else changes the table.",
     returnShape: {
       value: "number | null",
       text: "string | null  // the formatted figure for <Stat value>",
@@ -1983,8 +1993,8 @@ const HOOKS = [
   {
     name: "useDatastoreAggregate",
     signature:
-      "useDatastoreAggregate(tableId, { groupBy, bucket, from, to, sumColumn, filter, order, limit })",
-    optionalArgs: ["groupBy", "bucket", "from", "to", "sumColumn", "filter", "order", "limit"],
+      "useDatastoreAggregate(tableId, { groupBy, bucket, from, to, sumColumn, filter, order, limit, live })",
+    optionalArgs: ["groupBy", "bucket", "from", "to", "sumColumn", "filter", "order", "limit", "live"],
     description:
       "Counts rows on the server over EVERY row the viewer can read, so it is " +
       "exact past the 1000-row page a list read returns — never group " +
@@ -2003,7 +2013,8 @@ const HOOKS = [
       "them out with a `nempty:` filter. Encrypted, array, file and relation " +
       "columns cannot be grouped (VALIDATION). `filter` takes the same shapes " +
       "as useDatastoreQuery's, created_at ranges included. Pass null as the " +
-      "table until a bound table is known.",
+      "table until a bound table is known. `live: true` re-reads it when " +
+      "anyone else changes the table.",
     returnShape: {
       buckets:
         "Array<{ date, count, sum }>  // date = the bucket's start, YYYY-MM-DD; sum is 0 without sumColumn",
@@ -2209,6 +2220,15 @@ const HOOKS = [
   {
     name: "useDatastoreMutation",
     signature: "useDatastoreMutation(tableId)",
+    description:
+      "Creates, updates (partial) and deletes rows. A successful write re-reads " +
+      "every useDatastoreQuery, useDatastoreRecord, useDatastoreFigure and " +
+      "useDatastoreAggregate on the same table reference, in every widget on " +
+      "the screen, so no widget calls refetch() or subscribes for it. Readers " +
+      "must name the table the same way (its id, as a tableRef property binds it). " +
+      "A run of writes re-reads each reader at most once a second, always once " +
+      "more after the last. Never write from a useEffect that re-runs on the data " +
+      "it reads unless a ref or Set marks each row as already written: it loops.",
     returnShape: {
       create:
         "(record) => Promise<Record>  // rejects with DatastoreError { code, message, retryable } — render the message when retryable is false, never 'try again'",
@@ -2859,6 +2879,9 @@ const HOOKS = [
     signature: "useDatastoreSubscription(tableId, handlers, options)",
     optionalArgs: ["options"],
     description:
+      "To keep a list, record, figure or aggregate current, pass `live: true` " +
+      "to its read hook instead; this hook is for acting on each change " +
+      "(a toast, a sound, merging rows yourself). " +
       "Subscribe to a table's realtime change stream via the injected " +
       "datastore-client at ctx.datastore.records(tableId).subscribe(...). " +
       "handlers is { onCreated?, onUpdated?, onDeleted? }; each receives the " +
@@ -6478,7 +6501,11 @@ const CONTRACT = deepFreeze({
   // 1.218.0: additive (sc-14224) — the actions client's `status(actionId)`;
   //    `useAction().available` turns false when the server says a run would
   //    not reach the script.
-  version: "1.218.0",
+  // 1.219.0: behaviour (sc-14407) — a useDatastoreMutation write re-reads
+  //    every query, record, figure and aggregate on that table, app-wide.
+  // 1.220.0: additive (sc-14423) — `live: true` on useDatastoreQuery,
+  //    useDatastoreRecord, useDatastoreFigure and useDatastoreAggregate.
+  version: "1.220.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/datastore-figure.js

@@ -9,8 +9,9 @@ import { figureQuery, reduceFigure } from "./figure.js";
  * `filter` keeps the previous figure on screen while `fetching`.
  */
 export function useDatastoreFigure(table, options) {
-  const { aggregate, column, filter } = options || {};
-  const rows = useDatastoreQuery(table || null, figureQuery(filter, aggregate));
+  const { aggregate, column, filter, live } = options || {};
+  const query = figureQuery(filter, aggregate);
+  const rows = useDatastoreQuery(table || null, live === true ? { ...query, live } : query);
   const figure =
     table && !rows.loading && !rows.error
       ? reduceFigure(rows.data, { aggregate, column }, rows.total)

package/dist/hooks.js

@@ -28,6 +28,7 @@ import React, {
   useRef,
   useState,
 } from "react";
+import { watchTableChanges } from "./live-table.js";
 // REQ-L10N-WIDGET / REQ-L10N-SHARED: the translation key formats live in ONE
 // place (contract.js). useI18n (lookup) and the backend seeder (write) both
 // call them so the namespaced keys can never drift between the two sides.
@@ -2888,6 +2889,112 @@ function serializeQuery(query) {
 }
 
 const queryResultKey = (table, queryKey) => JSON.stringify([table, queryKey]);
+
+// sc-14407 — every widget of a running app shares this module (the web host
+// hands custom widgets its own SDK; the native bundle has one copy), so a
+// write through any widget re-reads every other widget's rows on that table.
+// A burst of writes folds into one re-read; a long run of them re-reads each
+// widget at most once a second, and always once more after the last write.
+// sc-14423 — a change someone else made reaches only `live` readers, paced
+// the same way.
+const TABLE_WRITE_SETTLE_MS = 50;
+const TABLE_REREAD_INTERVAL_MS = 1000;
+const tableWrites = new Map();
+// Orders writes and fetch starts: a fetch begun after a write already has its rows.
+let readWriteOrder = 0;
+
+/** Internal: stamps the start of a reader's fetch, for useRereadOnWrite. */
+export function stampFetchStart(ref) {
+  readWriteOrder += 1;
+  ref.current = readWriteOrder;
+}
+
+function tableWritesOf(table) {
+  let entry = tableWrites.get(table);
+  if (!entry) {
+    entry = { listeners: new Set(), timer: null, lastRereadAt: -Infinity, wroteAt: 0, changedAt: 0 };
+    tableWrites.set(table, entry);
+  }
+  return entry;
+}
+
+function forgetIfIdle(table, entry) {
+  if (entry.listeners.size === 0 && !entry.timer && tableWrites.get(table) === entry) tableWrites.delete(table);
+}
+
+function rereadTable(table, entry) {
+  entry.timer = null;
+  entry.lastRereadAt = Date.now();
+  for (const listener of Array.from(entry.listeners)) {
+    try {
+      listener(entry);
+    } catch (_e) {
+      // A reader's failure must never reach the write that already succeeded.
+    }
+  }
+  forgetIfIdle(table, entry);
+}
+
+function announceTableChange(table, { local }) {
+  const entry = tableWritesOf(table);
+  readWriteOrder += 1;
+  entry.changedAt = readWriteOrder;
+  if (local) entry.wroteAt = readWriteOrder;
+  if (entry.timer) return;
+  const wait = Math.max(TABLE_WRITE_SETTLE_MS, entry.lastRereadAt + TABLE_REREAD_INTERVAL_MS - Date.now());
+  entry.timer = setTimeout(() => rereadTable(table, entry), wait);
+}
+
+/**
+ * Internal: shared with stats-hooks.js, not re-exported by the index. Runs
+ * `reread` after a successful useDatastoreMutation write to `table`, from any
+ * widget, unless the reader began a fetch of its own (stamped into
+ * `fetchStartRef` by stampFetchStart) after that write. Keyed by the table
+ * reference exactly as the widgets pass it.
+ *
+ * sc-14423 — `live` also re-reads when anyone else changes the table, through
+ * the widget's datastore client's realtime subscription (see live-table.js).
+ */
+export function useRereadOnWrite(table, reread, fetchStartRef, live = false) {
+  const ctx = useContext(HostWidgetContext);
+  const rereadRef = useRef(reread);
+  rereadRef.current = reread;
+  const liveRef = useRef(live);
+  liveRef.current = live;
+  useEffect(() => {
+    if (!table) return undefined;
+    const entry = tableWritesOf(table);
+    const listener = ({ wroteAt, changedAt }) => {
+      const since = liveRef.current ? changedAt : wroteAt;
+      if (!since || (fetchStartRef && fetchStartRef.current > since)) return;
+      rereadRef.current();
+    };
+    entry.listeners.add(listener);
+    return () => {
+      entry.listeners.delete(listener);
+      forgetIfIdle(table, entry);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [table]);
+
+  const recordsRef = useRef(null);
+  recordsRef.current = ctx && ctx.datastore && typeof ctx.datastore.records === "function" ? ctx.datastore.records : null;
+  const signedIn = Boolean(ctx && ctx.user && ctx.user.id);
+  useEffect(() => {
+    if (!live || !table || !recordsRef.current) return undefined;
+    let ns;
+    try {
+      ns = recordsRef.current(table);
+    } catch (_e) {
+      return undefined;
+    }
+    return watchTableChanges(ns, {
+      tableId: table,
+      signedIn,
+      onChange: () => announceTableChange(table, { local: false }),
+    });
+  }, [table, live, signedIn]);
+}
 const recordResultKey = (table, recordId, includeCapabilities = false) =>
   JSON.stringify([table, recordId, includeCapabilities]);
 
@@ -2961,6 +3068,7 @@ export function useDatastoreQuery(table, query) {
   recordsRef.current = ctx.datastore.records;
 
   const runRef = useRef(0);
+  const fetchStartRef = useRef(0);
 
   const doFetch = useCallback(async () => {
     const myRun = ++runRef.current;
@@ -2972,6 +3080,7 @@ export function useDatastoreQuery(table, query) {
       setSettled(NO_QUERY_RESULT);
       return;
     }
+    stampFetchStart(fetchStartRef);
     const key = queryResultKey(t, serializeQuery(queryRef.current));
     setInFlight(true);
     try {
@@ -3041,6 +3150,7 @@ export function useDatastoreQuery(table, query) {
   // sc-1179 — auto-subscribe to the page-level refresh tick so a
   // pull-to-refresh on mobile re-runs the query without per-widget code.
   useRefresh(refetch);
+  useRereadOnWrite(table, refetch, fetchStartRef, Boolean(query && query.live === true));
 
   const currentKey = table ? queryResultKey(table, queryKey) : null;
   const busy = Boolean(table) && (settled.key !== currentKey || inFlight);
@@ -3106,6 +3216,7 @@ export function useDatastoreRecord(table, recordId, options) {
   recordsRef.current = ctx.datastore.records;
 
   const runRef = useRef(0);
+  const fetchStartRef = useRef(0);
 
   const doFetch = useCallback(async () => {
     const myRun = ++runRef.current;
@@ -3116,6 +3227,7 @@ export function useDatastoreRecord(table, recordId, options) {
       setSettled(NO_RECORD_RESULT);
       return;
     }
+    stampFetchStart(fetchStartRef);
     const key = recordResultKey(t, id, includeCapabilitiesRef.current);
     setInFlight(true);
     try {
@@ -3149,6 +3261,7 @@ export function useDatastoreRecord(table, recordId, options) {
 
   // sc-1179 — auto-subscribe to the page-level refresh tick.
   useRefresh(refetch);
+  useRereadOnWrite(recordId ? table : null, refetch, fetchStartRef, options?.live === true);
 
   const currentKey =
     table && recordId ? recordResultKey(table, recordId, includeCapabilities) : null;
@@ -4044,68 +4157,31 @@ export function useDatastoreMutation(table) {
   tableRef.current = table;
   recordsRef.current = ctx.datastore.records;
 
-  // Resolve records(table) lazily. Returns null when no table is bound so
-  // the callbacks reject with a clear VALIDATION error rather than letting
-  // the client's raw TypeError surface (or crashing at render).
-  const resolveNs = useCallback(() => {
+  // Resolve records(table) lazily, so an unbound widget rejects with a clear
+  // VALIDATION error instead of crashing at render. A successful write
+  // re-reads every widget showing this table (sc-14407).
+  const write = useCallback(async (verb, run) => {
     const t = tableRef.current;
-    if (!t) return null;
-    return recordsRef.current(t);
+    if (!t) {
+      throw new DatastoreError(
+        "VALIDATION",
+        `useDatastoreMutation: no table bound — set a source table before ${verb} a record.`,
+      );
+    }
+    const ns = recordsRef.current(t);
+    let result;
+    try {
+      result = await run(ns);
+    } catch (err) {
+      throw toDatastoreError(err);
+    }
+    announceTableChange(t, { local: true });
+    return result;
   }, []);
 
-  const create = useCallback(
-    async (values) => {
-      const ns = resolveNs();
-      if (!ns) {
-        throw new DatastoreError(
-          "VALIDATION",
-          "useDatastoreMutation: no table bound — set a source table before creating a record.",
-        );
-      }
-      try {
-        return await ns.create(values);
-      } catch (err) {
-        throw toDatastoreError(err);
-      }
-    },
-    [resolveNs],
-  );
-
-  const update = useCallback(
-    async (id, values) => {
-      const ns = resolveNs();
-      if (!ns) {
-        throw new DatastoreError(
-          "VALIDATION",
-          "useDatastoreMutation: no table bound — set a source table before updating a record.",
-        );
-      }
-      try {
-        return await ns.update(id, values);
-      } catch (err) {
-        throw toDatastoreError(err);
-      }
-    },
-    [resolveNs],
-  );
-
-  const del = useCallback(
-    async (id) => {
-      const ns = resolveNs();
-      if (!ns) {
-        throw new DatastoreError(
-          "VALIDATION",
-          "useDatastoreMutation: no table bound — set a source table before deleting a record.",
-        );
-      }
-      try {
-        return await ns.delete(id);
-      } catch (err) {
-        throw toDatastoreError(err);
-      }
-    },
-    [resolveNs],
-  );
+  const create = useCallback((values) => write("creating", (ns) => ns.create(values)), [write]);
+  const update = useCallback((id, values) => write("updating", (ns) => ns.update(id, values)), [write]);
+  const del = useCallback((id) => write("deleting", (ns) => ns.delete(id)), [write]);
 
   // sc-10268: one object while the methods are unchanged, so a widget can list
   // the mutation in a dependency array without re-running every render.

package/dist/index.d.ts

@@ -1099,6 +1099,11 @@ export interface Query {
    * that row. Gate a row's Edit / Delete on it.
    */
   includeCapabilities?: boolean;
+  /**
+   * Re-read when anyone else changes the table, paced like a write and keeping
+   * the rows on screen. For lists other people change; never poll by hand.
+   */
+  live?: boolean;
 }
 
 /**
@@ -1148,6 +1153,11 @@ export interface FigureOptions {
   filter?:
     | Query["filter"]
     | Array<{ column: string; operator: string; value?: unknown; valueMode?: string }>;
+  /**
+   * Re-read when anyone else changes the table, paced like a write and keeping
+   * the figure on screen. Never poll by hand.
+   */
+  live?: boolean;
 }
 
 export interface FigureResult {
@@ -1180,6 +1190,8 @@ export interface AggregateBucketSpec {
   /** A plain number column to add up per bucket. */
   sumColumn?: string;
   filter?: FigureOptions["filter"];
+  /** Re-read when anyone else changes the table. */
+  live?: boolean;
 }
 
 export interface AggregateGroupSpec {
@@ -1192,6 +1204,8 @@ export interface AggregateGroupSpec {
   order?: "count:desc" | "count:asc" | "sum:desc" | "sum:asc" | "group:asc" | "group:desc";
   /** 1–1000. */
   limit?: number;
+  /** Re-read when anyone else changes the table. */
+  live?: boolean;
 }
 
 export interface AggregateBucket {
@@ -1626,7 +1640,7 @@ export function useWidgetStyle(): Record<string, unknown>;
 export function useDatastoreRecord(
   tableId: string | null | undefined,
   recordId: string | null | undefined,
-  options?: { includeCapabilities?: boolean },
+  options?: { includeCapabilities?: boolean; /** Re-read when anyone else changes the table. */ live?: boolean },
 ): {
   data: unknown | null;
   loading: boolean;

package/dist/live-table.js

@@ -0,0 +1,105 @@
+// sc-14423 — what keeps a `live: true` read current. No React, so the
+// backend's end-to-end test drives this same code.
+
+/** How often a live read re-reads while no realtime stream reaches it. */
+export const LIVE_POLL_MS = 30000;
+
+const GRANTED_SCOPE = Object.freeze({ kind: "granted" });
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Calls `onChange()` whenever someone may have changed the table behind `ns`
+ * (`records(tableId)`); it carries no row, the caller re-reads.
+ *
+ * Streams the whole table through the client's shared subscription. Until
+ * that goes live, a signed-in viewer also streams their granted rows (the
+ * server refuses the whole table to a viewer who cannot read every row).
+ * While nothing streams it polls; after any gap it reports one change.
+ *
+ * @param {object} ns
+ * @param {{ tableId: string, signedIn?: boolean, onChange: () => void }} options
+ * @returns {() => void} stop
+ */
+export function watchTableChanges(ns, { tableId, signedIn = false, onChange }) {
+  const streamable = Boolean(ns && typeof ns.subscribe === "function" && UUID_RE.test(tableId || ""));
+  const statuses = new Map();
+  const releases = new Map();
+  let stopped = false;
+  let pollTimer = null;
+  let live = false;
+  let missed = false;
+  let tableWasLive = false;
+
+  const changed = () => {
+    if (!stopped) onChange();
+  };
+
+  function settle() {
+    const all = [...statuses.values()];
+    const nowLive = all.includes("live");
+    if (nowLive && !live && missed) changed();
+    if (!nowLive && (live || all.includes("fallback"))) missed = true;
+    if (nowLive) missed = false;
+    live = nowLive;
+    if (!live && all.every((s) => s === "fallback")) {
+      if (!pollTimer) pollTimer = setInterval(changed, LIVE_POLL_MS);
+    } else if (pollTimer) {
+      clearInterval(pollTimer);
+      pollTimer = null;
+    }
+  }
+
+  function close(name) {
+    releases.get(name)?.();
+    releases.delete(name);
+    statuses.delete(name);
+  }
+
+  function update(name, status) {
+    if (stopped || !statuses.has(name)) return;
+    statuses.set(name, status);
+    if (name === "table" && status === "live") {
+      tableWasLive = true;
+      if (statuses.has("granted")) close("granted");
+    }
+    if (name === "table" && status === "fallback" && !tableWasLive && streamable && signedIn && !statuses.has("granted")) {
+      open("granted", GRANTED_SCOPE);
+    }
+    settle();
+  }
+
+  function open(name, scope) {
+    statuses.set(name, "connecting");
+    try {
+      const release = ns.subscribe(
+        {
+          onCreated: changed,
+          onUpdated: changed,
+          onDeleted: changed,
+          onAccessGained: changed,
+          onAccessLost: changed,
+          onStatus: (s) => update(name, s),
+        },
+        scope ? { scope } : undefined,
+      );
+      if (typeof release === "function" && statuses.has(name)) releases.set(name, release);
+      else if (typeof release === "function") release();
+    } catch (_e) {
+      update(name, "fallback");
+    }
+  }
+
+  if (streamable) open("table", null);
+  else {
+    statuses.set("table", "fallback");
+    settle();
+  }
+
+  return function stop() {
+    stopped = true;
+    if (pollTimer) clearInterval(pollTimer);
+    pollTimer = null;
+    for (const release of releases.values()) release();
+    releases.clear();
+  };
+}

package/dist/stats-hooks.js

@@ -6,6 +6,8 @@ import {
   toDatastoreError,
   toDirectoryError,
   useRefresh,
+  stampFetchStart,
+  useRereadOnWrite,
   useWidgetContextOrThrow,
 } from "./hooks.js";
 
@@ -27,7 +29,7 @@ function serialize(value) {
  * keeps the previous data on screen (`fetching`); a new identity starts over
  * (`loading`). A null key is "nothing to read" and settles empty.
  */
-function useKeyedRead(read, identity, key, mapError) {
+function useKeyedRead(read, identity, key, mapError, fetchStartRef) {
   const readRef = useRef(read);
   readRef.current = read;
   const runRef = useRef(0);
@@ -42,6 +44,7 @@ function useKeyedRead(read, identity, key, mapError) {
       return;
     }
     setFetching(true);
+    if (fetchStartRef) stampFetchStart(fetchStartRef);
     try {
       const data = await readRef.current();
       if (runRef.current === myRun) setSettled({ identity, key, data, error: null });
@@ -97,6 +100,7 @@ export function useDatastoreAggregate(table, spec) {
     ? serialize(byDate ? [groupBy, bucket, from, to, sumColumn, filter] : [groupBy, sumColumn, filter, order, limit])
     : null;
   const records = ctx.datastore.records;
+  const fetchStartRef = useRef(0);
 
   const result = useKeyedRead(
     async () => {
@@ -111,7 +115,9 @@ export function useDatastoreAggregate(table, spec) {
     table ? `${table}|${byDate ? "date" : "column"}` : null,
     key,
     toDatastoreError,
+    fetchStartRef,
   );
+  useRereadOnWrite(table, result.refetch, fetchStartRef, Boolean(spec && spec.live === true));
 
   const { data, ...state } = result;
   const rows = data || [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.268.1",
+  "version": "0.270.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",

package/src/contract.js

@@ -1351,7 +1351,8 @@ const HOOKS = [
       "keeps it in `data` with loading false while `fetching` is true; a " +
       "different table or record id resets to loading. " +
       "`{ includeCapabilities: true }` adds `_capabilities` to the row, as " +
-      "for useDatastoreQuery.",
+      "for useDatastoreQuery. `{ live: true }` re-reads it when anyone else " +
+      "changes the table.",
     returnShape: {
       data: "Record | null",
       loading: "boolean",
@@ -1935,7 +1936,15 @@ const HOOKS = [
       "enforce, computed for the whole page in one lookup. Gate a row's " +
       "Edit on `row._capabilities?.can_write` and Delete on `can_delete`. " +
       "`total` is how many rows the query matches in all (the envelope's " +
-      "meta.total), not just the page in `data`; null until known.",
+      "meta.total), not just the page in `data`; null until known. A " +
+      "successful useDatastoreMutation write to the table, from this widget " +
+      "or any other on the screen, re-reads it on its own: never refetch or " +
+      "subscribe for your own writes. Add `live: true` to the options to also " +
+      "re-read when anyone else changes the table (a pushed change, paced like " +
+      "a write; the re-read is the same permission-checked read, and keeps the " +
+      "rows on screen with loading false). Use it for lists other people " +
+      "change: queues, bookings, chat, dashboards. Never poll with setInterval " +
+      "or wire useDatastoreSubscription for that.",
     returnShape: {
       data: "Record[]",
       total: "number | null",
@@ -1949,8 +1958,8 @@ const HOOKS = [
   },
   {
     name: "useDatastoreFigure",
-    signature: "useDatastoreFigure(tableId, { aggregate, column, filter })",
-    optionalArgs: ["aggregate", "column", "filter"],
+    signature: "useDatastoreFigure(tableId, { aggregate, column, filter, live })",
+    optionalArgs: ["aggregate", "column", "filter", "live"],
     description:
       "ONE live figure over a table, for a `<Stat>`: `aggregate` is " +
       "\"count\" (the default; the rows, or the rows `filter` matches), \"sum\" " +
@@ -1965,7 +1974,8 @@ const HOOKS = [
       "or average reads up to 1000 rows, skips blank cells rather than counting " +
       "them as zero, and past that reads \"≈ n\" (`truncated: true`). The stock " +
       "Stat widget computes its figure through this hook, so use it rather than " +
-      "reducing useDatastoreQuery rows by hand. Call it once per figure.",
+      "reducing useDatastoreQuery rows by hand. Call it once per figure. " +
+      "`live: true` re-reads it when anyone else changes the table.",
     returnShape: {
       value: "number | null",
       text: "string | null  // the formatted figure for <Stat value>",
@@ -1983,8 +1993,8 @@ const HOOKS = [
   {
     name: "useDatastoreAggregate",
     signature:
-      "useDatastoreAggregate(tableId, { groupBy, bucket, from, to, sumColumn, filter, order, limit })",
-    optionalArgs: ["groupBy", "bucket", "from", "to", "sumColumn", "filter", "order", "limit"],
+      "useDatastoreAggregate(tableId, { groupBy, bucket, from, to, sumColumn, filter, order, limit, live })",
+    optionalArgs: ["groupBy", "bucket", "from", "to", "sumColumn", "filter", "order", "limit", "live"],
     description:
       "Counts rows on the server over EVERY row the viewer can read, so it is " +
       "exact past the 1000-row page a list read returns — never group " +
@@ -2003,7 +2013,8 @@ const HOOKS = [
       "them out with a `nempty:` filter. Encrypted, array, file and relation " +
       "columns cannot be grouped (VALIDATION). `filter` takes the same shapes " +
       "as useDatastoreQuery's, created_at ranges included. Pass null as the " +
-      "table until a bound table is known.",
+      "table until a bound table is known. `live: true` re-reads it when " +
+      "anyone else changes the table.",
     returnShape: {
       buckets:
         "Array<{ date, count, sum }>  // date = the bucket's start, YYYY-MM-DD; sum is 0 without sumColumn",
@@ -2209,6 +2220,15 @@ const HOOKS = [
   {
     name: "useDatastoreMutation",
     signature: "useDatastoreMutation(tableId)",
+    description:
+      "Creates, updates (partial) and deletes rows. A successful write re-reads " +
+      "every useDatastoreQuery, useDatastoreRecord, useDatastoreFigure and " +
+      "useDatastoreAggregate on the same table reference, in every widget on " +
+      "the screen, so no widget calls refetch() or subscribes for it. Readers " +
+      "must name the table the same way (its id, as a tableRef property binds it). " +
+      "A run of writes re-reads each reader at most once a second, always once " +
+      "more after the last. Never write from a useEffect that re-runs on the data " +
+      "it reads unless a ref or Set marks each row as already written: it loops.",
     returnShape: {
       create:
         "(record) => Promise<Record>  // rejects with DatastoreError { code, message, retryable } — render the message when retryable is false, never 'try again'",
@@ -2859,6 +2879,9 @@ const HOOKS = [
     signature: "useDatastoreSubscription(tableId, handlers, options)",
     optionalArgs: ["options"],
     description:
+      "To keep a list, record, figure or aggregate current, pass `live: true` " +
+      "to its read hook instead; this hook is for acting on each change " +
+      "(a toast, a sound, merging rows yourself). " +
       "Subscribe to a table's realtime change stream via the injected " +
       "datastore-client at ctx.datastore.records(tableId).subscribe(...). " +
       "handlers is { onCreated?, onUpdated?, onDeleted? }; each receives the " +
@@ -6478,7 +6501,11 @@ const CONTRACT = deepFreeze({
   // 1.218.0: additive (sc-14224) — the actions client's `status(actionId)`;
   //    `useAction().available` turns false when the server says a run would
   //    not reach the script.
-  version: "1.218.0",
+  // 1.219.0: behaviour (sc-14407) — a useDatastoreMutation write re-reads
+  //    every query, record, figure and aggregate on that table, app-wide.
+  // 1.220.0: additive (sc-14423) — `live: true` on useDatastoreQuery,
+  //    useDatastoreRecord, useDatastoreFigure and useDatastoreAggregate.
+  version: "1.220.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,