Download web/src/customer-grid/apiBridge.ts from fsanyoto/loopable: direct link, hf CLI and curl.
- Browser
- Download file 165 kB
-
https://huggingface.co/spaces/fsanyoto/loopable/resolve/9291c0100f4e7b8da2efcbbf1ebdea72ee1663e7/web/src/customer-grid/apiBridge.ts
- Command line
-
hf download hf://spaces/fsanyoto/loopable@9291c0100f4e7b8da2efcbbf1ebdea72ee1663e7/web/src/customer-grid/apiBridge.ts
-
curl -L -o apiBridge.ts https://huggingface.co/spaces/fsanyoto/loopable/resolve/9291c0100f4e7b8da2efcbbf1ebdea72ee1663e7/web/src/customer-grid/apiBridge.ts
165 kB
// ---------------------------------------------------------------------------
// customer-grid / apiBridge.ts β the STANDALONE half of the data path (X2).
//
// The branch beside hostBridge.ts. Where `hostBridge` speaks the Streamlit
// Components v1 protocol to a surrounding Python app, this speaks HTTP to the
// API β the SAME event objects, the same ids, the same optimism semantics on
// the client. Which one is live is decided once, by mode, and never mixed:
// `installStandaloneBridge()` is called from main.tsx ONLY in standalone, so
// the embed bundle never registers a sink and its behaviour is byte-unchanged
// (pinned by verify_bridge.py, which was written BEFORE this file existed).
//
// β WHAT THIS WAVE'S WRITE PATH CAN AND CANNOT DO β read before extending.
// The client's whole write model is "emit β the host reruns β a fresh payload
// arrives β the UI reflects it" (CustomerGrid's own words: *"the emit itself
// triggers the host rerun, so the fresh name/list arrives with the next payload
// β no local mutation to drift from the store"*). Standalone has no rerun and
// X2 fixes `GET /api/v1/customers` at the EXACT current shape β `{fields, rows,
// today, pulled_at}`, with no `workspace`, no `cohorts`, no `docs`. So:
//
// VISIBLE + DURABLE view_upsert Β· view_delete Β· field_* Β· overlay_patch
// (the client already holds these in state + localStorage;
// the POST is what makes them durable server-side)
// DURABLE, INVISIBLE cohort_* Β· add_to_list Β· folder_* Β· item_move
// (they reach the store, but nothing re-reads them until
// the payload carries that state β EXIT-5). The server's
// `toast` is the only feedback the user gets, which is
// why it is wired through and not dropped.
// NOT REACHABLE doc_add / doc_fetch / doc_delete β the Documents panel
// is driven by `payload.docs`, which standalone never
// receives, so no doc event can be emitted at all. X2's
// `doc` field is therefore deliberately NOT handled here:
// wiring a response nobody can trigger is untestable dead
// code. When `/customers` grows `docs`, feed `doc` into
// the same `payload.docPayload` slot the embed uses.
//
// NOTHING HERE FALLS BACK TO `sample_customers.json`. That affordance ("the
// grid still renders with no backend") is unreachable now β the frame requires
// a session before CustomerGrid mounts at all β and behind a login, sample
// revenue rendered after a server hiccup is fabricated data on a screen the
// user has every reason to trust. An honest failure, always.
// ---------------------------------------------------------------------------
import {
API_V1,
CREDENTIALS,
DATA_ERROR_EVENT,
ROWS_STALE_EVENT,
TOAST_EVENT,
WORKSPACE_STALE_EVENT,
UNAUTHORIZED_EVENT,
checkTenant,
currentTenant,
PRINCIPAL_HEADER,
TENANT_HEADER,
signal,
} from "../apiContract";
import { createEditOutbox, OUTBOX_CHANGED_EVENT } from "./editOutbox";
import type { OutboxEdit, OutboxFailure, OutboxIdentity, OutboxReceipt, StoredEdit } from "./editOutbox";
import { applyPendingOps } from "./viewOps";
import { ROWS_CHUNK } from "./pipelineWorker";
import type { RowsReply, RowsRequest } from "./pipelineWorker";
import { eventId, setStandaloneSink } from "./hostBridge";
import { changedBuckets } from "./liveWorkspace";
import type { ChangeTokens } from "./liveWorkspace";
import { CUSTOMER_TOPIC, relatedEntries, relatedRefusals, topicForScope } from "./types";
import type { CustomersPayload, Field, FilterNode, GridLimit, GridWorkspace, HostEvent,
RelatedEntry, RelatedPin, RelatedRefusal, Row, SortSpec, TopicConfig, ViewConfig } from "./types";
import type { TsPayload, TsRequest } from "./timeSeriesData";
import { AMAZON_STILL_LOADING_MESSAGE, MIRROR_RETRY_DELAYS, isMirrorNotLoaded,
waitForMirror } from "./mirrorLoading";
import { FIRST_ANSWER_DEADLINE_MS, READ_DEADLINE_MS, WORKSPACE_DEADLINE_MS, armDeadline, fetchWithDeadline,
isReadTimeout } from "../net/deadline";
const JSON_HEADERS = { "Content-Type": "application/json" };
/** R8 layout vocabulary. Membership, row values and schema never ride this door. */
export type PersonalGridLayout = Pick<ViewConfig,
"order" | "visible" | "widths" | "sorts" | "filters" | "filterConj" | "groupBy">;
export function personalGridLayout(config: ViewConfig): PersonalGridLayout {
return {
order: config.order, visible: config.visible, widths: config.widths,
sorts: config.sorts, filters: config.filters, filterConj: config.filterConj ?? "and",
groupBy: config.groupBy,
};
}
// Only outstanding writes live here, never a user's cached prefs. Remounts await the write
// before GET; a tab switch cannot cancel it or hydrate from the server's pre-save snapshot.
const personalLayoutWrites = new Map<string, {
next: PersonalGridLayout | null;
task: Promise<boolean>;
}>();
export function savePersonalGridLayout(key: string, layout: PersonalGridLayout): Promise<boolean> {
const pending = personalLayoutWrites.get(key);
if (pending) {
pending.next = layout;
return pending.task;
}
const entry = { next: layout as PersonalGridLayout | null, task: Promise.resolve(false) };
personalLayoutWrites.set(key, entry);
entry.task = Promise.resolve().then(async () => {
let saved = true;
try {
while (entry.next) {
const next = entry.next;
entry.next = null;
try {
const res = await fetch(`${API_V1}/nav/prefs`, {
method: "POST", credentials: CREDENTIALS, headers: JSON_HEADERS,
body: JSON.stringify({ linkedLayouts: { [key]: next } }),
keepalive: true,
});
if (handledSession(res)) { entry.next = null; return false; }
if (!res.ok) {
const body = await readJson(res);
if ((body as { error?: { code?: string } } | null)?.error?.code === "data_input_frozen") {
entry.next = null;
signal(TOAST_EVENT, refusalMessage(body, res.status));
return false;
}
throw new Error("layout write refused");
}
} catch {
saved = false;
signal(TOAST_EVENT, "Your grid layout could not be saved. Change a view control to retry.");
}
}
return saved;
} finally {
personalLayoutWrites.delete(key);
}
});
return entry.task;
}
export async function fetchPersonalGridLayout(key: string): Promise<{
ok: boolean; layout: Partial<PersonalGridLayout> | null;
}> {
await personalLayoutWrites.get(key)?.task;
try {
const res = await fetch(`${API_V1}/nav/prefs`, { credentials: CREDENTIALS, cache: "no-store" });
if (handledSession(res)) return { ok: false, layout: null };
if (!res.ok) throw new Error("layout read refused");
const json = await readJson(res) as { prefs?: { linkedLayouts?: Record<string, PersonalGridLayout> } } | null;
if (!json?.prefs) throw new Error("invalid preferences");
const layout = json.prefs.linkedLayouts?.[key];
return { ok: true, layout: layout && typeof layout === "object" ? layout : null };
} catch {
signal(TOAST_EVENT, "Your saved grid layout could not be loaded. Reopen this tab to retry.");
return { ok: false, layout: null };
}
}
async function readJson(res: Response): Promise<unknown> {
try {
return await res.json();
} catch {
return null;
}
}
/** 401 is the one status that is never a data problem. Raised once, centrally,
* so every call site cannot forget to. Returns true when it handled it.
* The rows caches die with the session β the next signed-in user may not
* be the same person, and a cached book must never cross that boundary. */
function handledUnauthorized(status: number): boolean {
if (status !== 401) return false;
clearCustomersCache();
signal(UNAUTHORIZED_EVENT);
return true;
}
/**
* The session check every authenticated call makes: the 401 above, PLUS the TENANT swap the
* 401 path structurally cannot see.
*
* β WHY `handledUnauthorized` WAS NEVER ENOUGH. Its own note says the rows cache "dies with the
* session β the next signed-in user may not be the same person". That is the USER boundary, and
* it is enforced on 401. A TENANT swap produces no 401 at all: `aios_session` is one cookie per
* ORIGIN, so signing into another tenant in a second tab repoints this one, and every request
* here keeps returning a cheerful 200 full of somebody else's data. `checkTenant` reads the
* server's own stamp and reloads the frame; see `apiContract.ts::TENANT_HEADER`.
*/
/**
* β W62-T18 β WIDENED FROM `Response` TO WHAT IT ACTUALLY READS, and no further. A `Response`
* still satisfies it, so every existing call site is unchanged; what it now also accepts is the
* `{status, headers}` shim `rowsThroughWorker` builds from the worker's reply, because a worker
* that did the fetch holds no `Response` for the main thread to hand over. `checkTenant` was
* already written to this structural type (`apiContract.ts:99`) β this brings its caller into
* line rather than inventing a second session check for the worker path, which is the one way
* a tenant swap could have been missed on the read that matters most.
*/
interface SessionFacts {
status: number;
headers: { get(name: string): string | null };
}
function handledSession(res: SessionFacts): boolean {
if (checkTenant(res)) { clearCustomersCache(); return true; }
return handledUnauthorized(res.status);
}
// --- the READ (CP-B) -------------------------------------------------------
/**
* The last good `/customers` payload, reused across surface switches. The rows
* are a 15-minute-cached Odoo pull SERVER-side, but every CustomerβCohort
* route change remounts the grid and re-downloaded the whole ~1 MB payload β
* three full transfers in one short session, measured live. Within this window
* a remount reuses the copy; the workspace (the cheap per-scope call) is always
* re-fetched, so views/cohorts stay live.
*
* β THE CACHE IS SESSION-SCOPED OR IT IS A LEAK. It is cleared on ANY 401 and
* on sign-out/sign-in (Shell calls `clearCustomersCache`) β one browser, two
* accounts, and a cached book served across the boundary would be the exact
* cross-user leak EXIT-3b exists to prevent, client-side this time.
*
* Own edits stay visible ([[the NO-BLIP law]]): `patchCustomer` writes accepted
* values through into the cached rows, so a scope switch after an edit shows
* the edit, not the pre-edit pull.
*/
const CUSTOMERS_FRESH_MS = 5 * 60_000;
// Wave 16 C-TOPIC: ONE cache map keyed by the topic's rows path, so the product pull and the
// customer pull each get the same 5-minute remount window without ever serving each other.
const rowsCache = new Map<string, { at: number; payload: CustomersPayload }>();
const rowWrites = new Map<string, Promise<boolean>>();
const rowVersions = new Map<string, number>();
type WindowCursor = string | number;
type WindowPayload = CustomersPayload & { next_cursor?: WindowCursor | null };
type WindowPaging = {
table: string; version: number | undefined; at: number;
next?: { offset: number; rowOffset: number; cursor: WindowCursor; seen: Set<WindowCursor>; stalled?: boolean };
};
type WindowReadBudget = { remaining: number; until: number; recoveries: number; mirrorRetries: number };
const windowPaging = new Map<string, WindowPaging>();
const WINDOW_REQUEST_BUDGET = 32;
let rowsSession = 0;
// Bumped only at an account boundary: a cache refresh must never cancel a cell write in flight.
let writeSession = 0;
/**
* ββ WAVE 31 Β· T21 (owner item 7: *"It still takes a very long time to load from one Database
* into another"*) β THE WORKSPACE ENVELOPE, MEMOISED PER SCOPE.
*
* β WHAT WAS MISSING, stated exactly: `rowsCache` above has memoised ROWS since EXIT wave 1, and
* `fetchWorkspace` had NO cache of any kind. So switching back to a database whose rows were
* still warm STILL paid a full `/workspace` round trip β and that call is not cheap: it is
* `ut_assembly`, which on tenant #0 reads a **28.6 MB** document (703 ms of deep copy, warm) plus
* the whole `grid_events` workspace build. Measured live on `283b815`: **2,430 ms** for
* `?scope=customer`. Every databaseβdatabase hop paid it, both directions, for an envelope that
* had not changed.
*
* β THE FRESHNESS WINDOW IS THE ROWS CACHE'S, ON PURPOSE. Two windows over one surface would
* drift into a grid whose columns are newer than its rows, or the reverse β a shape this repo has
* already paid for. One constant, both memos.
*
* β AND IT IS EVICTED BY THE WRITE PATH, NOT ONLY BY TIME. Every accepted grid event fires
* `WORKSPACE_STALE_EVENT` β `useCustomerData.reread()`, which calls this with no `allowCached`,
* so it re-fetches AND overwrites this entry. Without that overwrite a person could hide a
* field, switch away, switch back, and be served the pre-write envelope β the write silently
* undone on screen, which is worse than the wait it replaced.
*/
const wsCache = new Map<string, { at: number; ws: GridWorkspace; current: boolean }>();
type WorkspaceRead = { ws: GridWorkspace | null; failure?: string; forbidden?: boolean; superseded?: boolean };
/** `forbidden`: the server refused this person the table, so a retry cannot help. */
export type WorkspaceStatus = { scope: SurfaceScope; state: "ready" | "absent" | "error"; message?: string;
forbidden?: boolean };
export const WORKSPACE_ERROR_EVENT = "aios:workspace-error";
// Pending reads belong to the same memo, not a second result cache. Uncached post-write
// reads replace the joinable flight; an older completion must not remove that newer one.
const wsFlights = new Map<string, Promise<WorkspaceRead>>();
let wsCacheEpoch = 0;
let workspaceOrder = 0;
// Reads stamp request start. ACKs patch the memo before suppressing older flights.
const workspaceWrites = new Map<string, number>();
const workspaceReads = new WeakMap<GridWorkspace, number>();
/** Local read/ACK order survives workspace projections without changing the wire shape. */
export function workspaceReadOrder(workspace: GridWorkspace | undefined): number {
return workspace ? workspaceReads.get(workspace) ?? 0 : 0;
}
export function clearWorkspaceCache(): void {
wsCache.clear();
wsFlights.clear();
workspaceWrites.clear();
wsCacheEpoch += 1;
}
export function clearCustomersCache(): void {
editOutbox.sessionBoundary();
rowWrites.clear();
writeSession += 1;
refreshCustomersCache();
}
/** Drop every cached read and keep the cell writes in flight: a stale workspace is not a sign-out. */
export function refreshCustomersCache(): void {
rowsCache.clear();
windowPaging.clear();
rowVersions.clear();
rowsSession += 1;
// β THE ENVELOPE IS SESSION-SCOPED FOR THE SAME REASON THE ROWS ARE, and it carries MORE that
// is per-account than they do: `viewer`, `userOptions`, the user's own views and folders. One
// browser, two accounts, and a cached workspace served across the boundary would show the
// previous person's saved views under the new person's name.
clearWorkspaceCache();
// β AND THE READ-THROUGH ROSTER, which is a per-SESSION fact, not a per-topic one. It names
// which tables this tenant serves through the mirror; a second account signing into the same
// browser is a different tenant's answer. Same boundary the rows cache is cleared on, and for
// the same reason.
readThroughMemo = null;
connectedTablesMemo = null;
}
/**
* Drop ONE topic's rows memo. The change poller's companion (wave 29, item 20).
*
* β NOT `clearCustomersCache()`, and the difference is a megabyte. That clears every topic's
* window, so a poll that noticed a change on the Product grid would also force the Customer pool
* to be re-downloaded on the next surface switch. One bucket changed; one memo is dropped.
*
* β WAVE 30 β it now sweeps a PREFIX, because one table can have many cache entries. A windowed
* grid's key carries its offset and its predicate (see `windowRowsPath`), so `ut_odoo_orders`
* may hold a dozen. Deleting the bare path would leave every one of them live.
*/
export function clearTopicRowsCache(rowsPath: string): void {
const table = rowsPath === "customers" ? "customer_data" : rowsPath === "products" ? "product_data"
: /^(?:odoo-tables|tables)\/([^/]+)\/rows$/.exec(rowsPath)?.[1];
if (table) invalidateWindowPaging(decodeURIComponent(table));
rowsCache.delete(rowsPath);
for (const key of [...rowsCache.keys()])
if (key.startsWith(`${rowsPath}?`)) rowsCache.delete(key);
}
/**
* ββ WAVE 30 Β· W30-T42 β DROP EVERY CACHED ROWS RESPONSE FOR ONE TABLE, WHICHEVER DOOR SERVED IT.
*
* β THE DEFECT THIS PREVENTS, AND IT IS THIS REPO'S NAMED CLASS. Before C2 a table had exactly
* one rows key (`tables/<key>/rows`) and eight call sites deleted that literal. A read-through
* grid is served by a DIFFERENT route (`odoo-tables/<key>/rows`) under MANY keys (one per
* offset Γ predicate), so every one of those literals silently stopped invalidating anything β
* a write that returned 200 and a grid that kept painting the pre-write page, with no error
* anywhere. Two invalidation laws for one question is [[one-question-two-normalizers]]; there
* is one law and it lives here.
*
* β IT MATTERS DESPITE `recordsMutable: false`. A read-through Odoo grid refuses record edits,
* but W30-T28 shipped tenant-wide SHARED COLUMNS on exactly these grids β `PATCH
* /tables/{key}/shared/{pid}` writes a cell that rides the window payload's own `fields`/rows.
*/
export function dropTableRowsCache(tableKey: string): void {
tableKey = tableKey === "customer" ? "customer_data" : tableKey === "product" ? "product_data" : tableKey;
invalidateWindowPaging(tableKey);
const prefixes = [`tables/${tableKey}/rows`, `odoo-tables/${tableKey}/rows`];
for (const key of [...rowsCache.keys()])
if (prefixes.some((p) => key === p || key.startsWith(`${p}?`))) rowsCache.delete(key);
}
function invalidateWindowPaging(tableKey: string): void {
for (const [query, paging] of windowPaging)
if (paging.table === tableKey) windowPaging.delete(query);
rowVersions.set(tableKey, (rowVersions.get(tableKey) ?? 0) + 1);
}
/**
* X2 `GET /api/v1/<topic.rowsPath>` β `{fields, rows, today, pulled_at}`, rows already
* scoped to the session's BU pool (EXIT-3b). The cookie replaces HTTP Basic.
*
* Returns null on ANY failure, having raised the matching signal. A null is not
* an empty table: the frame renders a failure, not "this tenant has no
* records", because those two look identical and only one of them is true.
*/
/**
* β WAVE 30 (D-79's second half) β THE ONE READER OF A SERVER REFUSAL, and the reason it exists.
*
* β MEASURED: five call sites in this file read `body.detail.message`, and **the server has never
* sent that shape.** `main.py`'s `_error_shape` handler unwraps `deps.err`'s `detail` before the
* response leaves, so every non-2xx body on the wire is `{"error": {"code", "message"}}` β the
* X2 contract, stated in that handler's own docstring. `body.detail` is `undefined` at all five,
* so every carefully-worded refusal in the API ("this database already has a profile column β
* 'Handle'. A database has at most oneβ¦") was replaced by "The server answered 400."
*
* That is worse than a missing feature: the product LOOKED like it was explaining itself. Sixteen
* other call sites across the client already read `error.message` correctly, which is why nobody
* noticed β the wrong shape survived only where nobody had recently read a refusal out loud.
*
* β THE `detail` LEG STAYS, AS A STRING. FastAPI's own `RequestValidationError` does NOT pass
* through `_error_shape`, so a 422 from a malformed body still arrives shaped `{"detail": β¦}`.
* Reading it as a string is honest; reading `.message` off it never was.
*/
export function refusalMessage(body: unknown, status: number, fallback?: string): string {
const shaped = body as { error?: { message?: unknown }; message?: unknown;
refused?: { message?: unknown }; detail?: unknown } | null | undefined;
const named = shaped?.error?.message;
if (typeof named === "string" && named.trim()) return named;
const detail = shaped?.detail as { message?: unknown; error?: { message?: unknown } } | null;
const supplied = shaped?.refused?.message ?? detail?.message ?? detail?.error?.message ?? shaped?.message;
if (typeof supplied === "string" && supplied.trim()) return supplied;
if (typeof shaped?.detail === "string" && shaped.detail.trim()) return shaped.detail;
return fallback ?? `The server answered ${status}.`;
}
/**
* ββ W62-T18 / R51 β THE ROWS READ, OFF THE MAIN THREAD, IN BOUNDED PIECES.
*
* β THE MEASUREMENT IS THE WHOLE ARGUMENT, and it is committed beside this code in
* `AutoWiki/waves/wave62/proto/T18-measure.md`. On staging's `sale.order.line.agent` database
* (137,327 rows, 13 columns) the rows body is **69,944,226 bytes** (5.69 MB gzipped on the wire).
* `await res.json()` over it cost **731 ms** unthrottled and **2,916 ms** at 4x CPU throttling,
* and produced the only main-thread tasks over 200 ms in the whole open: 355 ms unthrottled,
* **1,523 ms and 1,384 ms** throttled. A CPU profile of the same open attributes 870.6 ms of self
* time to V8's `(program)` (the native parse) and 168.6 ms to the collector, against **22.6 ms
* for the largest application frame in the profile**. The freeze is this one line, not the grid.
*
* β AND IT IS NOT THE PIPELINE, WHICH IS WHERE THE TICKET POINTED FIRST. `runPipeline` over the
* same 137,327 rows costs 20-39 ms on open and 67-101 ms on a filter change; typing five
* characters into the search box produced five tasks, none over 102 ms. Moving THAT to a worker
* would have bought nothing and cost every feature R28 protects its synchronous access to the
* rows. R51 asked for the cost to be measured before it was fixed; this is what the measurement
* changed.
*
* β CHUNKED, BECAUSE ONE MESSAGE IS ONE TASK. The worker could hand the whole payload back in a
* single `postMessage` (measured: 472 ms of main-thread wall unthrottled, 1,314 ms at 4x), or
* columnar with a rebuild on this side (measured: a 256 ms rebuild at 4x β over budget on its
* own). Ten-thousand-row slices measured 208 ms total unthrottled with NO long task recorded at
* all, and a worst task of **70 ms** at 4x. The bound is the point: each slice is deserialised in
* its own task, so the main thread stays interruptible however far the table grows.
* β 2,000-row slices measured WORSE at both speeds (293 ms / 1,131 ms, the only long tasks the
* experiment recorded on any chunked leg) β per-message overhead and the garbage it makes. Do not
* "tune" this down without re-running the experiment in that file.
*
* β NO CAP, ANYWHERE (standing rule 1). Every row the server sends is accumulated and handed to
* the caller; the chunking is a delivery schedule, not a window. There is no paging, no "See
* more" and no second virtualiser β the grid is still glide's canvas.
*
* β ONE WORKER, REUSED, AND IT MAY REFUSE TO EXIST. Any environment without `Worker` (the gates
* execute parts of this client under node) or any construction failure falls back to the old
* main-thread read, which is exactly today's behaviour. `workerDead` latches so a browser that
* cannot build workers pays the attempt once rather than once per read.
*/
let rowsWorker: Worker | null = null;
let rowsWorkerDead = false;
let rowsRequestId = 0;
function theRowsWorker(): Worker | null {
if (rowsWorkerDead) return null;
if (rowsWorker) return rowsWorker;
try {
if (typeof Worker === "undefined") { rowsWorkerDead = true; return null; }
rowsWorker = new Worker(new URL("./pipelineWorker.ts", import.meta.url), { type: "module" });
// An error that reaches here killed the worker, not one read: drop it and let the next
// caller take the main-thread path rather than wait on a worker that cannot answer.
rowsWorker.addEventListener("error", () => {
rowsWorkerDead = true;
try { rowsWorker?.terminate(); } catch { /* already gone */ }
rowsWorker = null;
});
return rowsWorker;
} catch {
rowsWorkerDead = true;
rowsWorker = null;
return null;
}
}
/** The worker's header map as something `checkTenant`/`handledSession` can read. Case-insensitive,
* like the `Headers.get` it stands in for. */
function headerReader(map: Record<string, string>): SessionFacts["headers"] {
return { get: (name: string) => map[name.toLowerCase()] ?? null };
}
/** What `rowsThroughWorker` hands back: the same three outcomes the main-thread read has, kept
* apart so the caller raises exactly what it raises today. */
type WorkerRead =
| { ok: true; payload: unknown; facts: SessionFacts }
| { ok: false; kind: "refused"; body: unknown; facts: SessionFacts }
| { ok: false; kind: "unavailable" }
| { ok: false; kind: "stalled" };
/**
* β The only bound is FIRST_ANSWER_DEADLINE_MS before the head arrives ("stalled"): a server that
* never answers ends in an error, while a body that is arriving is never cut off.
* β NO BODY TIMEOUT HERE, AND THAT IS A DECISION RATHER THAN AN OVERSIGHT. A worker that dies loudly
* raises `error` (the listener above retires it) and a fetch that fails posts `failed`, so both
* realistic failures already fall back. What is left uncovered is a worker that hangs silently -
* and the main-thread read this replaces has no timeout either, so a timer here would not close a
* gap, it would only add a way to fire DURING a healthy read: this table's own rows request
* measured 10-48 s, so any bound short enough to be useful is short enough to re-request 66.7 MB
* that was already on its way.
*/
function rowsThroughWorker(url: string): Promise<WorkerRead> {
const worker = theRowsWorker();
if (!worker) return Promise.resolve({ ok: false, kind: "unavailable" });
const id = ++rowsRequestId;
return new Promise<WorkerRead>((resolve) => {
let head: Record<string, unknown> | null = null;
let facts: SessionFacts | null = null;
/* β PRE-ALLOCATED FROM THE HEAD'S OWN `total`, and it is worth the extra field. Measured at 4x
CPU throttling on the 137,327-row table: growing this array with `push` cost 1,038 ms of
main-thread self time - the single largest application frame in the whole profiled open,
ahead of the pipeline (133 ms) and React's own commit - because a 137k-element array grows
by reallocating and copying about twenty times on the way up. Writing into a right-sized
array at a running offset pays none of that. The bound per slice is unchanged; what goes
away is the copying between slices. */
let rows: unknown[] = [];
let filled = 0;
let firstAnswer: ReturnType<typeof setTimeout> | undefined;
const finish = (result: WorkerRead): void => {
clearTimeout(firstAnswer);
worker.removeEventListener("message", onMessage);
resolve(result);
};
const onMessage = (event: MessageEvent<RowsReply>): void => {
const reply = event.data;
// β ONE WORKER SERVES EVERY READER, so a reply that is not this request's is another
// caller's rows. Ignoring it here is what makes the shared worker safe.
if (!reply || reply.id !== id) return;
if (reply.op === "head") {
clearTimeout(firstAnswer);
head = reply.head;
facts = { status: reply.status, headers: headerReader(reply.headers) };
rows = new Array(reply.total);
filled = 0;
} else if (reply.op === "slice") {
// A loop, not `push(...slice)`: spreading 10,000 arguments is a stack overflow on some
// engines, and this path exists to be dependable on a big table.
// β `filled` rather than the array's length, because the array is already at its final
// length. A server that sent more rows than its own `total` still lands them all - the
// assignment grows the array the ordinary way - so this cannot drop a row.
for (let i = 0; i < reply.slice.length; i += 1) rows[filled + i] = reply.slice[i];
filled += reply.slice.length;
} else if (reply.op === "refused") {
finish({ ok: false, kind: "refused", body: reply.body,
facts: { status: reply.status, headers: headerReader(reply.headers) } });
} else if (reply.op === "failed") {
// The fetch never happened, or the body was unreadable. Fall back rather than raise: the
// main-thread read owns those two messages and must keep owning them.
finish({ ok: false, kind: "unavailable" });
} else if (reply.op === "done") {
if (!head || !facts) finish({ ok: false, kind: "unavailable" });
// A short count means a slice was lost between the two threads. Trimming keeps the array
// honest rather than handing the grid trailing holes that read as blank records.
else finish({ ok: true, payload: { ...head, rows: filled === rows.length ? rows : rows.slice(0, filled) }, facts });
}
};
worker.addEventListener("message", onMessage);
firstAnswer = setTimeout(() => finish({ ok: false, kind: "stalled" }), FIRST_ANSWER_DEADLINE_MS);
try {
worker.postMessage({ id, url, chunk: ROWS_CHUNK } satisfies RowsRequest);
} catch {
finish({ ok: false, kind: "unavailable" });
}
});
}
/** The machine code of an X2 refusal (`{error: {code, message}}`), or "" when it names none. */
function refusalCode(body: unknown): string {
const code = (body as { error?: { code?: unknown } } | null | undefined)?.error?.code;
return typeof code === "string" ? code : "";
}
/** The code a rows failure carries when the server refused this person the table. */
export const FORBIDDEN_CODE = "forbidden";
/** The one line a table shows when the server refuses this person access to it. */
export const ACCESS_REFUSED_MESSAGE = "You do not have access to this table. Ask an Administrator.";
/** A 403, or a refusal coded `forbidden`. Decided by status and code, never by the message text. */
export function isForbiddenRefusal(status: number, body: unknown): boolean {
return status === 403 || refusalCode(body) === FORBIDDEN_CODE;
}
/** A rows refusal's code, with every 403 normalised to `FORBIDDEN_CODE`. */
function rowsRefusalCode(status: number, body: unknown): string {
return isForbiddenRefusal(status, body) ? FORBIDDEN_CODE : refusalCode(body);
}
/**
* β D-3495 (staging, 2026-09-29) β A `window_required` REFUSAL FROM THIS DOOR MEANS THE ROSTER
* WAS WRONG, so the memo is dropped right here, for every caller. The roster is memoised per
* session, and a tab that asked it before the Amazon mirror restore (about 19 minutes after
* every boot) held an answer with no `ut_amzn_*` key for as long as the tab stayed open. Every
* Amazon read-through grid then opened on THIS whole-book door and got 409 until a manual
* reload, however correct the server's registry had become. The next `readThroughTables()` asks
* the server again. `onFailure`, like `fetchTableWindow`'s, lets a caller that can recover (the
* grid reroutes to the window door) take the refusal instead of the global error signal.
*/
export async function fetchTopicRows(
topic: TopicConfig,
onFailure?: (reason: string, code: string) => void
): Promise<CustomersPayload | null> {
const fail = (reason: string, code = "") => {
if (code === "window_required") readThroughMemo = null;
if (onFailure) onFailure(reason, code);
else signal(DATA_ERROR_EVENT, reason);
};
const cached = rowsCache.get(topic.rowsPath);
if (cached && Date.now() - cached.at < CUSTOMERS_FRESH_MS) {
return cached.payload;
}
const version = rowVersions.get(topic.key);
const session = rowsSession;
// β W62-T18 β the worker leg FIRST, the main-thread read below as the fallback. Both end in
// the same three outcomes and the same cache write; what differs is only which thread pays for
// `JSON.parse`. See `rowsThroughWorker` for the measurement that put it here.
const offThread = await rowsThroughWorker(`${API_V1}/${topic.rowsPath}`);
if (!offThread.ok && offThread.kind === "stalled") {
// A server that never answered is not retried on the main thread: that would double the wait.
fail(DATABASE_TIMEOUT_MESSAGE);
return null;
}
if (offThread.ok || offThread.kind === "refused") {
if (handledSession(offThread.facts)) return null;
if (!offThread.ok) {
fail(refusalMessage(offThread.body, offThread.facts.status),
rowsRefusalCode(offThread.facts.status, offThread.body));
return null;
}
const carried = offThread.payload as CustomersPayload | null;
if (!carried || !Array.isArray(carried.rows) || !Array.isArray(carried.fields)) {
fail("The server sent an unreadable payload.");
return null;
}
if (session !== rowsSession) return null;
if (version !== rowVersions.get(topic.key)) return fetchTopicRows(topic, onFailure);
observeCanonicalRows(topic, carried);
rowsCache.set(topic.rowsPath, { at: Date.now(), payload: carried });
return carried;
}
let res: Response;
// Bounds the wait for the server's first answer only; the body below is never timed.
const controller = new AbortController();
const firstAnswer = armDeadline(controller, FIRST_ANSWER_DEADLINE_MS);
try {
res = await fetch(`${API_V1}/${topic.rowsPath}`, { credentials: CREDENTIALS, signal: controller.signal });
} catch {
fail(firstAnswer.expired() ? DATABASE_TIMEOUT_MESSAGE : "Cannot reach the server.");
return null;
} finally {
firstAnswer.disarm();
}
if (handledSession(res)) return null;
if (!res.ok) {
// β WAVE 30 β R's ask, and it is the SIXTH site of the shape T44 closed five of. This path
// answered every non-2xx with a bare status while `refusalMessage` sat 50 lines above it,
// and TWO cause-carrying refusals now arrive here: `store_not_ready` (503, live on a
// connected grid before the mirror's first sync) and the window route's own 409. Both name
// their cause and their fix; both used to render as "The server answered 503."
const refused = await readJson(res);
fail(refusalMessage(refused, res.status), rowsRefusalCode(res.status, refused));
return null;
}
const body = (await readJson(res)) as CustomersPayload | null;
if (!body || !Array.isArray(body.rows) || !Array.isArray(body.fields)) {
fail("The server sent an unreadable payload.");
return null;
}
if (session !== rowsSession) return null;
if (version !== rowVersions.get(topic.key)) return fetchTopicRows(topic, onFailure);
observeCanonicalRows(topic, body);
rowsCache.set(topic.rowsPath, { at: Date.now(), payload: body });
return body;
}
/** The customer topic's fetch β kept under its own name because half the write-path notes in
* this repo cite it; it IS `fetchTopicRows(CUSTOMER_TOPIC)`. */
export function fetchCustomers(): Promise<CustomersPayload | null> {
return fetchTopicRows(CUSTOMER_TOPIC);
}
/** C4/R9: assigned rows are selected by the server, never re-filtered from a wider client cache. */
export async function fetchAssignedCustomerRows(viewId: string): Promise<CustomersPayload | null> {
try {
const res = await fetch(`${API_V1}/customers/assigned/${encodeURIComponent(viewId)}/rows`,
{ credentials: CREDENTIALS });
if (!res.ok) {
signal(DATA_ERROR_EVENT, refusalMessage(await readJson(res), res.status));
return null;
}
const body = await readJson(res) as CustomersPayload | null;
return body && Array.isArray(body.rows) && Array.isArray(body.fields) ? body : null;
} catch {
signal(DATA_ERROR_EVENT, "Cannot reach the assigned view.");
return null;
}
}
// βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
// ββ WAVE 30 Β· W30-T42 β THE READ-THROUGH WINDOW (owner ruling R6 via R7, contract C2).
// βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
//
// THE SHAPE OF THE PROBLEM, in the owner's numbers. `tables/<key>/rows` serves a table by
// copying it out of the tenant's `user_tables` document, which is why `MAX_ROWS = 60_000`
// exists and why order lines (255,286) and GL lines (963,783) could never be grids at all.
// W30-T26 built the other door: `odoo-tables/<key>/rows` reads the DuckDB mirror and answers
// `{rows, total, totalUnfiltered, offset, limit, limits}` β the requested slice plus a
// `SELECT count(*)` that tells the truth about the whole.
//
// β THE CLIENT MACHINERY FOR THIS ALREADY EXISTED AND WAS DORMANT β `TableMode`,
// `ScopeCounts`, `countLabel`'s "showing 200 of 201,558", `useVisibleRows`' pass-through and
// every `serverWindowed` guard in `CustomerGrid`. What did not exist was anything that ever
// SET `counts.windowed`: a mode reachable only by a payload no fetch path had ever built. So
// what is added below is a fetch and a mapping, not an engine.
//
// β `counts.matched` IS THE SERVER'S `total`, NEVER `rows.length`. That is the fabricated
// aggregate this repo has paid for twice ([[no-unverifiable-aggregates]]) and it is the ONE
// number the whole contract exists to protect: a 200-row response describing 32,826 orders.
/** One window's worth of rows. 200 is what D measured the route at (79 ms warm on 32,700
* orders, against 474 ms for the whole read); the server clamps anything over
* `datastore.WINDOW_MAX` (5,000) and REPORTS the clamp rather than trimming quietly. */
// HOTFIX 2026-09-23 (owner): "pagination or next page and only load 50 at a time". The grid
// pages a read-through table 50 rows at a time with Prev / Next; `total` stays the server's.
export const WINDOW_ROWS = 100;
/** HOTFIX 2026-09-24 (owner): "a pagination option, 50/100/200 at a time, while 100 record at a
* time is the default." One vocabulary for every database, remembered per browser. */
export const PAGE_SIZES = [50, 100, 200] as const;
const PAGE_SIZE_KEY = "cg.pageSize";
export function readPageSize(): number {
try {
const n = Number(localStorage.getItem(PAGE_SIZE_KEY));
return (PAGE_SIZES as readonly number[]).includes(n) ? n : WINDOW_ROWS;
} catch {
return WINDOW_ROWS;
}
}
export function writePageSize(n: number): void {
try {
localStorage.setItem(PAGE_SIZE_KEY, String(n));
} catch {
/* a blocked store only loses the preference, never the page */
}
}
export interface RowWindowRequest {
offset: number;
limit: number;
/** A server continuation takes precedence over a jump offset. */
cursor?: WindowCursor | null;
/** Cell/link record IDs, intersected on the server before counting and paging. */
ids?: readonly number[];
/** The saved view's OWN objects. β Not translated β see `windowRowsPath`. */
filters?: FilterNode[] | null;
filterConj?: string;
sorts?: SortSpec | null;
search?: string;
/**
* ββ W51-T06 / C6 β THE PINNED READ. `{table, record, via}`: narrow this window to the rows
* related to ONE record of another database, ahead of `filters`.
*
* β IT IS PART OF THE PATH, therefore part of the CACHE KEY, and that is not a nicety.
* `rowsCache` is keyed by path (see `windowRowsPath`), so a pin that stayed out of the string
* would make a pinned read a cache HIT on the unpinned one this browser already holds β the
* whole table painted under a tab that names one record, served from memory, with no request
* to see in the network panel.
*/
related?: RelatedPin | null;
/** HOTFIX 2026-09-23 β page ONE group of `/aggregates`' grouping. `key` is the group key
* exactly as `/aggregates` put it on the wire (`null` = the blank bucket). Part of the path,
* therefore part of the cache key. */
group?: { by: string; key: string | number | null } | null;
}
/**
* The request path for one window β AND, deliberately, its cache key.
*
* β THE TICKET'S NAMED TRAP, SOLVED BY CONSTRUCTION. `rowsCache` is keyed by path. A windowed
* path that omitted its offset would make page 2 a cache HIT on page 1 β a scroll that fetches,
* succeeds, and paints the same rows forever. Rather than remember to key the cache on
* "path + offset + predicate" at each call site, ONE function builds the string and the caller
* uses it for both. They cannot disagree because they are the same value.
*
* β THE PREDICATE RIDES AS THE CLIENT'S OWN VOCABULARY. `filters` is `ViewConfig.filters`
* (a `FilterNode[]`), `filterConj` is `ViewConfig.filterConj`, `sorts` is `ViewConfig.sorts` β
* JSON, verbatim, no translation layer. D built `compile_filter_tree` to take exactly these
* objects, and an unparseable `filters` is answered with a 400 rather than "no filter",
* because a condition that is quietly dropped WIDENS and a wider answer looks plausible.
*
* β Empty parts are OMITTED, not sent blank: a view with no filter must produce the identical
* path the first (predicate-free) window used, or the very first scroll misses the cache.
*/
export function usesPinnedRows(tableKey: string, related: RelatedPin | null | undefined): boolean {
return Boolean(tableKey && related);
}
export function windowRowsPath(tableKey: string, req: RowWindowRequest): string {
tableKey = tableKey === "customer" ? "customer_data" : tableKey === "product" ? "product_data" : tableKey;
const q = new URLSearchParams();
if (req.cursor != null) q.set("cursor", String(req.cursor));
else q.set("offset", String(Math.max(0, Math.floor(req.offset || 0))));
q.set("limit", String(Math.max(1, Math.floor(req.limit || WINDOW_ROWS))));
if (req.filters && req.filters.length) {
q.set("filters", JSON.stringify(req.filters));
if (req.filterConj === "or") q.set("filterConj", "or");
}
if (req.sorts && req.sorts.length) q.set("sorts", JSON.stringify(req.sorts));
const search = (req.search ?? "").trim();
if (search) q.set("search", search);
/* ββ W51-T06 / C6 β THE PIN RIDES AS A JSON QUERY STRING, copying the `filters` precedent one
argument over, because `GET /odoo-tables/{key}/rows` is a GET and its `related` argument is
`Query(default=None)` (`routes_odoo_tables.py::odoo_table_rows`). β THE AGGREGATES DOOR IS
A POST AND TAKES THE SAME OBJECT AS A BODY KEY β see `fetchAggregates`. Two transports, one
payload; assuming both were bodies is the half-wired contract that paints the right rows
under a summary computed over the whole table. */
if (req.related) q.set("related", JSON.stringify(req.related));
if (req.group && req.group.by) {
q.set("groupBy", req.group.by);
q.set("groupKey", JSON.stringify(req.group.key ?? null));
}
/* S66-T48: a cell's record set rides in the POST BODY (`windowRowsInit`), because a drill of
thousands of ids overflows a URL. The path carries only its count and digest, so the path is
still the one cache key: two sets never share an entry, one set in any order shares one. */
if (req.ids !== undefined) q.set("ids", `${new Set(req.ids).size}.${idSetDigest(req.ids)}`);
return `odoo-tables/${encodeURIComponent(tableKey)}/rows?${q.toString()}`;
}
/** Stable set identity for component dependencies and the path's id digest. */
export function recordIdsKey(ids: readonly number[] | undefined): string {
return ids === undefined ? "" : JSON.stringify([...new Set(ids)].sort((a, b) => a - b));
}
/** A 53-bit digest of the sorted id set: the path names WHICH records without carrying them.
* Synchronous on purpose, so `windowRowsPath` stays one pure string builder. */
function idSetDigest(ids: readonly number[]): string {
const key = recordIdsKey(ids);
let h1 = 0xdeadbeef, h2 = 0x41c6ce57;
for (let i = 0; i < key.length; i++) {
const ch = key.charCodeAt(i);
h1 = Math.imul(h1 ^ ch, 2654435761);
h2 = Math.imul(h2 ^ ch, 1597334677);
}
h1 = Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^ Math.imul(h2 ^ (h2 >>> 13), 3266489909);
h2 = Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^ Math.imul(h1 ^ (h1 >>> 13), 3266489909);
return (4294967296 * (2097151 & h2) + (h1 >>> 0)).toString(36);
}
/** How the window at `windowRowsPath` is fetched: a GET, or with a record set a POST whose body
* is that set and nothing else (every other part of the question stays in the path). */
export function windowRowsInit(req: RowWindowRequest): RequestInit {
if (req.ids === undefined) return { credentials: CREDENTIALS };
return {
method: "POST", credentials: CREDENTIALS, headers: JSON_HEADERS,
body: JSON.stringify({ ids: JSON.parse(recordIdsKey(req.ids)) as number[] }),
};
}
/**
* D's window envelope β the payload this client already knows how to render.
*
* β `windowed` IS TRUE FOR EVERY READ-THROUGH RESPONSE, INCLUDING ONE THAT HAPPENS TO HOLD THE
* WHOLE TABLE, and that is not sloppiness. The mode is about WHO EVALUATES THE PREDICATE, not
* about whether this particular response was truncated. A 192-row table answered in full still
* had its filter compiled to SQL β flipping to `whole-book` because nothing was cut would
* switch the TypeScript engine back on and filter the server's already-filtered rows a second
* time. `countLabel` handles the no-truncation case honestly on its own (`shown >= matched`
* renders a plain count with no "showing β¦ of"), so nothing is lost by keeping the mode stable.
*
* Returns null on a shape it cannot read β the caller raises the signal, because a payload the
* client cannot parse is a failure, never an empty table.
*/
export function windowPayload(body: unknown): WindowPayload | null {
const b = body as {
fields?: unknown; rows?: unknown; total?: unknown; totalUnfiltered?: unknown;
limits?: unknown; today?: unknown; recordsMutable?: unknown; next_cursor?: unknown;
} | null;
if (!b || !Array.isArray(b.rows) || !Array.isArray(b.fields)) return null;
if (typeof b.total !== "number" || !Number.isFinite(b.total)) return null;
const rows = b.rows as Row[];
const unfiltered =
typeof b.totalUnfiltered === "number" && Number.isFinite(b.totalUnfiltered)
? b.totalUnfiltered
: b.total;
if (b.next_cursor != null && !((typeof b.next_cursor === "string" && b.next_cursor.length > 0)
|| (typeof b.next_cursor === "number" && Number.isSafeInteger(b.next_cursor) && b.next_cursor >= 0))) return null;
const out: WindowPayload = {
fields: b.fields as Field[],
rows,
counts: {
shown: rows.length,
// β FROM THE SERVER'S COUNT STATEMENT. Never `rows.length`.
matched: b.total,
total: unfiltered,
windowed: true,
},
};
if (Array.isArray(b.limits)) out.limits = b.limits as GridLimit[];
if (typeof b.today === "string") out.today = b.today;
if (typeof b.recordsMutable === "boolean") out.recordsMutable = b.recordsMutable;
if (b.next_cursor !== undefined) out.next_cursor = b.next_cursor as WindowCursor | null;
return out;
}
/**
* Fold a freshly-fetched window into what this browser already holds.
*
* β `offset === 0` REPLACES BUT MUST NOT BLANK THE WORKSPACE. A predicate change re-requests
* from the top, and the window route serves rows β it knows nothing about saved views, folders,
* cohorts, measures, documents or the viewer, all of which `withWorkspace` merged into the live
* payload from a different call. Returning the bare response would empty the Views sidebar on
* every keystroke in the search box. So the window's keys land OVER the existing payload.
*
* β AN APPEND WHOSE OFFSET DOES NOT MEET THE LOADED COUNT IS DROPPED, NOT GUESSED. Windows are
* contiguous under a total order; a page that starts anywhere else is a response to a question
* this browser no longer holds the answer to (a predicate changed mid-flight, two scrolls
* raced). Appending it anyway would duplicate or skip rows β data the user sees, with nothing
* erroring. Dropping it costs one scroll's latency and the next event re-asks.
*/
export function mergeWindow(
prev: CustomersPayload | null,
next: CustomersPayload,
offset: number
): CustomersPayload | null {
if (offset <= 0) return { ...(prev ?? {}), ...next };
if (!prev || !prev.counts?.windowed) return prev;
if (offset !== prev.rows.length) return prev;
const rows = [...prev.rows, ...next.rows];
return {
...prev,
rows,
limits: next.limits,
// The NEWEST scope-wide numbers win (the table can move under a long scroll); only `shown`
// is ours, because only this browser knows how much of it is actually here.
counts: { ...(next.counts ?? prev.counts), shown: rows.length },
};
}
/**
* Which of this tenant's tables are served THROUGH the mirror β asked once per session.
*
* β READ FROM THE SERVER, NEVER A KEY LIST HERE. The bindings convert one bucket at a time
* (`GRID_SOURCES`), and `odoo-tables/status` reports `readThrough` per table for exactly this
* reason. A hard-coded list in the client would go stale on D's next spec row and fail in the
* dangerous direction β asking the window route for a table it cannot serve, which answers 409.
*
* β `bound_not_declared` keys are DELIBERATELY not here: they ride a separate map on that
* response because a binding whose field declaration has not landed answers 404 on the rows
* route. Reading only `tables` is what keeps a half-shipped grid out of windowed mode.
*
* β FAIL-SOFT, AND IN THE SAFE DIRECTION. Any failure yields the empty set, i.e. today's
* whole-book behaviour, and the memo is NOT poisoned β a transient 500 must not pin a session
* into the slow path for as long as the tab is open.
*/
let readThroughMemo: Promise<Set<string>> | null = null;
export function readThroughTables(): Promise<Set<string>> {
if (!readThroughMemo) {
readThroughMemo = (async () => {
try {
// The grid needs only the read-through flag, never the operator status's counts/stamps.
// `brief=1` is server-derived from the connected-grid registry and reads no table rows.
// A stalled server rejects at the deadline, so only a resolved success stays memoised.
// The session check runs before the body is parsed: a tenant swap reloads unread.
let handled = false;
const { res, body: read } = await fetchWithDeadline(`${API_V1}/odoo-tables/status?brief=1`,
{ credentials: CREDENTIALS }, (r) => (handled = handledSession(r)) ? Promise.resolve(null) : readJson(r));
if (handled || !res.ok) {
readThroughMemo = null;
return new Set<string>();
}
const body = read as
{ tables?: Record<string, { readThrough?: boolean }> } | null;
const out = new Set<string>();
for (const [key, t] of Object.entries(body?.tables ?? {}))
if (t?.readThrough === true) out.add(key);
return out;
} catch {
readThroughMemo = null;
return new Set<string>();
}
})();
}
return readThroughMemo;
}
let connectedTablesMemo: Promise<Set<string> | null> | null = null;
/** Connected tables use overlay events whether their source rows are materialized or read through. */
function connectedTables(abort: AbortSignal): Promise<Set<string> | null> {
if (!connectedTablesMemo) {
connectedTablesMemo = (async () => {
try {
const res = await fetch(`${API_V1}/tables?brief=1`, { credentials: CREDENTIALS, signal: abort });
if (handledSession(res) || !res.ok) {
connectedTablesMemo = null;
return null;
}
const body = await readJson(res) as { tables?: { key: string; connected?: boolean }[] } | null;
if (!Array.isArray(body?.tables) || body.tables.some((table) =>
table.key.startsWith("ut_") && typeof table.connected !== "boolean")) {
connectedTablesMemo = null;
return null;
}
return new Set(body.tables.filter((table) => table.connected === true).map((table) => table.key));
} catch {
connectedTablesMemo = null;
return null;
}
})();
}
return connectedTablesMemo;
}
/**
* S85-T27: the window this session already fetched for exactly this question, or null.
*
* The key is `windowRowsPath`, so scope, filter, sort, search, group page, pin and offset all
* select it, never a view id. No age limit: a cell write patches or drops it (`adoptCachedRow`),
* an outside change and a session boundary drop it, and the caller refreshes it after painting.
* `fresh` is true inside the read window `fetchTableWindow` itself would serve without a request.
*/
export function peekTableWindow(tableKey: string, req: RowWindowRequest):
{ payload: WindowPayload; fresh: boolean } | null {
const held = rowsCache.get(windowRowsPath(tableKey, req));
return held ? { payload: held.payload as WindowPayload, fresh: Date.now() - held.at < CUSTOMERS_FRESH_MS } : null;
}
/** One window, mapped. A failure returns null and reports through the caller's handler or
* the default data-error signal; null is never an empty table. `fresh` skips the memo read
* and still stores the answer: the refresh of a window painted from `peekTableWindow`. */
export async function fetchTableWindow(
tableKey: string,
req: RowWindowRequest,
onFailure?: (reason: string, code?: string) => void,
budget: WindowReadBudget = { remaining: WINDOW_REQUEST_BUDGET,
until: Date.now() + READ_DEADLINE_MS, recoveries: 0, mirrorRetries: 0 },
fresh = false
): Promise<WindowPayload | null> {
tableKey = tableKey === "customer" ? "customer_data" : tableKey === "product" ? "product_data" : tableKey;
// Optional record enrichment reports its failure inline without replacing the open drawer.
// A 403 carries `FORBIDDEN_CODE`, so the grid can paint its access line in place of an error card.
const fail: (reason: string, code?: string) => void = onFailure
?? ((reason) => signal(DATA_ERROR_EVENT, reason));
const path = windowRowsPath(tableKey, req);
const query = windowRowsPath(tableKey, { ...req, offset: 0, cursor: undefined });
const pagingKey = query;
const version = rowVersions.get(tableKey);
const session = rowsSession;
let paging = windowPaging.get(pagingKey);
if (!paging || paging.version !== version
|| Date.now() - paging.at >= CUSTOMERS_FRESH_MS) {
paging = { table: tableKey, version, at: Date.now() };
windowPaging.set(pagingKey, paging);
}
const cached = rowsCache.get(path);
if (cached && !fresh && Date.now() - cached.at < CUSTOMERS_FRESH_MS) return cached.payload as WindowPayload;
// Page numbers and record drains address the same server continuation differently.
const checkpoint = paging.next && (paging.next.offset === req.offset
|| paging.next.rowOffset === req.offset) ? paging.next : undefined;
if ((checkpoint?.stalled && req.cursor == null)
|| (paging.next?.stalled && req.cursor === paging.next.cursor)) {
fail("Cannot load the next page. Reload this database to continue.");
return null;
}
let cursor = req.cursor ?? checkpoint?.cursor;
const seen = new Set(checkpoint?.seen ?? (cursor != null ? [cursor] : []));
const isCurrent = () => session === rowsSession && version === rowVersions.get(tableKey)
&& windowPaging.get(pagingKey) === paging;
const recover = (): Promise<WindowPayload | null> => {
if (session !== rowsSession) return Promise.resolve(null);
if (budget.recoveries++ >= 1) {
fail("Database paging changed again. Reload this database to continue.");
return Promise.resolve(null);
}
if (windowPaging.get(pagingKey) === paging) windowPaging.delete(pagingKey);
rowsCache.delete(path);
return fetchTableWindow(tableKey, { ...req, cursor: undefined }, onFailure, budget);
};
let res: Response;
let body: unknown;
let payload: WindowPayload;
for (;;) {
if (session !== rowsSession) return null;
if (version !== rowVersions.get(tableKey)) return recover();
if (windowPaging.get(pagingKey) !== paging) return null;
const remainingMs = budget.until - Date.now();
if (remainingMs <= 0 || budget.remaining-- <= 0) {
fail(remainingMs <= 0 ? "Database paging timed out. Try this page again."
: "Cannot load this page yet. Try again.");
return null;
}
const wire = cursor != null ? windowRowsPath(tableKey, { ...req, cursor }) : path;
try {
// One page is bounded by the deadline, body included, so a stalled server cannot spin the grid.
// The session check runs before the body is parsed: a tenant swap reloads unread.
let handled = false;
({ res, body } = await fetchWithDeadline(`${API_V1}/${wire}`, windowRowsInit(req),
(r) => (handled = handledSession(r)) ? Promise.resolve(null) : readJson(r),
Math.min(READ_DEADLINE_MS, remainingMs)));
if (handled) return null;
} catch (error) {
if (!isCurrent()) return null;
fail(isReadTimeout(error) ? DATABASE_TIMEOUT_MESSAGE : "Cannot reach the server.");
return null;
}
if (session !== rowsSession) return null;
if (rowVersions.get(tableKey) !== version) return recover();
if (windowPaging.get(pagingKey) !== paging) return null;
if (!res.ok) {
const code = (body as { error?: { code?: string } } | null)?.error?.code;
if (cursor != null && res.status === 400 && code === "window_cursor_invalid") return recover();
if (res.status === 503 && isMirrorNotLoaded(body)) {
const delay = MIRROR_RETRY_DELAYS[budget.mirrorRetries++];
if (delay === undefined) {
fail(AMAZON_STILL_LOADING_MESSAGE);
return null;
}
// The existing cold-mirror retries add their fixed wait once, never per empty page.
budget.until += delay + READ_DEADLINE_MS;
await waitForMirror(delay);
continue;
}
fail(refusalMessage(body, res.status), isForbiddenRefusal(res.status, body) ? FORBIDDEN_CODE : undefined);
return null;
}
const page = windowPayload(body);
if (!page) {
fail("The server sent an unreadable payload.");
return null;
}
const next = page.next_cursor;
if (next != null) {
const stalled = seen.has(next) || (typeof cursor === "number" && typeof next === "number" && next <= cursor);
// Keep valid rows, but refuse an unusable continuation before the next read.
if (stalled && !page.rows.length) {
paging.next = undefined;
fail("Cannot load the next page. Reload this database to continue.");
return null;
}
seen.add(next);
paging.next = { offset: page.rows.length ? req.offset + req.limit : req.offset,
rowOffset: req.offset + page.rows.length,
cursor: next, seen: new Set(seen), stalled };
} else paging.next = undefined;
if (!page.rows.length && next != null) {
cursor = next;
continue;
}
payload = page;
paging.at = Date.now();
break;
}
if (req.related && payload.fields.some((field) => field.measure)) {
const scoped = await fetchRelatedMeasureValues(tableKey, payload.rows.map((row) => Number(row.pid)),
req.related, () => true);
if (!scoped.values) {
fail(scoped.reason);
return null;
}
const allowed = new Set(scoped.fields);
const hidden = new Set(payload.fields.filter((field) => field.measure && !allowed.has(field.key))
.map((field) => field.key));
payload.fields = payload.fields.filter((field) => !hidden.has(field.key));
payload.rows = payload.rows.map((row) => ({ ...Object.fromEntries(Object.entries(row)
.filter(([key]) => !hidden.has(key))), ...scoped.values?.[row.pid] } as Row));
if (scoped.reason) payload.limits = [...(payload.limits ?? []).filter((limit) => limit.subject !== "Linked metrics"), {
subject: "Linked metrics", cause: scoped.reason,
recommendation: "Check the metric source binding and period, then reopen this tab.",
}];
}
if (session !== rowsSession) return null;
if (rowVersions.get(tableKey) !== version) return recover();
if (!isCurrent()) return null;
observeCanonicalRows(topicForScope(tableKey === "customer_data" ? "customer" : tableKey === "product_data" ? "product" : tableKey), payload);
rowsCache.set(path, { at: Date.now(), payload });
return payload;
}
/** C10: find this exact record within the named pin, then return only its Metric values.
* No pid filter: undeclared filter keys can be dropped by the rows door. Each page uses the
* existing window path/cache, including `related`, and stops when the drawer leaves this frame.
*/
export function isRelatedProductMetricScope(tableKey: string, related: RelatedPin | null): boolean {
if (tableKey !== "product_data" || related?.table !== "customer_data") return false;
const via = related.via;
return Array.isArray(via)
? via.length === 1 && via[0] === "products_ordered"
: via.direction === "forward" && (via.field === "products_ordered" || via.key === "products_ordered");
}
/** Linked-grid metrics follow pin presence, including manual and two-hop paths. */
export function isRelatedMetricScope(tableKey: string, related: RelatedPin | null): boolean {
return usesPinnedRows(tableKey, related);
}
/** The server owns fields, catalogue admission, membership and refusals. */
export async function fetchRelatedMeasureValues(
tableKey: string, pids: number[], related: RelatedPin, isCurrent: () => boolean
): Promise<{ values: Record<number, Partial<Row>> | null; fields: string[]; reason: string }> {
const unavailable = { values: null, fields: [], reason: "Metrics for these linked records are unavailable. Try again." };
if (!isCurrent()) return unavailable;
try {
const res = await fetch(`${API_V1}/tables/${encodeURIComponent(tableKey)}/related-metrics`, {
method: "POST", credentials: CREDENTIALS, headers: JSON_HEADERS,
body: JSON.stringify({ related, pids }),
});
if (handledSession(res) || !isCurrent()) return unavailable;
const body = await readJson(res) as {
ok?: boolean; values?: Record<number, Partial<Row>>; fields?: string[];
refusals?: { field?: string; message?: string }[];
scope?: { table?: string; related?: RelatedPin; pids?: number[] };
} | null;
if (!res.ok) return { ...unavailable, reason: refusalMessage(body, res.status) };
if (!body?.ok || body.scope?.table !== tableKey
|| JSON.stringify(body.scope.related) !== JSON.stringify(related)
|| !Array.isArray(body.fields) || !Array.isArray(body.refusals)) return unavailable;
const values: Record<number, Partial<Row>> = {};
for (const pid of pids) {
const cell = body.values?.[pid];
if (!cell || !body.scope.pids?.includes(pid)
|| body.fields.some((key) => !Object.prototype.hasOwnProperty.call(cell, key))) return unavailable;
values[pid] = Object.fromEntries(body.fields.map((key) => [key,
body.refusals?.some((refusal) => !refusal.field || refusal.field === key) ? null : cell[key]]));
}
return { values, fields: body.fields,
reason: [...new Set(body.refusals.map((refusal) => refusal.message).filter(Boolean))].join(" ") };
} catch {
return unavailable;
}
}
/** Customer-scoped Metric overlays; no client amounts, field specs or Odoo ids are authority. */
export async function fetchRelatedProductMeasureValues(
pids: number[], fields: Field[], related: RelatedPin, isCurrent: () => boolean
): Promise<{ values: Record<number, Partial<Row>> | null; reason: string }> {
const unavailable = { values: null, reason: "Metrics for these related products are unavailable." };
if (!isCurrent()) return unavailable;
try {
const res = await fetch(`${API_V1}/tables/product_data/related-metrics`, {
method: "POST", credentials: CREDENTIALS, headers: JSON_HEADERS,
body: JSON.stringify({ related, pids }),
});
if (handledSession(res) || !isCurrent()) return unavailable;
const body = await readJson(res) as {
ok?: boolean; values?: Record<string, Partial<Row>>; fields?: string[];
scope?: { customer?: number; products?: Record<string, number> }; reason?: string;
} | null;
if (!res.ok) return { values: null, reason: refusalMessage(body, res.status) };
if (!isCurrent() || !body?.ok || body.scope?.customer !== related.record) return unavailable;
const keys = fields.filter((field) => field.measure).map((field) => field.key);
const values: Record<number, Partial<Row>> = {};
for (const pid of pids) {
const cell = body.values?.[pid];
if (!cell || !Number.isSafeInteger(body.scope.products?.[pid])
|| keys.some((key) => !body.fields?.includes(key)
|| !Object.prototype.hasOwnProperty.call(cell, key))) return unavailable;
values[pid] = Object.fromEntries(keys.map((key) => [key, cell[key]]));
}
return { values, reason: body.reason ?? "" };
} catch {
return unavailable;
}
}
export async function fetchRecordMeasureValues(
tableKey: string,
pid: number,
fields: Field[],
related: RelatedPin,
isCurrent: () => boolean
): Promise<{ values: Partial<Row> | null; reason: string }> {
if (isRelatedProductMetricScope(tableKey, related)) {
const result = await fetchRelatedProductMeasureValues([pid], fields, related, isCurrent);
return { values: result.values?.[pid] ?? null, reason: result.reason };
}
const measureKeys = fields.filter((field) => field.measure).map((field) => field.key);
let offset = 0;
let cursor: WindowCursor | undefined;
const seen = new Set<WindowCursor>();
while (isCurrent()) {
let reason = "Metric values are unscoped because the related record read failed.";
const payload = await fetchTableWindow(tableKey, { offset, limit: WINDOW_ROWS, related, cursor },
(failure) => { reason = `Metric values are unscoped because the related record read failed: ${failure}`; });
if (!payload || !isCurrent()) return { values: null, reason };
// A successful HTTP response can still report a refused or incomplete calculation.
const limit = payload.limits?.find((item) => item.effect !== "none");
if (limit) return {
values: null,
reason: `Metric values are unscoped because the related read is limited: ${limit.cause}`,
};
const row = payload.rows.find((candidate) => Number(candidate.pid) === pid);
if (row) {
if (measureKeys.some((key) => !Object.prototype.hasOwnProperty.call(row, key))) {
return { values: null,
reason: "Metric values are unscoped because the related read did not return every metric field." };
}
const values: Partial<Row> = {};
for (const key of measureKeys) values[key] = row[key];
return { values, reason: "" };
}
if (payload.next_cursor != null) {
if (seen.has(payload.next_cursor)) return { values: null,
reason: "Cannot load related metric values. Reopen this record to try again." };
seen.add(payload.next_cursor);
cursor = payload.next_cursor;
offset += WINDOW_ROWS;
} else {
cursor = undefined;
offset += payload.rows.length;
if (!payload.rows.length || offset >= (payload.counts?.matched ?? offset)) break;
}
}
return { values: null,
reason: "Metric values are unscoped because this record was not found within the related records." };
}
// βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
// ββ WAVE 50 Β· W50-T03 β CONTRACT C1: THE WINDOWED AGGREGATE (owner ruling R1, second half).
// βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
//
// R1, verbatim: *"on a server-windowed table the summary bar and group aggregates are computed
// SERVER-SIDE over the whole predicate (fixes D-159)."*
//
// β THE ROUTE IS LANE F'S (W50-T31) AND IT DOES NOT EXIST IN THIS TREE. That is stated rather
// than worked around: this half of the contract is the CONSUMER, written to C1's shape, and its
// only correct behaviour while the producer is absent is to say so honestly and let the caller
// fall back to the loaded window with a sentence that names the window. Hand-faking the numbers
// would put a fabricated aggregate on screen β the exact thing R1 exists to end
// ([[no-unverifiable-aggregates]]) β and stalling would ship nothing at all.
//
// β A REFUSAL IS NOT AN ERROR TOAST HERE. `fetchTableWindow` above raises `DATA_ERROR_EVENT`
// because a window it cannot fetch means an empty grid. A summary it cannot fetch means a
// summary over the loaded window, which is a WORSE answer and not a broken screen β so this
// returns `null` quietly and the bar discloses its own scope. A toast on every paint of every
// Odoo grid until lane F lands would train the owner to dismiss the one that matters.
/** C1's request. `groupBy` is a colId; omit it for the table-wide answer. */
export interface AggregateRequest {
ids?: readonly number[];
filters?: FilterNode[] | null;
filterConj?: string;
search?: string;
groupBy?: string;
aggs: { colId: string; agg: string; p?: number }[];
/**
* ββ W51-T06 / C6 β THE SAME PIN THE WINDOW CARRIES, or the summaries describe a different
* population than the rows under them.
*
* ββ THIS IS THE HALF-WIRING TRAP, NAMED. Wire only `/rows` and the grid shows one record's
* related rows under a count and a summary bar folded over the WHOLE table: a plausible
* number, which is exactly the fabricated aggregate `no-unverifiable-aggregates` exists to
* forbid. `_compiled_read` is shared between the two doors server-side, so the ONLY way they
* can pin differently is this argument being dropped on one of them.
*/
related?: RelatedPin | null;
}
/** C1's response, as this client reads it. `null` for a column means the server ANSWERED and
* the value is blank β never a silent 0, which is what the contract's `limits` is for. */
export interface AggregateResult {
totalRows: number;
aggregates: Record<string, number | null>;
groups?: { key: string; label: string; count: number;
aggregates: Record<string, number | null> }[];
limits: GridLimit[];
}
/** Read C1's envelope, or null if it is not C1's envelope. Kept separate from the fetch so the
* gate and the node harness can drive the parse without a server. */
export function aggregatePayload(body: unknown): AggregateResult | null {
const b = body as {
ok?: unknown; total_rows?: unknown; aggregates?: unknown; groups?: unknown; limits?: unknown;
} | null;
if (!b || b.ok === false) return null;
if (!b.aggregates || typeof b.aggregates !== "object") return null;
const values: Record<string, number | null> = {};
for (const [colId, v] of Object.entries(b.aggregates as Record<string, unknown>))
values[colId] = typeof v === "number" && Number.isFinite(v) ? v : null;
const out: AggregateResult = {
totalRows: typeof b.total_rows === "number" ? b.total_rows : 0,
aggregates: values,
limits: Array.isArray(b.limits) ? (b.limits as GridLimit[]) : [],
};
if (Array.isArray(b.groups)) {
out.groups = (b.groups as Record<string, unknown>[]).map((g) => ({
key: String(g.key ?? ""),
label: String(g.label ?? ""),
count: typeof g.count === "number" ? g.count : 0,
aggregates: (g.aggregates ?? {}) as Record<string, number | null>,
}));
}
return out;
}
/** Refuse broken pagination metadata before another aggregate page is requested. */
export function aggregatePageProgress(body: unknown, offset: number, size: number | undefined,
expected?: number): { total?: number; done: boolean } | null {
if (!body || typeof body !== "object" || size === undefined) return null;
const meta = body as { total_groups?: number; group_offset?: number; group_limit?: number;
has_more?: boolean };
if (meta.total_groups === undefined) {
return offset === 0 && expected === undefined
&& (meta.has_more === undefined || meta.has_more === false)
&& (meta.group_offset === undefined || meta.group_offset === 0)
? { done: true } : null;
}
const total = meta.total_groups;
if (!Number.isSafeInteger(total) || total < 0 || meta.group_offset !== offset
|| !Number.isSafeInteger(meta.group_limit) || (meta.group_limit ?? 0) <= 0
|| size > meta.group_limit!
|| (expected !== undefined && expected !== total)) return null;
const next = offset + size;
if (next > total || (size === 0 && next < total)
|| (meta.has_more !== undefined && meta.has_more !== (next < total))) return null;
return { total, done: next === total };
}
/**
* `POST /api/v1/odoo-tables/<key>/aggregates` β C1, over the WHOLE predicate.
*
* β DEGRADES TO `null`, NEVER TO A NUMBER. A 404 (lane F's route not merged), a 405, a 500 or
* an unreachable server all land in the same place: the caller has no server answer and must
* say what it is showing instead.
*/
export async function fetchAggregates(
tableKey: string,
req: AggregateRequest
): Promise<AggregateResult | null> {
if (!req.aggs.length && !req.groupBy) return null;
let offset = 0;
let answer: AggregateResult | null = null;
let expectedGroups: number | undefined;
do {
let res: Response;
try {
res = await fetch(
`${API_V1}/odoo-tables/${encodeURIComponent(tableKey)}/aggregates`,
{
method: "POST",
credentials: CREDENTIALS,
headers: JSON_HEADERS,
body: JSON.stringify({
...(req.ids !== undefined ? { ids: req.ids } : {}),
filters: req.filters ?? [],
filterConj: req.filterConj === "or" ? "or" : "and",
search: (req.search ?? "").trim(),
...(req.groupBy ? { groupBy: req.groupBy } : {}),
...(req.groupBy ? { groupOffset: offset, groupLimit: 1000 } : {}),
/* β A BODY KEY HERE, A QUERY STRING ON `/rows` (`windowRowsPath`). Same object, two
transports, because this door is a POST and that one is a GET. */
...(req.related ? { related: req.related } : {}),
aggs: req.aggs,
}),
}
);
} catch {
return null;
}
if (handledSession(res) || !res.ok) return null;
const body = await readJson(res);
const page = aggregatePayload(body);
if (!page) return null;
if (!req.groupBy) return page;
const progress = aggregatePageProgress(body, offset, page.groups?.length, expectedGroups);
if (!progress) return null;
expectedGroups = progress.total;
if (!answer) answer = page;
else {
if (answer.totalRows !== page.totalRows
|| JSON.stringify(answer.aggregates) !== JSON.stringify(page.aggregates)) return null;
answer.groups = [...(answer.groups ?? []), ...(page.groups ?? [])];
}
offset += page.groups?.length ?? 0;
if (progress.done) return answer;
} while (true);
}
// βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
// ββ W51-T06 Β· RULING R2 Β· CONTRACT C6 β WHAT THIS DATABASE IS RELATED TO, AND WHETHER THE
// RELATION CAN BE PINNED TODAY.
// βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
/**
* ββ W53-T24 Β· R13 Β· C3 β THE LISTING IS TWO LISTS NOW, AND THAT IS THE WHOLE POINT.
*
* `related` is what a reader may follow; `refusals` is what was walled off on the way. R13 says
* "no related rows", "you may not see this table" and "this hop was filtered" are three
* different answers, and an answer that arrived only as a SHORTER `related` array would be
* indistinguishable from the database simply having fewer edges. So both travel, together, and
* the caller renders the second rather than dropping it.
* β THE REFUSALS NEVER WIDEN THE ENTRIES. They are parsed by a different function off a
* different key, so there is no path by which one becomes the other.
*/
export interface RelatedListing {
entries: RelatedEntry[];
refusals: RelatedRefusal[];
}
/** A stable identity, so a failed listing is not a fresh object on every render. */
const EMPTY_LISTING: RelatedListing = { entries: [], refusals: [] };
/**
* β W53-T24 Β· R13 β WHAT A REFUSED PIN ANSWERS WITH: the server's CODE and the server's
* SENTENCE. `null` still means the pin is served, unchanged.
*/
export interface RelatedRead {
code: string;
reason: string;
/**
* β THE X2 ENVELOPE'S OWN `table` AND `hop`, CARRIED BECAUSE R13 ASKS THE REFUSAL TO NAME ITS
* SUBJECT and the client must not mine the sentence for it. `table` rides on `forbidden_table`
* and MAY name the INTERMEDIATE table of a two-hop path, which is the exact case R13 exists
* for: read on both ends, walled out of the middle. `hop` rides on `hop_filtered` and names
* the edge key the wall took.
*/
table?: string;
hop?: string;
}
/**
* `GET /api/v1/grid/{table}/related?depth=2` β every edge THIS ACCOUNT may follow, forward then
* reverse then bridge, and (at depth 2) the SECOND JUMPS beyond them.
*
* β AN EMPTY LISTING ON ANY FAILURE, NEVER A THROW. A record whose relations cannot be listed
* still opens on its Fields tab; a rejected promise here would take the whole drawer down for a
* list that is chrome.
* β The permission narrowing happens SERVER-SIDE (`routes_grid.related_entries` filters on
* `_may_open`), so an edge that is not in this answer is also an edge that cannot be pinned.
* There is deliberately no second, laxer resolution on this side.
*
* β R12 CAPS THE TRAVERSAL AT TWO, so `depth` is typed `1 | 2` rather than `number`: depth 3 is
* a refusal the server has to author (it names the missing hop), and this client cannot even
* spell the request that would earn it. MEASURED 2026-09-05 on this branch: `?depth=2` is
* ACCEPTED AND IGNORED β 200, the same six entries, no `hops` and no `path` on any of them β
* so sending it today changes nothing and is what makes the consumer ready the day D lands.
*/
export async function fetchRelated(table: string, depth: 1 | 2 = 2): Promise<RelatedListing> {
try {
const res = await fetch(
`${API_V1}/grid/${encodeURIComponent(table)}/related?depth=${depth}`,
{ credentials: CREDENTIALS }
);
if (handledSession(res) || !res.ok) return EMPTY_LISTING;
const body = await readJson(res);
return { entries: relatedEntries(body), refusals: relatedRefusals(body) };
} catch {
return EMPTY_LISTING;
}
}
/**
* ββ CAN THIS EDGE BE SERVED AS A PINNED READ, AND IF NOT, IN WHOSE WORDS?
*
* ββ THE SENTENCE HAS EXACTLY ONE AUTHOR, AND IT IS THE SERVER. `relations.py` already writes
* three of them (`unknown_via_refusal`, `unresolvable_source_refusal`,
* `unserved_target_refusal`), each naming a cause and a recommendation. Spelling a fourth here
* would be a second opinion about one wire contract, which is how a feature ships with both
* halves correct and disagreeing [[two-lanes-one-contract-dead-feature]]. So this asks for ONE
* row and reports what came back: `null` when the pin is served, the server's own sentence when
* it is not.
*
* β AND IT IS WHY THE TAB DOES NOT SIMPLY MOUNT AND HOPE. `useCustomerData`'s failure channel
* is `DATA_ERROR_EVENT`, which REPLACES the surface with an error card; a declared-but-unserved
* relation is a reported limit, not a broken screen. `bridge_customer_open_invoices` is the one
* such edge today (`ut_odoo_invoices` is materialised and absent from `GRID_SOURCES`), and a
* link whose target is an ordinary user table is the same shape for a different reason: that
* door (`routes_tables.table_rows`) takes no predicate at all.
*
* ββ W53-T24 Β· R13 β IT NOW RETURNS THE **CODE** BESIDE THE SENTENCE, AND THAT IS NOT A SECOND
* OPINION ABOUT THE WORDS. R13 asks for three refusals to be TOLD APART; a bare string can be
* printed but it cannot be branched on without the client re-reading the server's prose, which
* is the same "second author of one contract" mistake wearing a regular expression. The code
* picks the TREATMENT (which voice, which `role`, which emphasis); the sentence stays the
* server's, verbatim, in every one of the three.
* β Read from `body.error.code` β the X2 envelope, the same one `refusalMessage` documents 400
* lines above. `""` when the body carries no code, which is honest rather than a guess.
*/
export async function probeRelatedRead(
tableKey: string,
related: RelatedPin
): Promise<RelatedRead | null> {
const path = windowRowsPath(tableKey, { offset: 0, limit: 1, related });
let res: Response;
try {
res = await fetch(`${API_V1}/${path}`, { credentials: CREDENTIALS });
} catch {
return {
// β NO CODE. The server never answered, so there is no code to report and no state to
// treat specially; the caller falls through to printing this sentence plainly.
code: "",
reason: "The server could not be reached, so these related records cannot be shown yet. "
+ "Check the connection and open this tab again.",
};
}
if (handledSession(res)) return null;
if (res.ok) return null;
const body = await readJson(res);
const err = (body as { error?: { code?: unknown; table?: unknown; hop?: unknown } } | null)
?.error;
const out: RelatedRead = {
code: typeof err?.code === "string" ? err.code : "",
reason: refusalMessage(body, res.status),
};
if (typeof err?.table === "string" && err.table) out.table = err.table;
if (typeof err?.hop === "string" && err.hop) out.hop = err.hop;
return out;
}
/**
* `GET /api/v1/workspace` β the saved views, custom fields, folders and cohorts
* for the session user (S1's amendment, 2026-07-30). It exists because X2 pins
* `/customers` at the EXACT current shape, which carries no `workspace`, and
* without one the standalone write path is WRITE-ONLY: a saved view reaches the
* store and is gone from the screen on reload.
*
* The body is `{workspace: GridWorkspace}` β the client's own built type
* (types.ts `GridWorkspace`), which is what the embed's host already projects.
*
* β A 404 retains compatibility with a host that does not ship this route:
* views in memory, no `storageKey`, nothing durable. It degrades to the
* honest gap rather than failing the whole read, because the workspace is an
* enhancement of the table, not a precondition for it. A malformed 200 needs
* a scoped error and Retry. A 401 still ends the session.
*
* β WAVE 21 item 3 (3c) β BUT A REFUSAL IS NOT AN ABSENCE, and conflating the
* two is half of the "RI fields on a new database" report.
*
* This used to answer `null` to every unhappy path alike: route-not-shipped,
* 403, 500, connection refused, garbage body. The caller cannot tell those
* apart, so it did the only thing it could β carried on without a workspace β
* and `CustomerGrid` then had no `storageKey` and fell back to a bucket shared
* with every other surface (see the note at its `storageKey`). A tenant whose
* `/workspace` 403s for `ut_*` therefore got ANOTHER TABLE'S views and fields,
* silently, with the grid looking entirely healthy.
*
* Workspace failures use a scoped status and a nonfatal notification. The rows
* reader owns DATA_ERROR_EVENT; metadata cannot replace independently ready rows.
*
* β IT IS OFF BY DEFAULT, and that is load-bearing rather than cautious.
* `reread()` calls this on every workspace-stale signal, and its own rule is
* "absent stays absent β never blank a live panel"; a signal from there would
* let one dropped packet replace a working table with an error card. Callers
* can consume onStatus to offer an inline metadata retry instead.
*/
/**
* HOTFIX 2026-09-29 (owner: "clicking edit for cell database ... is still very slow"). The memo's
* answer for `scope` when it is inside its freshness window, WITHOUT a request, else null. A
* panel paints from it at once and still asks the server; the server's answer replaces it.
*/
export function peekWorkspace(scope: SurfaceScope, opts: { fieldsOnly?: boolean } = {}): GridWorkspace | null {
const key = opts.fieldsOnly ? `${scope}:fields` : scope;
const hit = wsCache.get(key);
return hit && Date.now() - hit.at < CUSTOMERS_FRESH_MS ? workspaceWithoutMetricCells(hit.ws) : null;
}
export async function fetchWorkspace(
scope: SurfaceScope = "customer",
opts: { announceFailure?: boolean; allowCached?: boolean; refresh?: boolean; fieldsOnly?: boolean;
onStatus?: (status: WorkspaceStatus) => void } = {},
): Promise<GridWorkspace | null> {
const loud = opts.announceFailure === true;
const fieldsOnly = opts.fieldsOnly === true;
const key = fieldsOnly ? `${scope}:fields` : scope;
const requestEpoch = wsCacheEpoch;
const fullAtStart = wsCache.get(scope);
// β W31-T21 β OPT IN, NEVER BY DEFAULT. Only the first-paint read of a surface may be served
// from the memo; the post-write `reread()` calls this with no options and therefore always goes
// to the server, which is what keeps the memo from becoming a second source of truth.
if (opts.allowCached === true) {
const hit = wsCache.get(key);
// A warm-open refresh bypasses only the completed memo, and still joins pending work.
if (!opts.refresh && hit && Date.now() - hit.at < CUSTOMERS_FRESH_MS) {
opts.onStatus?.({ scope, state: "ready" });
return workspaceWithoutMetricCells(hit.ws);
}
}
let pending = opts.allowCached === true ? wsFlights.get(key) : undefined;
if (!pending) {
// A fresh full question invalidates older schema offers through this same memo.
if (!fieldsOnly) {
wsCache.delete(`${scope}:fields`);
wsFlights.delete(`${scope}:fields`);
const previousFull = wsCache.get(scope);
if (previousFull) previousFull.current = false;
}
const epoch = wsCacheEpoch;
const readOrder = ++workspaceOrder;
let flight: Promise<WorkspaceRead>;
flight = readWorkspace(scope, epoch, fieldsOnly, readOrder,
() => wsFlights.get(key) === flight && readOrder > (workspaceWrites.get(scope) ?? 0));
pending = flight;
wsFlights.set(key, pending);
void flight.then(() => {
if (wsFlights.get(key) === flight) wsFlights.delete(key);
});
}
let result = await pending;
if (fieldsOnly && result.superseded && requestEpoch === wsCacheEpoch) {
// A Sheet full read may supersede the editor's schema read. Follow the current
// existing flight, then use only an authoritative full memo published since this
// question began. A failed full read cannot turn an older offer into a fresh one.
let full = wsFlights.get(scope);
while (full) {
result = await full;
if (requestEpoch !== wsCacheEpoch) return null;
const next = wsFlights.get(scope);
full = next !== full ? next : undefined;
}
const current = wsCache.get(scope);
result = current && current.current && current !== fullAtStart && Date.now() - current.at < CUSTOMERS_FRESH_MS
? { ws: workspaceWithoutMetricCells(current.ws) }
: { ws: null, failure: result.failure, ...(result.forbidden ? { forbidden: true } : {}) };
}
const latestWrite = workspaceWrites.get(scope) ?? 0;
if (result.ws && workspaceReadOrder(result.ws) < latestWrite) {
const current = wsCache.get(key)?.ws;
result = current && workspaceReadOrder(current) >= latestWrite
? { ws: current } : { ws: null, superseded: true };
}
// A departed session or superseded request cannot publish even a failure into the new scope.
if (requestEpoch !== wsCacheEpoch || result.superseded) return null;
// Each joiner receives its own scoped status; response parsing/session handling happen once.
const status: WorkspaceStatus = result.failure
? { scope, state: "error", message: result.failure, ...(result.forbidden ? { forbidden: true } : {}) }
: { scope, state: result.ws ? "ready" : "absent" };
opts.onStatus?.(status);
if (loud && result.failure) signal(WORKSPACE_ERROR_EVENT, status);
const good = result.ws;
return good ? workspaceWithoutMetricCells(good) : null;
}
/** The one sentence a database shows when its saved views and columns stall past the deadline. */
export const DATABASE_TIMEOUT_MESSAGE = "This database did not load in time.";
async function readWorkspace(scope: SurfaceScope, epoch: number, fieldsOnly: boolean, readOrder: number,
isCurrent: () => boolean): Promise<WorkspaceRead> {
const superseded = (): WorkspaceRead => {
const latestWrite = workspaceWrites.get(scope) ?? 0;
const current = wsCache.get(fieldsOnly ? `${scope}:fields` : scope)?.ws;
// A read started before the ACK can return only the patched memo, never its old body.
return epoch === wsCacheEpoch && readOrder < latestWrite && current && workspaceReadOrder(current) >= latestWrite
? { ws: current } : { ws: null, superseded: true };
};
let res: Response;
let body: unknown;
let handled = false;
try {
// The body read shares the deadline: a stalled server ends in the error state, never a spinner.
// The session and epoch checks run before the body is parsed: a tenant swap reloads unread.
({ res, body } = await fetchWithDeadline(
`${API_V1}/workspace?scope=${encodeURIComponent(scope)}${fieldsOnly ? "&fields_only=1" : ""}`,
{ credentials: CREDENTIALS },
(r) => (handled = handledSession(r)) || epoch !== wsCacheEpoch ? Promise.resolve(null) : readJson(r),
fieldsOnly ? READ_DEADLINE_MS : WORKSPACE_DEADLINE_MS));
} catch (error) {
return epoch === wsCacheEpoch && isCurrent()
? { ws: null, failure: isReadTimeout(error) ? DATABASE_TIMEOUT_MESSAGE : "Cannot reach the server." }
: superseded();
}
if (handled || epoch !== wsCacheEpoch) return { ws: null };
if (!res.ok) {
if (!isCurrent()) return superseded();
if (isCurrent() && (res.status === 403 || res.status === 404)) {
wsCache.delete(scope);
wsCache.delete(`${scope}:fields`);
wsFlights.delete(scope);
wsFlights.delete(`${scope}:fields`);
}
// 404 is the ONE status that means "this host does not serve a workspace",
// which is the enhancement posture above and stays quiet. Everything else
// is a server that had an answer and would not give it.
return res.status === 404 ? { ws: null } : {
ws: null,
failure: refusalMessage(
body, res.status,
`The server answered ${res.status} for this table's saved views and columns.`),
...(isForbiddenRefusal(res.status, body) ? { forbidden: true } : {}),
};
}
const ws = body as { workspace?: GridWorkspace } | null;
if (epoch !== wsCacheEpoch) return { ws: null };
const w = ws?.workspace as (GridWorkspace & { fieldsOnly?: boolean }) | undefined;
// Only 404 means compatibility absence. An unreadable 200 needs an actionable retry.
const good = w && typeof w.storageKey === "string" && w.storageKey.length > 0 && Array.isArray(w.views)
&& w.views.every((view) => view && typeof view.id === "string")
&& (w.fields === undefined || (Array.isArray(w.fields)
&& w.fields.every((field) => field && typeof field.key === "string")))
&& (w.measures === undefined || (Array.isArray(w.measures)
&& w.measures.every((measure) => measure && typeof measure.key === "string")))
&& (w.derived === undefined || (w.derived && typeof w.derived === "object" && !Array.isArray(w.derived)
&& Object.values(w.derived).every((cells) => cells && typeof cells === "object" && !Array.isArray(cells))))
&& (fieldsOnly ? w.fieldsOnly === true : w.fieldsOnly !== true) ? w : null;
if (!isCurrent()) return superseded();
if (!good) {
wsCache.delete(fieldsOnly ? `${scope}:fields` : scope);
return { ws: null, failure: "Saved views could not be loaded." };
}
// β W31-T21 β EVERY SUCCESSFUL READ REFRESHES THE MEMO, including the post-write `reread()`
// that is not allowed to CONSUME it. That asymmetry is the whole safety argument: the write
// path can never leave a stale envelope behind for the next switch to serve.
// β A FAILURE LEAVES THE PREVIOUS ENTRY ALONE rather than poisoning it with `null` β the same
// "absent stays absent, never blank a live panel" posture `reread()` already takes.
if (good && isCurrent()) {
const key = fieldsOnly ? `${scope}:fields` : scope;
const previous = wsCache.get(key)?.ws;
workspaceReads.set(good, readOrder);
wsCache.set(key, { at: Date.now(), ws: good, current: true });
if (!fieldsOnly) {
wsCache.delete(`${scope}:fields`);
wsFlights.delete(`${scope}:fields`);
}
// A refreshed metric definition or answer is read again through each grid's own pin.
// The same rows door still supplies the ordinary record's global Details values.
if (!fieldsOnly && previous && JSON.stringify(metricWorkspaceCells(previous)) !== JSON.stringify(metricWorkspaceCells(good))) {
rowsCache.clear();
windowPaging.clear();
signal(ROWS_STALE_EVENT);
}
}
return { ws: good };
}
function metricWorkspaceCells(workspace: GridWorkspace): unknown {
const fields = (workspace.fields ?? []).filter((field) => field.measure);
if (fields.length === 0) return null;
const keys = new Set(fields.map((field) => field.key));
return { fields, cells: Object.fromEntries(Object.entries(workspace.derived ?? {}).map(([pid, cells]) =>
[pid, Object.fromEntries(Object.entries(cells).filter(([key]) => keys.has(key)))])) };
}
/** Workspace metadata is shared by pinned and ordinary grids; metric amounts are row data. */
export function workspaceWithoutMetricCells(workspace: GridWorkspace): GridWorkspace {
const metrics = new Set((workspace.fields ?? []).filter((field) => field.measure).map((field) => field.key));
const admitted = Array.isArray(workspace.measures) ? new Set(workspace.measures.map((measure) => measure.key)) : null;
const fields = workspace.fields?.filter((field) => !field.measure || admitted === null || admitted.has(field.measure.key));
const projected = { ...workspace, fields, derived: Object.fromEntries(Object.entries(workspace.derived ?? {}).map(([pid, cells]) =>
[pid, Object.fromEntries(Object.entries(cells).filter(([key]) => !metrics.has(key)))])) };
workspaceReads.set(projected, workspaceReadOrder(workspace));
return projected;
}
// --- the CHANGE POLLER (wave 29, item 20 / R11 / contract C6) ---------------
/**
* `GET /api/v1/changes?scope=β¦` β `{bucket: opaque token}`, or null.
*
* β A FAILED POLL IS SILENT. It raises no `DATA_ERROR_EVENT`, because the frame REPLACES the whole
* surface with an error card on that signal β so one dropped packet, six times a minute, would turn
* a working grid into a failure screen. `changedBuckets` reads a null as "no baseline, no change"
* and the tab simply carries on with what it has. 401 still ends the session: that is the one
* status which is never about this route.
*/
export async function fetchChangeTokens(scope: string): Promise<ChangeTokens | null> {
let res: Response;
try {
res = await fetch(`${API_V1}/changes?scope=${encodeURIComponent(scope)}`,
// This header marks a current, user-return check. Legacy bundles lack it,
// so their former 10-second requests remain database-free on Pg.
{ credentials: CREDENTIALS, headers: { "X-AIOS-Change-Check": "focus-v1" } });
} catch {
return null;
}
if (handledSession(res)) return null;
if (!res.ok) return null;
const body = (await readJson(res)) as { tokens?: unknown } | null;
const tokens = body?.tokens;
if (!tokens || typeof tokens !== "object" || Array.isArray(tokens)) return null;
const out: ChangeTokens = {};
for (const [bucket, token] of Object.entries(tokens as Record<string, unknown>))
out[bucket] = typeof token === "string" ? token : null;
return out;
}
/**
* A grid reloads only when the person returns to the tab or window. There is no timer and no
* background token request.
*/
interface ChangeWatch {
listeners: Set<(changed: string[]) => void>;
tokens: ChangeTokens | null;
/** The last own write `tokens` is known to include. */
ownSeq: number;
inFlight: boolean;
/** `rebaseline`: a read after this tab's own write. It runs in a hidden tab too. */
refresh: (rebaseline?: boolean) => Promise<void>;
/** β ONE poll implementation per watch, held here so the interval and the visibility handler
* call the SAME function. The visibility handler used to re-inline the body, which quietly
* skipped `inFlight` β so returning to a tab whose poll was still outstanding stacked a second
* request on top of it, exactly what that guard exists to prevent. */
}
const changeWatches = new Map<string, ChangeWatch>();
let visibilityBound = false;
function refreshVisibleChanges(): void {
if (document.visibilityState !== "visible") return;
for (const watched of changeWatches.values())
void watched.refresh();
}
// S85-T26: a token read that can contain this tab's own write moves the baseline and reports
// nothing. Only a read taken after every own write settled can report an outside change.
let ownWritesOpen = 0;
let ownWriteSeq = 0;
let rebaselineTimer: ReturnType<typeof setTimeout> | undefined;
/** A burst of own writes costs one token read, taken this long after the last one settles. */
export const CHANGE_REBASELINE_MS = 300;
/** Run one write from this tab so the change baseline moves past it. An abort also ends it, so
* a transport that ignores its signal cannot hold every later check open. */
async function ownWrite<T>(work: () => Promise<T>, abort?: AbortSignal): Promise<T> {
let open = true;
const close = () => {
if (!open) return;
open = false;
ownWritesOpen -= 1;
ownWriteSeq += 1;
if (rebaselineTimer !== undefined) clearTimeout(rebaselineTimer);
rebaselineTimer = undefined;
if (changeWatches.size) rebaselineTimer = setTimeout(() => {
rebaselineTimer = undefined;
for (const watched of changeWatches.values()) void watched.refresh(true);
}, CHANGE_REBASELINE_MS);
};
ownWritesOpen += 1;
abort?.addEventListener("abort", close, { once: true });
try {
return await work();
} finally {
abort?.removeEventListener("abort", close);
close();
}
}
/**
* Watch one scope for server-side changes. Returns its unsubscribe.
*
* β ONE WATCH PER SCOPE, REFCOUNTED. A linked-record grid can mount a second `useCustomerData` on
* the same surface, and both listeners share one mount baseline and one return-to-tab refresh.
*
* β IT NEVER POLLS. Own writes update the current tab from their response; a change made elsewhere
* is checked when the person returns to this tab or focuses its window. A forgotten tab left open
* overnight creates no database traffic.
*/
export function subscribeChanges(scope: string,
onChange: (changed: string[]) => void,
{ baseline = true }: { baseline?: boolean } = {}): () => void {
if (typeof window === "undefined") return () => {};
let watch = changeWatches.get(scope);
if (!watch) {
const w0: ChangeWatch = {
listeners: new Set(), tokens: null, ownSeq: ownWriteSeq, inFlight: false,
refresh: async (rebaseline = false) => {
if (w0.inFlight || (!rebaseline && document.visibilityState !== "visible")) return;
w0.inFlight = true;
const seq = ownWriteSeq, quiet = ownWritesOpen === 0;
let next: ChangeTokens | null = null;
try {
next = await fetchChangeTokens(scope);
const settled = quiet && ownWritesOpen === 0 && ownWriteSeq === seq;
const changed = settled && w0.ownSeq === seq ? changedBuckets(w0.tokens, next) : [];
if (next) {
w0.tokens = next;
if (settled) w0.ownSeq = seq;
}
if (changed.length)
for (const listener of [...w0.listeners]) listener(changed);
} finally {
w0.inFlight = false;
}
// An own write that overlapped this read may have landed after it. Read once more.
if (next && w0.ownSeq !== ownWriteSeq && ownWritesOpen === 0 && rebaselineTimer === undefined
&& changeWatches.get(scope) === w0) void w0.refresh(true);
},
};
watch = w0;
changeWatches.set(scope, w0);
}
const w = watch;
w.listeners.add(onChange);
// S65-T12: baseline on subscribe by default; grids defer this read until their first payload
// lands. Racing the rows fetch cost 4,857 ms; the same read alone took 5 ms. Later user returns
// can still preserve the browser cache when nothing changed. It is never an interval.
if (baseline) primeChangeBaseline(scope);
if (!visibilityBound) {
visibilityBound = true;
window.addEventListener("visibilitychange", refreshVisibleChanges);
window.addEventListener("focus", refreshVisibleChanges);
}
return () => {
w.listeners.delete(onChange);
if (w.listeners.size === 0) {
// β The tokens are DROPPED with the last listener. A remount must re-baseline rather than
// compare against a token from before it was unmounted.
changeWatches.delete(scope);
}
};
}
/** Take a subscribed scope's first baseline through its ONE guarded refresh path. */
export function primeChangeBaseline(scope: string): void {
const w = changeWatches.get(scope);
if (w && w.tokens === null && !w.inFlight) void w.refresh();
}
/** A refusal keeps its machine code separate from the sentence shown by the existing toast. */
export interface CellWriteFailure { code: string; message: string }
/** Only admitted canonical row reads can invalidate a successful cell duplicate. */
function observeCanonicalRows(topic: TopicConfig, payload: CustomersPayload): void {
const fields = payload.fields.map((field) => field.key);
for (const row of payload.rows) editOutbox.observeCells(topic.scope, row.pid,
Object.fromEntries(fields.map((key) => [key, row[key]])));
}
/** Update each cached page without extending its source freshness or widening its field wall. */
function adoptCachedRow(topic: TopicConfig, pid: number, accepted: Partial<Row>): boolean {
editOutbox.observeCells(topic.scope, pid, accepted);
const keys = new Set(Object.keys(accepted));
const prefixes = [topic.rowsPath, `tables/${topic.key}/rows`, `odoo-tables/${topic.key}/rows`];
const fields = new Map<string, Field>();
const relationFields = [...wsCache.values()].map(({ ws }) => ws.fields ?? [])
.concat([...rowsCache.values()].map(({ payload }) => payload.fields));
const mentions = (raw: string | null): boolean => {
if (!raw) return false;
try {
const visit = (value: unknown): boolean => Array.isArray(value) ? value.some(visit)
: !!value && typeof value === "object" && Object.entries(value).some(([key, item]) =>
(key === "colId" && typeof item === "string" && keys.has(item)) || visit(item));
return visit(JSON.parse(raw));
} catch { return true; }
};
for (const [path, cached] of rowsCache) {
if (!prefixes.some((prefix) => path === prefix || path.startsWith(`${prefix}?`))) continue;
const allowed = new Set(cached.payload.fields.map((field) => field.key));
for (const field of cached.payload.fields) fields.set(field.key, field);
const row = cached.payload.rows.find((record) => record.pid === pid);
if (row) for (const [key, value] of Object.entries(accepted))
if (allowed.has(key)) row[key] = value;
const query = new URLSearchParams(path.split("?")[1] ?? "");
const changesLinks = cached.payload.fields.some((field) => keys.has(field.key) && field.type === "link");
// Membership and order can change even when this page did not contain the edited row.
if (query.get("search") || mentions(query.get("filters")) || mentions(query.get("sorts"))
|| keys.has(query.get("groupBy") ?? "") || (query.has("related") && changesLinks)) rowsCache.delete(path);
}
const workspaceFields = wsCache.get(topic.scope)?.ws.fields ?? [];
for (const field of workspaceFields) fields.set(field.key, field);
rowVersions.set(topic.key, (rowVersions.get(topic.key) ?? 0) + 1);
return [...keys].some((key) => fields.get(key)?.type === "link")
|| relationFields.some((book) => book.some((field) => {
const rollup = field.rollup;
const link = book.find((candidate) => candidate.key === rollup?.link)?.link;
return link?.table === topic.key && !!rollup &&
[rollup.field, rollup.sortBy, rollup.distinctBy,
...(rollup.where ?? []).map((rule) => rule.field), ...(rollup.conditions ?? []).map((rule) => rule.field)]
.some((key) => !!key && keys.has(key));
}));
}
/** Queue synchronously so page exit also covers the IndexedDB persistence gap. */
export async function patchTopicRow(
topic: TopicConfig,
pid: number,
updates: Partial<Row>,
onAccepted?: (accepted: Partial<Row>, cleared: string[]) => void,
onFailure?: (failure: CellWriteFailure) => void,
): Promise<boolean> {
const session = writeSession;
const rowKey = `${topic.rowsPath}/${pid}`;
const id = eventId("cell");
const task = editOutbox.enqueue({ id, kind: "row", scope: topic.scope,
payload: { pid, updates } }, (receipt) => {
if (session !== writeSession) return;
const result = receipt.result as { accepted: Partial<Row>; cleared: string[] } | undefined;
if (result) onAccepted?.(result.accepted, result.cleared);
if (receipt.ok) {
return;
} else {
const failure = { code: receipt.code ?? "write_refused",
message: receipt.message ?? "This edit could not be saved." };
if (onFailure) onFailure(failure);
else signal(TOAST_EVENT, failure.message);
refreshFrozenOutboxRefusal(receipt);
}
});
rowWrites.set(rowKey, task);
try { return await task; }
finally { if (rowWrites.get(rowKey) === task) rowWrites.delete(rowKey); }
}
/** The customer topic's patch, by its historical name. */
export function patchCustomer(pid: number, updates: Partial<Row>): Promise<boolean> {
return patchTopicRow(CUSTOMER_TOPIC, pid, updates);
}
/**
* β Wave-20 owner item 4 / contract C-ADDROW β **APPEND A ROW TO A USER DATABASE**, and
* (C-UNDO) restore a deleted one under its old id.
*
* USER TABLES ONLY, and the refusal is structural rather than checked here: no other scope has
* a `/tables/{key}/rows` endpoint at all. A connector's rows are read-synced from its source β
* R8 is explicit that a "+" which must refuse is a fake affordance, so the caller never renders
* one there.
*
* β THE ANSWER IS THE ID THAT WAS STORED, never the one that was asked for. An undo that
* requests `rid` may find that id re-used, and the server's own note says it answers with what
* it actually wrote; the caller re-anchors on the returned value rather than assuming.
*
* β The rows cache is CLEARED on success. `fetchTopicRows` holds a 5-minute window per topic,
* so a re-read straight after an append would serve the payload from before it β the new row
* would appear minutes later, which reads as "the button did nothing". Same reason the shell's
* retired Add-record bar cleared it (wave 20 item 4 moved that door here).
*/
export interface TableRowAcknowledgement {
rid: string | number;
pid: number;
values?: Record<string, string | number | null>;
}
export async function addTableRow(
tableKey: string,
values: Record<string, unknown> = {},
rid?: string | number,
restore = false
): Promise<TableRowAcknowledgement | null> {
try {
const res = await fetch(`${API_V1}/tables/${encodeURIComponent(tableKey)}/rows`, {
method: "POST",
credentials: CREDENTIALS,
headers: JSON_HEADERS,
body: JSON.stringify(rid === undefined ? { values, restore } : { rid, values, restore }),
});
if (handledSession(res)) return null;
const body = (await readJson(res)) as { rid?: string | number; pid?: number; values?: unknown;
error?: { message?: string } } | null;
if (!res.ok) {
// The server states WHY (a row cap, a store refusal). Surfacing its sentence beats a
// generic failure toast, and staying silent would be the worst of the three.
const why = refusalMessage(body, res.status);
signal(TOAST_EVENT, why);
return null;
}
if (body?.rid === undefined || typeof body?.pid !== "number") {
signal(DATA_ERROR_EVENT, "The server did not say which row it created.");
return null;
}
dropTableRowsCache(tableKey);
const accepted: TableRowAcknowledgement["values"] = body.values &&
typeof body.values === "object" && !Array.isArray(body.values) ? {} : undefined;
if (accepted) for (const [key, value] of Object.entries(body.values as Record<string, unknown>)) {
if (key === "pid") continue;
if (value === null || typeof value === "string" ||
(typeof value === "number" && Number.isFinite(value))) accepted[key] = value;
else if (typeof value === "boolean") accepted[key] = value ? "True" : "False";
}
return { rid: body.rid, pid: body.pid, ...(accepted ? { values: accepted } : {}) };
} catch {
signal(DATA_ERROR_EVENT, "Cannot reach the server.");
return null;
}
}
/**
* β WAVE 21 item 7 (contract C2) β ADD A COLUMN TO A USER DATABASE'S **DEFINITION**,
* not to this user's overlay.
*
* β THE BUG THIS EXISTS FOR. Every column the grid creates has always gone out as a
* `field_upsert` EVENT, which lands in the per-user workspace stratum
* (`<key>_table_workspace`). That is right for the connector surfaces, where a custom
* column IS one person's annotation of somebody else's data. It is wrong for a user
* database, where the columns ARE the table β and it is why the automation editor's
* "Automation column" picker was empty by construction: that picker reads the DEFINITION
* (`user_tables`), which the grid had never written to. Two stores, one word, and the two
* surfaces disagreed with no error anywhere. The route has existed since wave 18 with no
* client caller; this is that caller, and `routes_tables.py`'s own comment above it names
* this exact defect.
*
* β SCOPED TO THE AUTOMATION KIND THIS WAVE (C2, deliberately narrow). Moving EVERY kind
* onto the definition is the right end state and is booked as debt: it changes who can see
* a column (everyone with the table, not just its author), which is a visible change to
* shipped behaviour on three surfaces and does not belong in a wave that is fixing this
* one's blindness.
*
* β THE SERVER'S FIELD IS THE ANSWER, never the request. `add_field` re-slugs and
* re-types on the way in, so the caller inserts what came BACK β a column ordered under a
* key the store does not hold is a column that renders nowhere.
*/
/**
* ββ 2026-08-07 (D-79's last half) β PATCH one column's DEFINITION on a user table.
*
* β WHY IT EXISTS: wave 25 shipped the profile flag's READER everywhere β the column-menu line,
* the cell validator, R6's clear-on-write, the one-per-table refusal β and never its WRITER. The
* route (`PATCH /tables/{key}/fields/{fkey}`) has accepted `profile` since that wave with no
* client caller, so the enrich action could not be bound to any database a person made
* themselves. This is that caller.
*
* β THE SERVER'S FIELD IS THE ANSWER, never the request β the same rule `addTableField` carries.
* `_clean_field` enforces `type: 'text'` for a profile flag and refuses a SECOND one with a
* sentence naming the column that already has it, so the refusal is worth surfacing verbatim.
*/
/**
* β 2026-08-07 β the sibling databases a `link` column may point at, WITH their fields.
*
* `GET /tables` already returns exactly this (key, label, fields) filtered by `may_open`, so
* there is no new route and no new wall: a database you cannot open is a database you cannot
* link to, decided by the same predicate that decides whether you can see it at all.
*
* β Returns `[]` on any failure rather than throwing. The link editor renders "no other
* databases yet" for an empty list, which is the truthful reading of both an empty workspace
* and an unreachable server β and a create pane that explodes because a picker could not fetch
* is worse than one that says it has nothing to offer.
*/
export async function fetchLinkTargets(): Promise<LinkTarget[]> {
try {
// A link picker uses only key/label/schema. `brief=1` keeps the server's table wall but does
// not transfer row counts or the row-bearing `user_tables` document for this one field menu.
const res = await fetch(`${API_V1}/tables?brief=1`, { credentials: CREDENTIALS });
if (handledSession(res) || !res.ok) return [];
const body = (await readJson(res)) as { tables?: LinkTarget[] } | null;
return Array.isArray(body?.tables) ? body.tables : [];
} catch {
return [];
}
}
export interface LinkTarget {
key: string;
label: string;
fields: Field[];
}
/**
* ββ 2026-08-09 β the READ-THROUGH rollup's offer: which governed Odoo topic, which metric of
* it, grouped by which dimension, over which date window.
*
* β WHY THIS IS A DIFFERENT LIST FROM `fetchLinkTargets`. A LINK rollup folds rows that live in
* the workspace, so its offer is "the other databases". A SOURCE rollup folds rows that were
* never copied here at all β 256,810 order lines answered by one grouped SQL query β so its
* offer is the semantic model, and the server derives it from `model/topics/*.yml` +
* `model/metrics/*.yml` rather than from anything the client knows.
*
* β Returns an EMPTY offer on any failure rather than throwing, for the same reason the link
* picker does: the editor then renders "no live sources are available", which is the truthful
* reading of both a tenant with no Odoo mirror and an unreachable server.
*/
export async function fetchRollupSources(): Promise<RollupSourceOffer> {
try {
const res = await fetch(`${API_V1}/tables/rollup-sources`, { credentials: CREDENTIALS });
if (handledSession(res) || !res.ok) return { topics: [], windows: [] };
const body = (await readJson(res)) as Partial<RollupSourceOffer> | null;
return {
topics: Array.isArray(body?.topics) ? body!.topics! : [],
windows: Array.isArray(body?.windows) ? body!.windows! : [],
};
} catch {
return { topics: [], windows: [] };
}
}
export interface RollupSourceOffer {
topics: RollupSourceTopic[];
windows: { key: string; label: string }[];
}
export interface RollupSourceTopic {
key: string;
label: string;
grain: string;
/** `keyedBy` says whether the group key is an Odoo ID or the dimension's own value β which is
* what decides which column on THIS database it should be matched against. */
dims: { key: string; label: string; keyedBy: "id" | "value" }[];
measures: { key: string; label: string; format: string; description: string }[];
}
/**
* W42-T08/T37: the semantic one-hop authoring offer is deliberately fetched from its own
* endpoint. It is not a projection of RollupSourceOffer: hop dimensions carry their real
* date/number/text types, which choose the filter operators rendered by FilterBuilderPanel.
*/
export interface HopTopic {
key: string;
label: string;
dims: Field[];
measures: { key: string; label: string }[];
}
export interface HopTopicOffer {
topics: HopTopic[];
windows: { key: string; label: string }[];
omissions: { topic: string; label: string; reasons: string[] }[];
}
/** Preserve the server's typed dimensions; malformed envelopes fail closed to an empty offer. */
export function hopTopicOfferFromBody(body: unknown): HopTopicOffer {
const raw = body && typeof body === "object" && !Array.isArray(body)
? body as Partial<HopTopicOffer>
: null;
return {
topics: Array.isArray(raw?.topics) ? raw.topics : [],
windows: Array.isArray(raw?.windows) ? raw.windows : [],
omissions: Array.isArray(raw?.omissions) ? raw.omissions : [],
};
}
export async function fetchHopTopics(): Promise<HopTopicOffer> {
const empty: HopTopicOffer = { topics: [], windows: [], omissions: [] };
try {
const res = await fetch(`${API_V1}/grid/hop-topics`, { credentials: CREDENTIALS });
if (handledSession(res) || !res.ok) return empty;
return hopTopicOfferFromBody(await readJson(res));
} catch {
return empty;
}
}
export async function patchTableField(
tableKey: string,
fieldKey: string,
patch: Record<string, unknown>
): Promise<Field | null> {
try {
const res = await fetch(
`${API_V1}/tables/${encodeURIComponent(tableKey)}/fields/${encodeURIComponent(fieldKey)}`,
{ method: "PATCH", credentials: CREDENTIALS, headers: JSON_HEADERS,
body: JSON.stringify(patch) }
);
if (handledSession(res)) return null;
const body = (await readJson(res)) as
| { field?: Field; error?: { message?: string } }
| null;
if (!res.ok) {
signal(TOAST_EVENT, refusalMessage(body, res.status));
return null;
}
// β 2026-08-09 β the rows cache is a SCHEMA behind after this too, and for a rollup it is a
// VALUES behind: `PATCH /fields` refreshes the relations host-side, so the aggregate in every
// row changed the moment this returned. `addTableField` has dropped it since the day it was
// written; this door needed the same line and did not have it.
dropTableRowsCache(tableKey);
return body?.field ?? null;
} catch {
signal(TOAST_EVENT, "That change did not reach the server.");
return null;
}
}
/**
* Owner, 2026-09-02 - REMOVE a select / multiselect OPTION together with the cells that hold it.
* TWO PHASES through one door: `confirm: false` COUNTS server-side (the browser holds one page of
* rows and the field's universe is uncapped, so a count taken here would be wrong exactly when it
* matters); `confirm: true` retires the option and clears its values in this user's stratum, the
* tenant-wide stratum and a user database's rows alike. The server owns the wall.
*/
export interface ChoiceRemoval {
key: string;
options: string[];
cells: number;
applied: boolean;
usage?: Record<string, number>;
}
export async function removeChoice(
scope: SurfaceScope,
key: string,
options: string[],
confirm: boolean
): Promise<ChoiceRemoval | null> {
try {
const res = await fetch(`${API_V1}/grid/choice-remove?scope=${encodeURIComponent(scope)}`, {
method: "POST", credentials: CREDENTIALS, headers: JSON_HEADERS,
body: JSON.stringify({ key, options, confirm }),
});
if (handledSession(res)) return null;
const body = await readJson(res);
if (!res.ok) {
signal(TOAST_EVENT, refusalMessage(body, res.status, "That option could not be removed."));
return null;
}
const got = body as Partial<ChoiceRemoval> | null;
if (!got || typeof got.cells !== "number") return null;
return {
key: String(got.key ?? key),
options: Array.isArray(got.options) ? got.options.map(String) : options,
cells: got.cells,
applied: got.applied === true,
...(got.usage && typeof got.usage === "object"
? { usage: got.usage as Record<string, number> }
: {}),
};
} catch {
signal(TOAST_EVENT, "That change did not reach the server.");
return null;
}
}
/**
* ββ 2026-08-10 β REMOVE a column from a user database's SHARED definition.
*
* β THE ROUTE HAS EXISTED SINCE THE DEFINITION DOORS WERE BUILT AND NOTHING EVER CALLED IT β
* `DELETE /api/v1/tables/{key}/fields/{fkey}`, mounted, guarded by `_field_or_refuse`, and
* unreachable from the product ([[artifact-with-no-importer]] from the consumer end). The
* consequence was invisible while only `link`/`rollup` used that stratum, because both arrive as
* pre-set columns on the databases people actually have. It stops being invisible the moment a
* FORMULA column lands there: `field_delete` (the overlay event) scrubs a per-user bucket the
* definition does not read, so the column would come back on the next render and the Delete
* control would be a button that lies.
*
* β NOT optimistic, unlike the overlay delete. The server refuses the last remaining column and
* refuses a pre-set one (`may_edit_field`), and removing a column from the screen that the store
* still holds is the same lie in the other direction.
*/
export async function deleteTableField(
tableKey: string,
fieldKey: string
): Promise<boolean> {
try {
const res = await fetch(
`${API_V1}/tables/${encodeURIComponent(tableKey)}/fields/${encodeURIComponent(fieldKey)}`,
{ method: "DELETE", credentials: CREDENTIALS }
);
if (handledSession(res)) return false;
if (!res.ok) {
const body = (await readJson(res)) as { error?: { message?: string } } | null;
signal(TOAST_EVENT, refusalMessage(body, res.status));
return false;
}
// The schema moved, and a deleted LINK takes its reciprocal and every rollup that folded it
// with it (`_refresh_relations` runs on this route) β so the cached rows are values behind,
// not just a column behind. Same line `patchTableField` needed.
dropTableRowsCache(tableKey);
return true;
} catch {
signal(TOAST_EVENT, "That delete did not reach the server.");
return false;
}
}
/** Per-column verdict returned by the plural schema delete door. */
export interface FieldDeleteResult {
key: string;
status: "deleted" | "refused";
code?: string;
reason?: string;
contract?: unknown;
removed?: unknown;
}
export interface FieldDeleteOutcome {
deleted: string[];
refused: string[];
results: FieldDeleteResult[];
/** The server accepted the request but did not name any affected key. */
unreadable: boolean;
}
const DELETE_ANSWER_NAMED_NO_COLUMN =
"The server accepted that delete without saying which columns went, so the table is being read " +
"again rather than guessed at.";
function refusedWholesale(
fieldKeys: readonly string[],
reason: string | undefined,
code: string,
unreadable = false,
): FieldDeleteOutcome {
return {
deleted: [],
refused: [...fieldKeys],
results: fieldKeys.map((key) => ({ key, status: "refused" as const, code, reason })),
unreadable,
};
}
/**
* Delete every selected definition through one request, including a one-item selection. The
* caller reconciles only the keys the server explicitly reports as deleted.
*/
export async function deleteTableFields(
tableKey: string,
fieldKeys: readonly string[],
): Promise<FieldDeleteOutcome> {
if (fieldKeys.length === 0) {
return { deleted: [], refused: [], results: [], unreadable: false };
}
let res: Response;
try {
res = await fetch(`${API_V1}/tables/${encodeURIComponent(tableKey)}/fields/delete`, {
method: "POST",
credentials: CREDENTIALS,
headers: JSON_HEADERS,
body: JSON.stringify({ keys: [...fieldKeys] }),
});
} catch {
return refusedWholesale(fieldKeys, "That delete did not reach the server.", "unreachable");
}
if (handledSession(res)) return refusedWholesale(fieldKeys, undefined, "session_ended");
const body = (await readJson(res)) as {
results?: unknown;
deleted?: unknown;
refused?: unknown;
error?: { message?: string; code?: string };
} | null;
if (!res.ok) {
const code = typeof body?.error?.code === "string" ? body.error.code : "refused";
return refusedWholesale(fieldKeys, refusalMessage(body, res.status), code);
}
const results: FieldDeleteResult[] = [];
if (Array.isArray(body?.results)) {
for (const entry of body.results) {
const raw = entry as Record<string, unknown> | null;
if (!raw || typeof raw.key !== "string") continue;
results.push({
key: raw.key,
status: raw.status === "deleted" ? "deleted" : "refused",
code: typeof raw.code === "string" ? raw.code : undefined,
reason: typeof raw.reason === "string" ? raw.reason : undefined,
contract: raw.contract,
removed: raw.removed,
});
}
} else {
const named = (value: unknown): string[] =>
Array.isArray(value) ? value.filter((key): key is string => typeof key === "string") : [];
for (const key of named(body?.deleted)) results.push({ key, status: "deleted" });
for (const key of named(body?.refused)) results.push({ key, status: "refused" });
}
if (results.length === 0) {
dropTableRowsCache(tableKey);
return refusedWholesale(fieldKeys, DELETE_ANSWER_NAMED_NO_COLUMN, "unreadable_answer", true);
}
const deleted = results.filter((item) => item.status === "deleted").map((item) => item.key);
const refused = results.filter((item) => item.status === "refused").map((item) => item.key);
if (deleted.length > 0) dropTableRowsCache(tableKey);
return { deleted, refused, results, unreadable: false };
}
/**
* ββ 2026-08-09 β THE DEFINITION SHAPE, NOT A THREE-KEY SUMMARY.
*
* This used to be typed `{key, label, type}`, which was not merely narrow β it was the second
* half of the defect that made a user-built Rollup permanently blank. `ColumnMenu` builds a
* complete `rollup` bag and hands it over; a parameter type naming three keys meant the only
* caller sent three keys, so the bag never left the browser. `_clean_field` REFUSES a rollup
* with no bag, so the shape below is what makes the create legal at all.
*/
export interface TableFieldDefinition {
key: string;
label: string;
type: string;
link?: Record<string, unknown>;
rollup?: Record<string, unknown>;
options?: string[];
[extra: string]: unknown;
}
export async function addTableField(
tableKey: string,
field: TableFieldDefinition
): Promise<Field | null> {
try {
const res = await fetch(`${API_V1}/tables/${encodeURIComponent(tableKey)}/fields`, {
method: "POST",
credentials: CREDENTIALS,
headers: JSON_HEADERS,
body: JSON.stringify(field),
});
if (handledSession(res)) return null;
const body = (await readJson(res)) as
| { ok?: boolean; value?: Field | null; refused?: boolean; reason?: string;
field?: Field; error?: { message?: string } }
| null;
if (!res.ok || body?.ok === false || body?.refused === true) {
// The server states WHY β the column cap, an unknown type (this is the 400 to expect
// until `UT_FIELD_TYPES` learns `automation`, C2's other half), a wall refusal. Its
// sentence beats anything invented here.
const why = refusalMessage(body, res.status, body?.reason?.trim() || undefined);
signal(TOAST_EVENT, why);
return null;
}
const made = body && "value" in body ? body.value : body?.field;
if (!made || typeof made.key !== "string") {
signal(DATA_ERROR_EVENT, "The server did not say which column it created.");
return null;
}
// The definition feeds BOTH payloads for a user table (`ut_assembly` builds the rows
// envelope and `/workspace` from the same `fields_base`), so the cached rows are now a
// schema behind. Cheap to drop, and a stale schema is not a stale number β it is a
// column that exists on the server and nowhere on screen.
dropTableRowsCache(tableKey);
return made;
} catch {
signal(DATA_ERROR_EVENT, "Cannot reach the server.");
return null;
}
}
/**
* β WAVE 21 item 11 (ruling R10, contract C5) β parse an uploaded `.xlsx`/`.csv` and
* hand back its COLUMNS AND VALUES as strings.
*
* β THE FILE NEVER BECOMES DATA. This reads a spreadsheet to find out which records the
* user means; nothing here writes a row, creates a field, or keeps the file. The server
* parses (openpyxl is not a thing a browser has) and answers with strings β the matching
* itself is client-side, over rows this browser already holds (`fileSelect.ts`).
*
* β `truncated` IS THE CONTRACT'S POINT. C5 caps a column at 20k values, and a cap the
* caller cannot see is a silent wrong answer: a 30k-row file would report ten thousand
* records "not found" that are simply past the cap. The dialog surfaces this flag as its
* own sentence, never folded into the miss count ([[no-unverifiable-aggregates]]).
*/
export interface TabularUpload {
columns: string[];
rows: number;
values: Record<string, string[]>;
truncated: boolean;
}
export async function uploadTabular(file: File): Promise<TabularUpload | null> {
const form = new FormData();
form.append("file", file);
try {
// β NO Content-Type HEADER. The browser must set it, because only the browser knows
// the multipart boundary it generated β writing `multipart/form-data` by hand omits
// the boundary and the server cannot parse the body at all.
const res = await fetch(`${API_V1}/uploads/tabular`, {
method: "POST",
credentials: CREDENTIALS,
body: form,
});
if (handledSession(res)) return null;
const body = (await readJson(res)) as
| { columns?: unknown; rows?: unknown; values?: unknown; truncated?: unknown;
error?: { message?: string } }
| null;
if (!res.ok) {
const why = refusalMessage(
body,
res.status,
`The file could not be read (the server answered ${res.status}).`
);
signal(TOAST_EVENT, why);
return null;
}
const columns = Array.isArray(body?.columns)
? body.columns.filter((c): c is string => typeof c === "string")
: [];
const rawValues = (body?.values && typeof body.values === "object" ? body.values : {}) as
Record<string, unknown>;
const values: Record<string, string[]> = {};
for (const col of columns)
values[col] = Array.isArray(rawValues[col])
? (rawValues[col] as unknown[]).map((v) => (v === null || v === undefined ? "" : String(v)))
: [];
if (!columns.length) {
signal(TOAST_EVENT, "That file has no readable columns.");
return null;
}
return {
columns,
rows: typeof body?.rows === "number" ? body.rows : 0,
values,
truncated: body?.truncated === true,
};
} catch {
signal(DATA_ERROR_EVENT, "Cannot reach the server.");
return null;
}
}
/** C-UNDO's other half: drop a row this session just added. Same cache rule as the append. */
export async function deleteTableRow(
tableKey: string,
rid: string | number
): Promise<boolean> {
try {
const res = await fetch(
`${API_V1}/tables/${encodeURIComponent(tableKey)}/rows/${encodeURIComponent(String(rid))}`,
{ method: "DELETE", credentials: CREDENTIALS }
);
if (handledSession(res)) return false;
if (res.ok) dropTableRowsCache(tableKey);
return res.ok;
} catch {
return false;
}
}
/**
* Item 7 (contract C-TS) β `POST /api/v1/grid/timeseries`.
*
* A READ that is a POST, because the request body carries a pid list that can run to
* thousands: a URL cannot hold the caller's book, and putting customer ids in a query string
* would also put them in every access log. The server intersects those pids with the caller's
* `allowed_pids` regardless, so the body narrows the answer and can never widen it.
*
* β RETURNS `null` ON EVERY FAILURE, AND THE PANEL MUST SAY SO RATHER THAN DRAW ZEROES.
* That is the difference between this and a payload of empty buckets: "we could not ask" and
* "the answer is nothing" look identical on a chart and are not the same claim. A 400 is the
* honest "narrow the span"; a 403 is `out_of_scope` (every requested pid was outside the
* caller's book); a 401 ends the session like everywhere else.
*/
export async function fetchTimeseries(
body: TsRequest,
scope: SurfaceScope = surfaceScope
): Promise<{ payload: TsPayload | null; status: number }> {
try {
const res = await fetch(
`${API_V1}/grid/timeseries?scope=${encodeURIComponent(scope)}`,
{
method: "POST",
credentials: CREDENTIALS,
headers: JSON_HEADERS,
body: JSON.stringify(body),
}
);
if (handledSession(res)) return { payload: null, status: res.status };
if (!res.ok) return { payload: null, status: res.status };
const json = (await readJson(res)) as TsPayload | null;
// Shape-check before trusting it: `columns` and `rows` are indexed POSITIONALLY against
// each other, so a payload missing either would index into undefined all the way down.
if (!json || !Array.isArray(json.columns) || !Array.isArray(json.rows))
return { payload: null, status: res.status };
return { payload: json, status: res.status };
} catch {
return { payload: null, status: 0 };
}
}
/**
* wave17 owner item 9 / ruling R4 (contract C-CAL) β per-DAY measure values.
*
* β WHY A SECOND CHANNEL rather than a parameter on the time-series one: **every group carries
* its OWN pid set.** A calendar day holds whatever records the date field placed there, so the
* subject changes from cell to cell; one `allowed_pids` for the whole request would compute
* every day over everybody, which is a different question with the same shape.
*
* The caps are the SERVER's and it answers a 400 with its reason rather than trimming: 31 days,
* 6 fields, 186 cells. The client's job is to send no more than that, never to guess what was
* dropped. `values[field][day] === null` is UNANSWERED β a day past the tenant's today, a day
* whose pids are all outside the reader's book, or a measure that could not resolve β and the
* renderer draws "β" for all three. Never 0.
*/
export interface CalMetricsResponse {
values: Record<string, Record<string, number | null>>;
today?: string;
/** C-TSWIN at day grain: which window each metric was resolved under. */
windows?: Record<string, { kind: string; label: string }>;
dropped?: { field: string; reason: string }[];
problems?: string[];
}
export async function fetchCalendarMetrics(
body: { groups: { key: string; pids: number[] }[]; fields: string[] },
scope: SurfaceScope = surfaceScope
): Promise<{ payload: CalMetricsResponse | null; status: number }> {
try {
const res = await fetch(
`${API_V1}/grid/calendar_metrics?scope=${encodeURIComponent(scope)}`,
{
method: "POST",
credentials: CREDENTIALS,
headers: JSON_HEADERS,
body: JSON.stringify(body),
}
);
if (handledSession(res)) return { payload: null, status: res.status };
if (!res.ok) return { payload: null, status: res.status };
const json = (await readJson(res)) as CalMetricsResponse | null;
// Shape-checked before it is trusted, the `fetchTimeseries` rule: every lookup below is
// `values[field][day]`, so a payload without `values` would read `undefined` as a value and
// paint blanks that look like real "β" refusals.
if (!json || !json.values || typeof json.values !== "object")
return { payload: null, status: res.status };
return { payload: json, status: res.status };
} catch {
return { payload: null, status: 0 };
}
}
// --- the WRITE (CP-C) ------------------------------------------------------
/** Legacy export for embed consumers. Durable browser edits have no replay cap. */
export const MAX_REPLAY = 24;
/** Use the real session envelope and opaque principal stamp, never a local account label. */
async function outboxIdentity(abort: AbortSignal): Promise<OutboxIdentity | null> {
const session = writeSession;
const response = await fetch(`${API_V1}/auth/me`, { credentials: CREDENTIALS, cache: "no-store", signal: abort });
if (handledSession(response) || session !== writeSession || !response.ok) return null;
const body = await readJson(response) as { tenant?: unknown; user?: { username?: unknown } } | null;
const tenant = response.headers.get(TENANT_HEADER);
const principal = response.headers.get(PRINCIPAL_HEADER);
if (typeof body?.user?.username !== "string" || !body.user.username || !tenant || !principal
|| body.tenant !== tenant || currentTenant() !== tenant || session !== writeSession) return null;
return { tenant, principal };
}
function refusedReceipt(id: string, body: unknown, status: number, fallback: string): OutboxReceipt {
const results = (body as { results?: { id?: string }[] } | null)?.results;
const matched = Array.isArray(results) ? results.find((result) => result.id === id) : undefined;
if (matched) return refusedReceipt(id, matched, status, fallback);
const shaped = body as { reason?: unknown; refused?: { code?: unknown };
detail?: { reason?: unknown; error?: { code?: unknown }; code?: unknown } } | null;
const code = refusalCode(body) || shaped?.refused?.code || shaped?.detail?.error?.code
|| shaped?.detail?.code || shaped?.reason || shaped?.detail?.reason;
return { id, ok: false, code: typeof code === "string" ? code : "write_refused",
message: refusalMessage(body, status, fallback) };
}
/** Receipts identify outcomes. A transport error never proves a refusal was final. */
function matchingRefusal(id: string, body: unknown, status: number, grid: boolean): boolean {
if (status >= 500) return false;
const answer = body as { id?: string; opId?: string; detail?: unknown; results?: unknown[] } | null;
if (!answer) return false;
if ((grid ? answer.id : answer.opId) === id) return true;
if (answer.detail && matchingRefusal(id, answer.detail, status, grid)) return true;
return Array.isArray(answer.results) && answer.results.some((result) => matchingRefusal(id, result, status, grid));
}
/** Refresh frozen-store reads without crossing the unsent edit's session boundary. */
function refreshFrozenOutboxRefusal(receipt: OutboxReceipt): void {
if (receipt.code !== "data_input_frozen") return;
refreshCustomersCache();
signal(ROWS_STALE_EVENT);
signal(WORKSPACE_STALE_EVENT);
}
/** Both grid adapters use this transport. No caller also sends its own optimistic cell event. */
async function sendOutboxEdit(edit: StoredEdit, abort: AbortSignal): Promise<OutboxReceipt> {
if (edit.kind !== "row" && edit.kind !== "event") {
const transport = outboxTransports.get(edit.kind);
if (!transport) throw new Error("Open this edit's document to finish saving.");
return transport(edit, abort);
}
const session = writeSession;
const headers = { ...JSON_HEADERS, [TENANT_HEADER]: edit.owner.tenant,
[PRINCIPAL_HEADER]: edit.owner.principal };
const topic = topicForScope(edit.scope);
const patch = edit.payload as { pid: number; updates: Partial<Row> };
const tables = edit.kind === "row" && topic.scope.startsWith("ut_")
? await connectedTables(abort) : new Set<string>();
if (session !== writeSession || abort.aborted) throw new Error("The signed-in account changed.");
if (!tables) return refusedReceipt(edit.id, null, 0, "This database's write capabilities could not be loaded. Try again.");
const connected = tables.has(topic.key);
const event: HostEvent = edit.kind === "event" ? { ...edit.payload as HostEvent, id: edit.id }
: { id: edit.id, type: "overlay_patch", pid: patch.pid, updates: patch.updates };
const grid = edit.kind === "event" || connected;
const response = await fetch(grid ? `${API_V1}/grid/events` : `${API_V1}/${topic.rowsPath}/${patch.pid}`, {
method: grid ? "POST" : "PATCH", credentials: CREDENTIALS, headers, signal: abort,
body: JSON.stringify(grid ? { events: [event], scopeKey: edit.scope }
: { ...patch.updates, opId: edit.id }),
});
if (handledSession(response) || session !== writeSession) throw new Error("Sign in again to save this edit.");
const envelope = await readJson(response);
if (event.type === "view_op") {
const rows = (envelope as { results?: unknown[] } | null)?.results;
const body = (Array.isArray(rows) ? rows : []).find((row) =>
(row as { opId?: unknown } | null)?.opId === event.client_op_id) as {
opId: string; applied?: boolean; member?: string;
refused?: { reason?: string; member?: string; message?: string };
} | undefined;
if (body?.member !== event.member || edit.id !== event.client_op_id || response.status >= 500)
return refusedReceipt(edit.id, null, response.status, "The server did not confirm this view edit.");
if (body.refused && body.refused.member === event.member)
return { id: edit.id, ok: false, confirmedRefusal: true,
code: body.refused.reason, message: body.refused.message ?? "This view edit was refused.", result: body };
if (!response.ok || body.applied !== true)
return refusedReceipt(edit.id, null, response.status, "The server did not confirm this view edit.");
const workspaceWriteOrder = ++workspaceOrder;
workspaceWrites.set(edit.scope, workspaceWriteOrder);
wsFlights.delete(edit.scope);
wsFlights.delete(`${edit.scope}:fields`);
wsCache.delete(`${edit.scope}:fields`);
const cached = wsCache.get(edit.scope);
if (cached && (event.op !== "undo" || edit.viewPaint) && cached.ws.views.some((view) => view.id === event.view_id)) {
const paint = edit.viewPaint ?? event;
const ws = { ...cached.ws, views: cached.ws.views.map((view) => view.id === event.view_id
? { ...view, ...applyPendingOps(view, [paint]) } : view) };
workspaceReads.set(ws, workspaceWriteOrder);
wsCache.set(edit.scope, { ...cached, ws, current: true });
} else wsCache.delete(edit.scope);
applyEventResult(envelope, edit.id, true);
signal(WORKSPACE_STALE_EVENT);
return { id: edit.id, ok: true, result: body, workspaceWriteOrder };
}
if (!response.ok) return { ...refusedReceipt(edit.id, envelope, response.status, "This edit could not be saved."),
confirmedRefusal: matchingRefusal(edit.id, envelope, response.status, grid) };
type Answer = { id?: string; opId?: string; ok?: boolean; value?: unknown; updates?: unknown;
refused?: unknown; cleared?: unknown; routeSwaps?: unknown; reason?: string };
const results = (envelope as { results?: Answer[] } | null)?.results;
const body = grid ? (Array.isArray(results) ? results.find((result) => result.id === edit.id) : null)
: envelope as Answer | null;
const matches = grid ? body?.id === edit.id : body?.opId === edit.id;
if (!matches) return refusedReceipt(edit.id, null, response.status, "The server did not confirm this edit.");
const refused = Array.isArray(body?.refused) ? body.refused.length > 0 : !!body?.refused;
const failure = applyEventResult(envelope, grid ? edit.id : undefined);
if (edit.kind === "event" && event.type !== "overlay_patch") {
if (failure || refused || body?.ok === false || body?.reason)
return { ...(failure ?? refusedReceipt(edit.id, body, response.status, "This edit could not be saved.")),
confirmedRefusal: true };
if (event.type === "field_duplicate" && body?.ok === true)
return { id: edit.id, ok: true, result: body };
return { id: edit.id, ok: true };
}
const draft = edit.kind === "event" ? event as Extract<HostEvent, { type: "overlay_patch" }> : patch;
const refusalKeys = Array.isArray(body?.refused) ? body.refused.filter((key): key is string => typeof key === "string") : [];
const raw = body && "value" in body ? body.value : body?.updates;
const accepted = Object.fromEntries(raw && typeof raw === "object" && !Array.isArray(raw)
? Object.entries(raw).filter(([key, value]) => key !== "pid" && !refusalKeys.includes(key) && (value === null
|| typeof value === "string" || typeof value === "number" || typeof value === "boolean")) : []) as Partial<Row>;
const cleared = Array.isArray(body?.cleared)
? body.cleared.filter((key): key is string => typeof key === "string" && key !== "pid" && !refusalKeys.includes(key)) : [];
for (const key of cleared) accepted[key] = "";
if (failure || refused || body?.ok === false || body?.reason) {
const knownKeys = refusalKeys.length > 0;
const updates = Object.fromEntries(Object.entries(draft.updates).filter(([key]) =>
!knownKeys || refusalKeys.includes(key) || !Object.prototype.hasOwnProperty.call(accepted, key)));
const receipt = failure ?? refusedReceipt(edit.id, body, response.status, "One or more cell values could not be saved.");
if (knownKeys && Object.keys(accepted).length) {
adoptCachedRow(topic, draft.pid, accepted);
signal(ROWS_STALE_EVENT);
}
return { ...receipt, confirmedRefusal: true, retryPayload: { ...draft, updates },
cellFailures: Object.fromEntries(Object.keys(updates).map((key) => [key, receipt.message ?? "This cell could not be saved."])),
result: knownKeys ? { accepted, cleared } : undefined };
}
if (edit.kind === "event") {
if (Object.keys(accepted).length) adoptCachedRow(topic, draft.pid, accepted);
signal(ROWS_STALE_EVENT);
return { id: edit.id, ok: true, result: { accepted, cleared } };
}
const acknowledged = Object.keys(patch.updates).every((key) => Object.prototype.hasOwnProperty.call(accepted, key));
const valid = acknowledged && (!connected || (body?.ok === true && body.refused === false));
if (!valid) return refusedReceipt(edit.id, body, response.status, "The server did not confirm this edit.");
const relationsChanged = adoptCachedRow(topic, patch.pid, accepted);
if (relationsChanged) {
windowPaging.clear();
for (const key of [...rowsCache.keys()])
if (key.startsWith("tables/") || key.startsWith("odoo-tables/")) rowsCache.delete(key);
}
if (Array.isArray(body?.routeSwaps) && body.routeSwaps.length > 0) clearTopicRowsCache(topic.rowsPath);
signal(ROWS_STALE_EVENT);
return { id: edit.id, ok: true, result: { accepted, cleared } };
}
const outboxTransports = new Map<string, (edit: StoredEdit, abort: AbortSignal) => Promise<OutboxReceipt>>();
/** Sheet and notes register their receipt adapters on the same ordered outbox and save state. */
// Adapters inherit the attempt bound and must pass the signal through all I/O, including body reads.
// Adapters match wire ids. Only retryNow replaces the id of a confirmed refusal.
export function registerOutboxTransport(kind: string,
transport: (edit: StoredEdit, abort: AbortSignal) => Promise<OutboxReceipt>): () => void {
if (kind === "row" || kind === "event") throw new Error("The grid owns this outbox transport.");
outboxTransports.set(kind, transport);
return () => { if (outboxTransports.get(kind) === transport) outboxTransports.delete(kind); };
}
export const editOutbox = createEditOutbox({ identity: outboxIdentity,
send: (edit, abort) => ownWrite(() => sendOutboxEdit(edit, abort), abort) });
editOutbox.subscribe(() => signal(OUTBOX_CHANGED_EVENT, editOutbox.snapshot()));
export const CELL_NOTES_KEY = "__cell_notes__";
export const CELL_NOTE_RECEIPT_EVENT = "aios:cell-note-receipt";
export interface CellNoteChange { pid: number; field: string; text: string | null }
function objectValue(value: unknown): Record<string, unknown> | undefined {
return value !== null && typeof value === "object" && !Array.isArray(value)
? value as Record<string, unknown> : undefined;
}
/** Reserved row metadata never enters the scalar cell adoption path. */
export function cellNoteText(row: unknown, field: string): string | null {
const notes = objectValue(objectValue(row)?.[CELL_NOTES_KEY]);
const text = notes && Object.prototype.hasOwnProperty.call(notes, field) ? notes[field] : undefined;
return typeof text === "string" && text.trim() ? text : null;
}
export function withCellNote(row: Row, field: string, text: string | null): Row {
const notes = { ...objectValue(objectValue(row)?.[CELL_NOTES_KEY]) };
if (text === null) delete notes[field];
else Object.defineProperty(notes, field, { value: text, enumerable: true, configurable: true, writable: true });
// Row describes scalar cells. Only this guarded metadata seam carries the reserved map.
return { ...row, [CELL_NOTES_KEY]: notes } as unknown as Row;
}
export function readCellNoteChange(payload: unknown): CellNoteChange | null {
const value = objectValue(payload);
return value && typeof value.pid === "number" && Number.isSafeInteger(value.pid)
&& typeof value.field === "string" && !!value.field && value.field !== CELL_NOTES_KEY
&& (value.text === null || typeof value.text === "string")
? { pid: value.pid, field: value.field, text: value.text } : null;
}
export function pendingCellNotes(scope: string) {
const snapshot = editOutbox.snapshot();
return snapshot.pending.flatMap((edit) => {
if (edit.kind !== "cell-note" || !gridEditScope(edit, scope)) return [];
const change = readCellNoteChange(edit.payload);
return change ? [{ ...change, id: edit.id, failure: snapshot.failures[edit.id] }] : [];
});
}
/** C1 merges just one field note. Null explicitly deletes it without replacing sibling notes. */
export function patchCellNote(scope: string, pid: number, field: string, text: string | null): Promise<boolean> {
return editOutbox.enqueue({ id: eventId("cell-note"), kind: "cell-note", scope,
payload: { pid, field, text } });
}
async function sendCellNote(edit: StoredEdit, abort: AbortSignal): Promise<OutboxReceipt> {
const session = writeSession;
const change = readCellNoteChange(edit.payload);
if (!change) throw new Error("This cell note has an unreadable draft.");
const topic = topicForScope(edit.scope);
const { pid, field, text } = change;
const response = await fetch(`${API_V1}/${topic.rowsPath}/${pid}`, {
method: "PATCH", credentials: CREDENTIALS, signal: abort,
headers: { ...JSON_HEADERS, [TENANT_HEADER]: edit.owner.tenant, [PRINCIPAL_HEADER]: edit.owner.principal },
body: JSON.stringify({ opId: edit.id, [CELL_NOTES_KEY]: { [field]: text } }),
});
if (handledSession(response) || session !== writeSession || abort.aborted)
throw new Error("Sign in again to save this note.");
const envelope = await readJson(response);
if (session !== writeSession || abort.aborted) throw new Error("The note save was cancelled.");
const body = objectValue(envelope);
const sameIdentity = response.headers.get(TENANT_HEADER) === edit.owner.tenant
&& response.headers.get(PRINCIPAL_HEADER) === edit.owner.principal;
const matches = body?.opId === edit.id && sameIdentity;
const refused = Array.isArray(body?.refused) ? body.refused.length > 0 : !!body?.refused;
if (!response.ok || (matches && (body?.ok === false || refused || body?.reason))) {
const receipt = { ...refusedReceipt(edit.id, envelope, response.status, "This cell note could not be saved."),
confirmedRefusal: sameIdentity && matchingRefusal(edit.id, envelope, response.status, false) };
signal(TOAST_EVENT, receipt.message);
refreshFrozenOutboxRefusal(receipt);
return receipt;
}
const value = objectValue(body?.value ?? body?.updates);
const notes = objectValue(value?.[CELL_NOTES_KEY]);
const present = !!notes && Object.prototype.hasOwnProperty.call(notes, field);
if (!matches || !notes || !present || notes[field] !== text)
return refusedReceipt(edit.id, null, response.status, "The server did not confirm this cell note.");
// Replayed edits have no original callback. Reconcile caches and mounted rows in the adapter.
for (const [path, cached] of rowsCache) {
const prefixes = [topic.rowsPath, `tables/${topic.key}/rows`, `odoo-tables/${topic.key}/rows`];
if (!prefixes.some((prefix) => path === prefix || path.startsWith(`${prefix}?`))) continue;
cached.payload = { ...cached.payload, rows: cached.payload.rows.map((row) =>
row.pid === pid ? withCellNote(row, field, text) : row) };
}
rowVersions.set(topic.key, (rowVersions.get(topic.key) ?? 0) + 1);
signal(CELL_NOTE_RECEIPT_EVENT, { scope: topic.scope, ...change });
signal(ROWS_STALE_EVENT);
return { id: edit.id, ok: true, result: change };
}
registerOutboxTransport("cell-note", sendCellNote);
/** Restore only this authenticated owner's unsent cell changes for the mounted grid. */
export function gridEditScope(edit: OutboxEdit, scope: string): boolean {
return (edit.kind === "row" || edit.kind === "event" || edit.kind === "cell-note")
&& topicForScope(edit.scope).scope === topicForScope(scope).scope;
}
export interface PendingCellEdit {
id: string;
kind: string;
scope: string;
failure?: OutboxFailure;
pid: number;
updates: Partial<Row>;
}
export function pendingCellEdits(scope: string): PendingCellEdit[] {
const snapshot = editOutbox.snapshot();
return snapshot.pending.flatMap((edit) => {
if (!gridEditScope(edit, scope)) return [];
const evidence = { id: edit.id, kind: edit.kind, scope: edit.scope, failure: snapshot.failures[edit.id] };
if (edit.kind === "row") return [{ ...edit.payload as { pid: number; updates: Partial<Row> }, ...evidence }];
const event = edit.payload as HostEvent;
return edit.kind === "event" && event.type === "overlay_patch"
? [{ pid: event.pid, updates: event.updates, ...evidence }] : [];
});
}
/**
* Foreground surface identity for legacy shell/read consumers. W60-T27 removes it from
* event stamping: emitHostEvent takes a scope captured by the emitting grid instance.
*
* β The server refuses an unknown value rather than defaulting it, so this is
* never a free-text field. Read and write must agree on what a scope is: the
* grid asks `/workspace?scope=X` and every event it then emits says `X`.
*/
export type SurfaceScope = "customer" | "cohort" | "product" | `ut_${string}`;
let surfaceScope: SurfaceScope = "customer";
export function setSurfaceScope(scope: SurfaceScope): void {
surfaceScope = scope;
}
/**
* β 2026-08-14 (owner item 2) β WHAT THE MOUNTED GRID IS ACTUALLY DRAWING.
*
* β ADDED BECAUSE THE FRAME USED TO DERIVE THIS FROM THE HASH, AND THE HASH STOPPED BEING
* ABLE TO ANSWER. `Shell.tsx`'s alert-create handler read `window.location.hash` and mapped
* it (`product_data` β `product`, `ut_*` β itself, else `customer`) β correct while every
* grid lived at a route named after its database. The Query module is a grid at `#/query`,
* so that derivation would have filed every alert raised there against the CUSTOMER topic:
* a silently wrong write, on a door that answers 200.
*
* This reports the foreground grid only. A nested grid never binds it, and no event writer
* reads it. Each event carries the scope of the instance that created its callback.
*/
export function currentSurfaceScope(): SurfaceScope {
return surfaceScope;
}
/** For the gate: the queue is module state and a test needs a known start. */
export function _resetQueue(): void {
editOutbox.sessionBoundary();
for (const timer of viewSelectTimers.values()) clearTimeout(timer);
viewSelectTimers.clear();
viewSelects.clear();
}
export function _pendingIds(): string[] {
return editOutbox.snapshot().pending.map((edit) => edit.id);
}
/** Structural events and cell patches share one persisted order, including across reloads. */
async function drain(): Promise<void> {
await editOutbox.flush();
}
/** Return the matching event refusal before publishing stale notifications. */
function applyEventResult(body: unknown, operationId?: string, quiet = false): OutboxReceipt | undefined {
const b = body as {
toast?: unknown; rerender?: unknown; results?: unknown; derived?: unknown;
} | null;
const results = Array.isArray(b?.results)
? (b.results as { id?: string; rerender?: unknown; refused?: unknown; ok?: boolean; reason?: string }[]) : [];
const refusal = operationId ? results.find((result) => result.id === operationId
&& ((Array.isArray(result.refused) ? result.refused.length > 0 : !!result.refused)
|| result.ok === false || !!result.reason)) : undefined;
if (refusal) return refusedReceipt(operationId!, refusal, 200, "One or more cell values could not be saved.");
const toast = b?.toast;
if (!quiet && typeof toast === "string" && toast.trim() !== "") signal(TOAST_EVENT, toast.trim());
// owner item 2 β a measure column's values, computed server-side right after the write and
// returned here rather than waiting for the `/workspace` re-read below. Raised BEFORE the
// stale signal so the numbers paint on the earlier of the two, whichever the server sent.
// Shape-checked, because a shortcut that corrupts rows is worse than no shortcut.
if (b?.derived && typeof b.derived === "object" && !Array.isArray(b.derived)) {
// A broadcast has no parent pin. Re-read every receiver through its own rows door.
// Non-metric derived cells still arrive through the workspace refresh below.
rowsCache.clear();
windowPaging.clear();
signal(ROWS_STALE_EVENT);
}
// The server already tells us when a write changed durable state β `rerender`
// is exactly the flag the Streamlit adapter uses to trigger its own rerun. We
// were dropping it, which is why cohort membership, list adds and folder moves
// never appeared in standalone until a manual reload.
if (b?.rerender === true || results.some((r) => r?.rerender === true)) {
signal(WORKSPACE_STALE_EVENT);
}
}
// S85-T26: `view_select` records the open view. It leaves on its own path, never behind queued
// saves, only the last click of a burst is sent, and it is never stored in the browser.
/** Clicks inside this window collapse into one `view_select`. */
export const VIEW_SELECT_SETTLE_MS = 250;
const viewSelects = new Map<string, { event: HostEvent; session: number }>();
const viewSelectTimers = new Map<string, ReturnType<typeof setTimeout>>();
const viewSelectFlights = new Map<string, Promise<void>>();
function queueViewSelect(event: HostEvent, scope: SurfaceScope): void {
viewSelects.set(scope, { event, session: writeSession });
const timer = viewSelectTimers.get(scope);
if (timer !== undefined) clearTimeout(timer);
viewSelectTimers.set(scope, setTimeout(() => {
viewSelectTimers.delete(scope);
void sendViewSelect(scope);
}, VIEW_SELECT_SETTLE_MS));
}
async function sendViewSelect(scope: string, keepalive = false): Promise<void> {
// One request per scope at a time. A click made during it is sent after it.
const flight = viewSelectFlights.get(scope);
if (flight && !keepalive) {
await flight;
if (viewSelectTimers.has(scope)) return;
}
const latest = viewSelects.get(scope);
if (!latest) return;
viewSelects.delete(scope);
if (latest.session !== writeSession) return;
const tenant = currentTenant();
const task = ownWrite(async () => {
try {
const response = await fetch(`${API_V1}/grid/events`, {
method: "POST", credentials: CREDENTIALS, keepalive,
headers: { ...JSON_HEADERS, ...(tenant ? { [TENANT_HEADER]: tenant } : {}) },
body: JSON.stringify({ events: [latest.event], scopeKey: scope }),
});
handledSession(response);
} catch {
// The view is already on screen. A lost choice only changes where a new browser opens.
}
});
viewSelectFlights.set(scope, task);
try {
await task;
} finally {
if (viewSelectFlights.get(scope) === task) viewSelectFlights.delete(scope);
}
}
/** Send every waiting view choice now, because the page is going away. */
function flushViewSelects(): void {
for (const [scope, timer] of [...viewSelectTimers]) {
clearTimeout(timer);
viewSelectTimers.delete(scope);
void sendViewSelect(scope, true);
}
}
/** The sink hostBridge falls through to in standalone. Returns true: the event
* is now OURS (queued and owned), which is all the caller ever needed. */
function standaloneSink(event: HostEvent, scope: SurfaceScope): boolean {
if (event.type === "view_select") {
queueViewSelect(event, scope);
return true;
}
void editOutbox.enqueue({ id: event.id, kind: "event", scope, payload: event }, (receipt) => {
if (event.type !== "view_op" && !receipt.ok && receipt.message) signal(TOAST_EVENT, receipt.message);
if (!receipt.ok) refreshFrozenOutboxRefusal(receipt);
});
return true;
}
/** Called from main.tsx in standalone ONLY. Never in the embed β that is the
* whole of "standalone-only branches", enforced at the one wiring point. */
export function installStandaloneBridge(): void {
setStandaloneSink(standaloneSink);
if (!outboxListenersBound && typeof window !== "undefined") {
outboxListenersBound = true;
window.addEventListener("beforeunload", editOutbox.beforeUnload);
window.addEventListener("online", () => { void drain(); });
window.addEventListener("pagehide", flushViewSelects);
}
void editOutbox.start();
}
let outboxListenersBound = false;
/**
* ββ WAVE 34 (owner ruling R13, `W34-T54`) β RUN AN `ai_enrich` COLUMN OVER A SCOPE.
*
* `POST /api/v1/tables/{key}/fields/{fkey}/enrich`, body `{scope: "blank" | "always"}`.
* `blank` fills only cells nothing has written; `always` re-runs every row.
*
* β ADDED BY THE INTEGRATOR AT CLOSE-OUT, and the reason is worth stating rather than burying.
* Lane F built the server door, the menu row and the field kind, and left the host call site as an
* OPTIONAL prop with the note *"nothing breaks if you decline"*. That is true of the BUILD and
* false of the FEATURE: this is the only path that makes the bulk run reachable, and `W34-T54`'s
* own `done-when` reads *"the bulk menu offers at least all rows and rows never filled"*. Left
* unwired, that ticket would have been BUILT with its acceptance test unreachable β the exact
* shape this repo has shipped five times ([[mounted-is-not-callable]]).
*
* β IT SPENDS MONEY, so it reports rather than returns a boolean. The server answers a RUN REPORT
* (`filled`, `failed`, `skipped` by reason, `tokens`, `limit`) and the caller shows the sentence:
* a bulk enrichment that quietly did 3 of 900 rows because a ceiling bit is precisely the silent
* cap R6's standing rule forbids, and a `true` would hide it.
*/
export async function enrichField(
tableKey: string,
fieldKey: string,
scope: "blank" | "always"
): Promise<EnrichReport | null> {
try {
const res = await fetch(
`${API_V1}/tables/${encodeURIComponent(tableKey)}/fields/${encodeURIComponent(fieldKey)}/enrich`,
{
method: "POST",
credentials: CREDENTIALS,
headers: JSON_HEADERS,
body: JSON.stringify({ scope }),
}
);
if (handledSession(res)) return null;
const body = (await readJson(res)) as (EnrichReport & { error?: { message?: string } }) | null;
if (!res.ok) {
// The server states WHY (no key, a token ceiling, a locked column). Its sentence beats ours.
signal(TOAST_EVENT, refusalMessage(body, res.status));
return null;
}
return body ?? null;
} catch {
signal(DATA_ERROR_EVENT, "The enrichment run could not be reached. Nothing was changed.");
return null;
}
}
/** What `POST .../enrich` answers. Shapes the sentence the caller shows. */
export type EnrichReport = {
filled?: number;
failed?: number;
skipped?: Record<string, number>;
tokens?: number;
limit?: number;
};
// ---------------------------------------------------------------------------
// customer-grid / apiBridge.ts β the STANDALONE half of the data path (X2).
//
// The branch beside hostBridge.ts. Where `hostBridge` speaks the Streamlit
// Components v1 protocol to a surrounding Python app, this speaks HTTP to the
// API β the SAME event objects, the same ids, the same optimism semantics on
// the client. Which one is live is decided once, by mode, and never mixed:
// `installStandaloneBridge()` is called from main.tsx ONLY in standalone, so
// the embed bundle never registers a sink and its behaviour is byte-unchanged
// (pinned by verify_bridge.py, which was written BEFORE this file existed).
//
// β WHAT THIS WAVE'S WRITE PATH CAN AND CANNOT DO β read before extending.
// The client's whole write model is "emit β the host reruns β a fresh payload
// arrives β the UI reflects it" (CustomerGrid's own words: *"the emit itself
// triggers the host rerun, so the fresh name/list arrives with the next payload
// β no local mutation to drift from the store"*). Standalone has no rerun and
// X2 fixes `GET /api/v1/customers` at the EXACT current shape β `{fields, rows,
// today, pulled_at}`, with no `workspace`, no `cohorts`, no `docs`. So:
//
// VISIBLE + DURABLE view_upsert Β· view_delete Β· field_* Β· overlay_patch
// (the client already holds these in state + localStorage;
// the POST is what makes them durable server-side)
// DURABLE, INVISIBLE cohort_* Β· add_to_list Β· folder_* Β· item_move
// (they reach the store, but nothing re-reads them until
// the payload carries that state β EXIT-5). The server's
// `toast` is the only feedback the user gets, which is
// why it is wired through and not dropped.
// NOT REACHABLE doc_add / doc_fetch / doc_delete β the Documents panel
// is driven by `payload.docs`, which standalone never
// receives, so no doc event can be emitted at all. X2's
// `doc` field is therefore deliberately NOT handled here:
// wiring a response nobody can trigger is untestable dead
// code. When `/customers` grows `docs`, feed `doc` into
// the same `payload.docPayload` slot the embed uses.
//
// NOTHING HERE FALLS BACK TO `sample_customers.json`. That affordance ("the
// grid still renders with no backend") is unreachable now β the frame requires
// a session before CustomerGrid mounts at all β and behind a login, sample
// revenue rendered after a server hiccup is fabricated data on a screen the
// user has every reason to trust. An honest failure, always.
// ---------------------------------------------------------------------------
import {
API_V1,
CREDENTIALS,
DATA_ERROR_EVENT,
ROWS_STALE_EVENT,
TOAST_EVENT,
WORKSPACE_STALE_EVENT,
UNAUTHORIZED_EVENT,
checkTenant,
currentTenant,
PRINCIPAL_HEADER,
TENANT_HEADER,
signal,
} from "../apiContract";
import { createEditOutbox, OUTBOX_CHANGED_EVENT } from "./editOutbox";
import type { OutboxEdit, OutboxFailure, OutboxIdentity, OutboxReceipt, StoredEdit } from "./editOutbox";
import { applyPendingOps } from "./viewOps";
import { ROWS_CHUNK } from "./pipelineWorker";
import type { RowsReply, RowsRequest } from "./pipelineWorker";
import { eventId, setStandaloneSink } from "./hostBridge";
import { changedBuckets } from "./liveWorkspace";
import type { ChangeTokens } from "./liveWorkspace";
import { CUSTOMER_TOPIC, relatedEntries, relatedRefusals, topicForScope } from "./types";
import type { CustomersPayload, Field, FilterNode, GridLimit, GridWorkspace, HostEvent,
RelatedEntry, RelatedPin, RelatedRefusal, Row, SortSpec, TopicConfig, ViewConfig } from "./types";
import type { TsPayload, TsRequest } from "./timeSeriesData";
import { AMAZON_STILL_LOADING_MESSAGE, MIRROR_RETRY_DELAYS, isMirrorNotLoaded,
waitForMirror } from "./mirrorLoading";
import { FIRST_ANSWER_DEADLINE_MS, READ_DEADLINE_MS, WORKSPACE_DEADLINE_MS, armDeadline, fetchWithDeadline,
isReadTimeout } from "../net/deadline";
const JSON_HEADERS = { "Content-Type": "application/json" };
/** R8 layout vocabulary. Membership, row values and schema never ride this door. */
export type PersonalGridLayout = Pick<ViewConfig,
"order" | "visible" | "widths" | "sorts" | "filters" | "filterConj" | "groupBy">;
export function personalGridLayout(config: ViewConfig): PersonalGridLayout {
return {
order: config.order, visible: config.visible, widths: config.widths,
sorts: config.sorts, filters: config.filters, filterConj: config.filterConj ?? "and",
groupBy: config.groupBy,
};
}
// Only outstanding writes live here, never a user's cached prefs. Remounts await the write
// before GET; a tab switch cannot cancel it or hydrate from the server's pre-save snapshot.
const personalLayoutWrites = new Map<string, {
next: PersonalGridLayout | null;
task: Promise<boolean>;
}>();
export function savePersonalGridLayout(key: string, layout: PersonalGridLayout): Promise<boolean> {
const pending = personalLayoutWrites.get(key);
if (pending) {
pending.next = layout;
return pending.task;
}