Spaces:
Running on CPU Upgrade
Running on CPU Upgrade
Download web/src/shell/nav.ts from fsanyoto/runloopable: direct link, hf CLI and curl.
- Browser
- Download file 79.7 kB
-
https://huggingface.co/spaces/fsanyoto/runloopable/resolve/main/web/src/shell/nav.ts
- Command line
-
hf download hf://spaces/fsanyoto/runloopable/web/src/shell/nav.ts
-
curl -L -o nav.ts https://huggingface.co/spaces/fsanyoto/runloopable/resolve/main/web/src/shell/nav.ts
79.7 kB
// ---------------------------------------------------------------------------
// shell/nav.ts β X6: the shell's nav, shaped from `GET /api/v1/nav`.
//
// WHAT CHANGED, AND WHY IT MATTERS MORE THAN IT LOOKS. The wave-4 nav was a
// STATIC array in Shell.tsx β a hand-kept mirror of `core/registry.py` that
// nobody's build would notice going stale, and that showed every surface to
// everybody. It is now rendered from a SERVER-FILTERED payload: the API applies
// `may_open` (incl. `_LEGACY_KEYS` migration-on-read) and drops archived
// modules, so what a user sees IS what the server granted. Registry-driven at
// one end, permission-filtered at the other.
//
// β THERE IS NO CLIENT-SIDE FALLBACK LIST, deliberately. If `/api/v1/nav`
// fails or answers with a malformed envelope, the shell renders a bounded retry
// state, never a hard-coded list. A fallback would put surfaces on screen that
// the server never authorised, which is precisely the fail-closed rule the wave
// is built on ("an undeclared surface is denied"), and it would mask a broken API
// as a working one.
//
// No `import.meta` here either: `appBase` is a PARAMETER so this module
// compiles and runs under node in `verify_login.py` (see session.ts).
// ---------------------------------------------------------------------------
import { API_V1, CREDENTIALS, UNAUTHORIZED_EVENT, checkTenant, signal } from "../apiContract";
import { APP_PATH_PREFIX, canonicalDataHash, decodeDataFilters } from "../customer-grid/dataPath";
import type { DataPath } from "../customer-grid/dataPath";
// β WAVE 19 R8 / C1 β the icon vocabulary is the GRID's, imported not redefined.
// A VALUE import (not type-only) because the whitelist has to exist at runtime:
// `FolderMark` indexes `FOLDER_SHAPE_PATHS[shape]` and maps the result, so one
// unrecognised shape off the wire is `undefined.map` β a white screen, from a
// stored preference. `customer-grid/types` imports only `./windows`, which
// imports nothing, so this stays runnable under plain node (verify_login
// compiles this module and executes it there β see the header note on
// `appBase` being a parameter for exactly that reason).
import { FOLDER_SHAPES, FOLDER_TONES } from "../customer-grid/types";
import type { FolderIcon } from "../customer-grid/types";
/** One entry of X2's nav payload. `source` is the registry's connector fact
* (wave-9 I8: "Sales Β· Odoo"); `parent` names a sub-module's family head. */
export interface NavPage {
key: string;
label: string;
/** C1's injected system-table descriptor. The client displays it but never offers generic mutation. */
managedBy?: "loopable";
protected?: boolean;
source?: string;
/** Authoritative Data-rail grouping label (for example Odoo or Custom). */
sourceGroup?: string;
group?: string;
sync?: { at: string | null; empty: boolean | null };
parent?: string;
/**
* The registry's `group_only`: this key names a FOLDER, never a destination
* (`customers` is the only one today β the head of customer_data + cohort).
*
* β ADDED BY S1 2026-07-30, additive, present only when true. It supersedes
* the client's has-children DERIVATION, which stays as the fallback for a
* payload that predates the flag: the registry knows this fact, and a client
* re-deriving a fact the server holds is drift waiting to happen.
*/
group_only?: boolean;
/**
* `core.perms.nav_pages`' placement flag: `'main'` is the module list,
* `'utility'` is a live surface the HOST renders outside it (Analyst,
* Settings, the Metric Dictionary). The payload has carried it since X6;
* rendering utility rows in the main list was this client's own gap β
* `nav_pages`' docstring says "the client places them where the host does".
*/
chrome?: "main" | "utility";
/**
* WAVE 19 R8 / C1 β the mark this database wears, from the tenant-wide
* `nav_meta` bucket. Absent β the default cylinder, which is every database
* that has never been given one.
*
* β TENANT-WIDE, not per-user, and that is the whole difference between this
* and `nav_prefs` two fields down. Folders and placement are one person's
* arrangement of their own rail; an icon and a name are what the DATABASE is
* called, and a workspace where two people call the same table different
* things has no shared vocabulary to hold a conversation in.
*/
icon?: FolderIcon;
/**
* WAVE 19 R14 β may THIS session change this row's icon (and, for a `ut_` key,
* its name)? The SERVER answers, because it is the only end that can: the
* client cannot see who created a user table.
*
* β FAIL-CLOSED BY ABSENCE, like every other flag on this payload. A row that
* does not say `manage: true` offers no rename and no icon picker β and the
* route re-checks regardless, so this is the courtesy half of "the client
* hides, the server forbids", never the wall.
*/
manage?: boolean;
/**
* WAVE 21 item 6 (ruling R3, contract C3) β may THIS session DELETE this
* database?
*
* β A SEPARATE FLAG FROM `manage`, deliberately, and reusing that one would
* have been the bug. `manage` rides `user_tables.may_open` β which R14 widened
* to include everyone a table has been SHARED with (D-32, `user_tables.py:511`).
* That is the right reach for renaming and re-iconing; it is far too wide for
* a verb that destroys ten artifact families. R3 scopes delete to the CREATOR
* or a tenant admin, so the server answers a second, narrower question and
* this is where the answer lands.
*
* Absent β no, like every flag here. Connector-backed databases never carry
* it (R3: "NO delete verb for connector-backed databases β Pause stays their
* only off-switch"), so the entry is absent rather than refused.
*/
canDelete?: boolean;
/**
* β WAVE 27 item 3 (contract C9) β IS THIS A **LOCKED DATABASE**?
*
* The owner's item-4 vocabulary, and it means exactly one thing (DESIGN.md Β§4, THE THREE
* LOCKS): RECORDS cannot be added, deleted or edited β **FIELDS STILL CAN BE**. It is not
* "read-only", and a UI that hid the add-field door on the strength of this flag would be a
* defect, not caution.
*
* Answered server-side from `user_tables.records_mutable`'s own condition (`routes_nav.py`),
* because the client cannot see a table's `recordMode`.
*
* β ABSENT β UNLOCKED, which is the OPPOSITE direction from `manage`/`canDelete` above and
* is deliberate: those two gate CONTROLS, so absence must deny. This one draws a HINT beside a
* name, while the real refusal is the route's 403. A store blip should cost a missing padlock,
* never a control that silently disappears.
*/
locked?: boolean;
/**
* ββ WAVE 34 (ruling R1, contract C1) β HOW MANY RECORDS THIS DATABASE'S **IMPORTANT** VIEWS
* RESOLVE TO.
*
* R1 moves the mark-important number OFF the view sidebar's header and INTO the database
* navigation, and that move is what forces this onto the wire: the flyout has no grid, so the
* client cannot compute it the way `CustomerGrid::importantTotal` does.
*
* β THE THREE FIELDS ARE NOT REDUNDANT AND `partial` IS THE LOAD-BEARING ONE. `marked` counts
* VIEWS, `counted` counts RECORDS, and `partial` says at least one marked view could not be
* counted at all. `/nav` holds a rows-free projection, so a FILTERED view is uncountable there
* by construction; a sum that silently skipped those would be short by an unknown amount, which
* is exactly the silent absence `D-205` exists to end, one level up.
*
* β PER USER, never tenant-wide. Views live in a per-database bucket split by username, so the
* same database answers `{marked: 1, counted: 13}` for one account and `{marked: 0}` for
* another. Measured on tenant #0: `leadership` vs `admin` on `customer_data`.
*
* β ABSENT means "not a database, or the server could not read its views" β the second case is
* named in `degraded`, exactly like the `ut_*` merge. It does NOT mean zero: a database with
* nothing marked ships `{marked: 0, counted: 0, partial: false}`, because a key a consumer has
* to test for is a key a consumer forgets to test for.
*/
important?: NavImportant;
}
/** C1's per-database important payload. See `NavPage.important` for why all three fields exist. */
export interface NavImportant {
marked: number;
counted: number;
partial: boolean;
}
/**
* The wire's important block, validated like every other flag on this payload: prune, never
* invent. A malformed one reads as ABSENT, which renders no badge β the safe direction, because
* the alternative is a confident number derived from junk.
*/
export function parseNavImportant(raw: unknown): NavImportant | undefined {
if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
const r = raw as { marked?: unknown; counted?: unknown; partial?: unknown };
const int = (v: unknown): number | null =>
typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.floor(v) : null;
const marked = int(r.marked);
const counted = int(r.counted);
if (marked === null || counted === null) return undefined;
// `=== true`, the same strictness `manage`/`canDelete`/`locked` use: a drifted server sending a
// truthy string must not turn a real count into a `+`.
return { marked, counted, partial: r.partial === true };
}
/**
* ββ THE BADGE TEXT, AND IT IS ONE FUNCTION BECAUSE THERE ARE TWO CALLERS.
*
* A database row and a COLLAPSED FOLDER both draw this number, from different inputs (one entry's
* block, a sum over a folder's members). Two renderers deciding "is there a number here" by their
* own rules is [[one-question-two-normalizers]] with the answer on screen, so the rule lives here
* and both call it.
*
* The four cases, and the third is the one the ticket calls out by name:
* Β· nothing marked -> `null`. R1's own clause: NOT a zero. Most databases are this.
* Β· a real count -> the number, plus `+` when at least one view could not be counted.
* Β· nothing countable -> `"+"` ALONE. β NEVER `"0+"`: that string is `D-205` itself, the
* thing the owner photographed, and rendering it here would be the
* same defect moved into the nav. A bare `+` says "there is something
* here we could not count" without claiming the something is zero.
* Β· a genuine zero -> `"0"`. A marked view that matches no records is a fact worth
* seeing, and it is distinguishable from the case above because
* nothing was skipped.
*/
export function importantBadge(imp?: NavImportant): string | null {
if (!imp || imp.marked <= 0) return null;
if (imp.counted > 0) return `${imp.counted}${imp.partial ? "+" : ""}`;
return imp.partial ? "+" : "0";
}
/**
* The wire's icon, validated against the vocabulary the renderer can actually
* draw. Anything unrecognised reads as ABSENT (the default mark) rather than as
* an error: a stored preference is not worth a broken rail, and the server
* applies the same whitelist on the way in, so a mismatch here means the two
* ends have drifted β which shows up as an icon quietly reverting, the loudest
* safe symptom available.
*/
export function parseNavIcon(raw: unknown): FolderIcon | undefined {
if (!raw || typeof raw !== "object" || Array.isArray(raw)) return undefined;
const r = raw as { shape?: unknown; tone?: unknown };
if (!(FOLDER_SHAPES as readonly string[]).includes(String(r.shape))) return undefined;
if (!(FOLDER_TONES as readonly string[]).includes(String(r.tone))) return undefined;
return { shape: r.shape as FolderIcon["shape"], tone: r.tone as FolderIcon["tone"] };
}
/**
* WAVE 20 item 4 (R8) β the class list for the universal database header's icon
* chip: `shell-db-chip`, plus a tone modifier when the database wears a mark.
*
* R8 asks for "an icon chip on a bold colour background on EVERY database", and
* that sentence hides a decision the JSX would otherwise bury: what colour does a
* database that never chose one get? Three cases, and they are here rather than
* inline so a gate can hold them (and so the answer is written once, not once per
* render branch):
*
* Β· no icon at all β every built-in and every un-styled table β takes the BASE
* chip, which the stylesheet paints in the brand primary. That is the
* "sensible default where unset" the ruling asks for, and it is why the base
* class carries a colour instead of leaving the chip transparent.
* Β· an icon takes its own TONE at the bold `-deep` weight, so the header agrees
* with the mark the same database wears in the rail.
* Β· an UNRECOGNISED tone falls back to the base, never `--unknown`: emitting a
* class no stylesheet defines would paint a chip with no background at all,
* and a white glyph on white is an invisible header. Same fail-safe posture
* as `parseNavIcon` above β a drifted vocabulary reverts to the default mark
* rather than breaking the frame.
*/
export function dbChipClass(icon?: FolderIcon): string {
const base = "shell-db-chip";
const tone = icon?.tone;
if (!tone || !(FOLDER_TONES as readonly string[]).includes(tone)) return base;
return `${base} ${base}--${tone}`;
}
/**
* Read X2's `{pages:[β¦]}`. An entry with no key or no label is DROPPED rather
* than rendered: a nav row with no name is a door with no sign on it, and
* guessing the sign from the key would put an internal identifier in the UI.
*/
/** S78-T02: a nav row's sync stamp, `at` a string or null and `empty` a boolean or null. */
function isNavSync(value: unknown): value is { at: string | null; empty: boolean | null } {
if (!value || typeof value !== "object") return false;
const v = value as Record<string, unknown>;
return (typeof v.at === "string" || v.at === null) &&
(typeof v.empty === "boolean" || v.empty === null);
}
export function parsePages(body: unknown): NavPage[] {
const raw = (body as { pages?: unknown } | null)?.pages;
if (!Array.isArray(raw)) return [];
const out: NavPage[] = [];
for (const item of raw) {
if (!item || typeof item !== "object") continue;
const p = item as Record<string, unknown>;
const key = typeof p.key === "string" ? p.key.trim() : "";
const label = typeof p.label === "string" ? p.label.trim() : "";
if (!key || !label) continue;
out.push({
key,
label,
...(typeof p.source === "string" && p.source ? { source: p.source } : {}),
...(typeof p.sourceGroup === "string" && p.sourceGroup.trim()
? { sourceGroup: p.sourceGroup.trim() }
: {}),
...(typeof p.group === "string" && p.group.trim() ? { group: p.group.trim() } : {}),
...(isNavSync(p.sync) ? { sync: { at: p.sync.at, empty: p.sync.empty } } : {}),
...(typeof p.parent === "string" && p.parent ? { parent: p.parent } : {}),
...(p.managedBy === "loopable" ? { managedBy: "loopable" as const } : {}),
...(p.protected === true ? { protected: true } : {}),
...(p.group_only === true ? { group_only: true } : {}),
...(p.chrome === "main" || p.chrome === "utility" ? { chrome: p.chrome } : {}),
...(parseNavIcon(p.icon) ? { icon: parseNavIcon(p.icon)! } : {}),
...(p.manage === true ? { manage: true } : {}),
// C3 (W-5): read with the same `=== true` strictness as `manage` β a
// truthy-but-not-true value from a drifted server must not open a delete.
...(p.canDelete === true ? { canDelete: true } : {}),
// β WAVE 27 item 3 / C9 β same `=== true` strictness. A locked database is a padlock
// beside a name, so a drifted server sending a truthy string must not paint one.
...(p.locked === true ? { locked: true } : {}),
// ββ WAVE 34 R1 / C1 β the important block, validated on the way in like the icon.
...(parseNavImportant(p.important) ? { important: parseNavImportant(p.important)! } : {}),
});
}
return out;
}
/**
* Split the payload by placement. `main` feeds `shapeNav`; `utility` rows are
* placed where the host places them (the Analyst slot above the list, the rest
* behind the account menu). An absent flag reads as `main` β a payload that
* predates the flag keeps today's behaviour rather than losing rows.
*/
export function splitChrome(pages: NavPage[]): { main: NavPage[]; utility: NavPage[] } {
const main: NavPage[] = [];
const utility: NavPage[] = [];
for (const p of pages) (p.chrome === "utility" ? utility : main).push(p);
return { main, utility };
}
/**
* WAVE 23 (C10 / R7) β one entry of the Home landing's recents.
*
* `at` is EPOCH SECONDS, and the type says so because the alternative bit this product once:
* a formatted naive-local stamp read by a browser in another zone (D-18). An integer instant
* has one reading everywhere, and the two things Home renders from it β "Opened N minutes ago"
* and the Today / Past 7 days / Older bucket β are both statements about THE READER'S OWN
* CLOCK, which is the one case where using it is correct rather than forbidden (contrast
* `alertsModel.stampText`, which must NOT touch a clock because it re-states a server event).
*/
export interface Recent {
key: string;
at: number;
}
/** `empty` (wave 18): the SERVER's reason for an empty page list. `"no_databases"` means a
* freshly provisioned tenant with no modules and no databases YET β a legitimate starting
* state, not a broken account. Absent means "no reason given", which the shell reads as the
* misconfigured-account case it always did. Distinguishing them is what stops the rail saying
* "no surfaces are available" beside a hero saying "welcome, create your first database". */
export type NavResult =
| {
ok: true;
pages: NavPage[];
recents: Recent[];
empty?: string;
/**
* β W31-T11 (owner item 6b) β REGISTRY KEYS THIS WORKSPACE'S CATALOGUE DOES NOT INCLUDE.
*
* A DELIBERATE absence. Every provisioned tenant carries a restricted `modules` list
* (`gtmlab`/`loopable`/`nurilab` are all `['analyst','automation']`), so this is normal and
* the rail draws nothing for these keys β as it always has. The value of naming them is
* that it makes the OTHER absence distinguishable.
*/
omitted?: string[];
/**
* β W31-T11 β PARTS OF THIS PAYLOAD THE SERVER COULD NOT READ.
*
* `["databases"]` means the `ut_*` merge raised and every database is missing from a
* **200 OK**. Before this the two absences were identical on the wire and the shell
* rendered `null` for both β which is pixel-identical to still-loading, with no timeout on
* `fetchNav` at all. That is the owner's *"Connectors and Automation still disappear"*
* report: not a permission bug, an unmarked failure.
*/
degraded?: string[];
}
| { ok: false; status: number };
/**
* A conditional module's settled rail state. `absent` means the server completed
* navigation and did not grant or provide that module; it is intentionally not
* a visual placeholder. `unavailable` remains visible because the navigation
* response is incomplete and silence would falsely claim the module is absent.
*/
export type RailSlot = "row" | "unavailable" | "absent";
/**
* Whether a conditional rail section has any visible module row. This is kept
* beside the nav contract so layout can decide from settled slot state before
* it renders separators; a known-absent module must not reserve rail geometry.
*/
export function hasVisibleRailSlot(slots: ReadonlyArray<RailSlot>): boolean {
return slots.some((slot) => slot !== "absent");
}
/**
* How long the shell waits for `/nav` before calling it unavailable.
*
* β THE POINT IS NOT SPEED, IT IS THAT `phase:"loading"` CAN END. `fetchNav` had no
* `AbortSignal`, no deadline and no retry, so a request that never resolved left a rail that
* looked *almost* complete β the four static rows plus a spinner β for ever, and the owner read
* that screen as modules disappearing. **20 seconds is chosen to sit ABOVE the measured worst
* case, not near it**: `/nav` measured a 9.5β14.0 s band on tenant #0 before W31-T10, so a
* shorter deadline would have converted a slow success into a manufactured failure. It is a
* backstop for "never", not a performance budget.
*/
export const NAV_TIMEOUT_MS = 20_000;
/** Initial request plus two quiet retries before the shell offers manual recovery. */
export const NAV_ATTEMPTS = 3;
export const NAV_RETRY_DELAYS_MS = [1000, 3000];
/** Our encoding for "the deadline passed", distinct from 0 (transport) and any HTTP status. */
export const NAV_TIMEOUT_STATUS = -1;
/** Our encoding for "the server answered, but not with a readable navigation envelope". */
export const NAV_MALFORMED_STATUS = -2;
/** Record one timed-out attempt without letting telemetry interrupt navigation recovery. */
export function reportNavTimeout(elapsedMs: number, attempt: number): void {
try {
const message = "nav_timeout " + JSON.stringify({ elapsed_ms: Math.round(elapsedMs), attempt });
void fetch(`${API_V1}/client-error`, {
method: "POST",
credentials: CREDENTIALS,
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ message, componentStack: "" }),
}).catch(() => undefined);
} catch {
// Navigation recovery must survive a failed reporter too.
}
}
/**
* A readable nav envelope has a pages list whose every destination carries a nonblank key and
* label. Optional decoration on a valid destination may still be pruned by `parsePages`, but a
* malformed destination cannot disappear into a confident partial rail. An empty list remains
* valid because a newly provisioned tenant can legitimately have no destinations yet.
*/
export function isReadableNavEnvelope(body: unknown): boolean {
if (!body || typeof body !== "object" || Array.isArray(body)) return false;
const raw = (body as { pages?: unknown }).pages;
if (!Array.isArray(raw)) return false;
return raw.every((item) => {
if (!item || typeof item !== "object" || Array.isArray(item)) return false;
const page = item as { key?: unknown; label?: unknown };
return typeof page.key === "string" && !!page.key.trim()
&& typeof page.label === "string" && !!page.label.trim();
});
}
/**
* `{recents:[β¦]}` β the list, fail-closed. An entry with no key or an unreadable stamp is
* DROPPED rather than rendered at the epoch, which would file it under "Older" for ever and
* put a tile on Home for something nobody opened.
*/
export function parseRecents(body: unknown): Recent[] {
const raw = (body as { recents?: unknown } | null)?.recents;
if (!Array.isArray(raw)) return [];
const out: Recent[] = [];
for (const item of raw) {
if (!item || typeof item !== "object") continue;
const r = item as Record<string, unknown>;
const key = typeof r.key === "string" ? r.key.trim() : "";
const at = typeof r.at === "number" && isFinite(r.at) ? Math.floor(r.at) : 0;
if (!key || at <= 0) continue;
out.push({ key, at });
}
return out;
}
/**
* WAVE 23 (C10) β stamp a page as opened. FIRE AND FORGET, by design.
*
* β IT RETURNS `void` AND SWALLOWS EVERYTHING. A recents stamp is the least important write in
* the product: it decorates a landing page. Nothing the user is doing may wait on it, and no
* failure of it may reach a screen β a toast saying "we could not record that you opened this
* table" is noise about a feature nobody asked for, printed over the table they successfully
* opened. The server answers 503 honestly when the store is down; this end simply does not
* care, which is the only correct posture for telemetry-shaped state.
*/
export function postOpened(key: string): void {
if (!key) return;
void fetch(`${API_V1}/nav/opened`, {
method: "POST",
credentials: CREDENTIALS,
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ key }),
}).catch(() => {});
}
/**
* X2 `GET /api/v1/nav`. `status` rides the failure so the caller can tell the
* two apart that must not be conflated: **401 means the session is gone** (drop
* to the login screen), anything else means the nav is unavailable (stay signed
* in, say so). `status: 0` is our encoding for a transport failure, as in
* session.ts.
*/
export function parseKeyList(raw: unknown): string[] {
if (!Array.isArray(raw)) return [];
const out: string[] = [];
for (const k of raw) if (typeof k === "string" && k.trim()) out.push(k.trim());
return out;
}
export async function fetchNav(timeoutMs: number = NAV_TIMEOUT_MS): Promise<NavResult> {
// β `setTimeout` + `AbortController`, not `AbortSignal.timeout` β the latter is unavailable in
// the plain-node context `verify_login.py` compiles and RUNS this module in (see the header
// note on `appBase` being a parameter for exactly that reason). A helper that throws on import
// in the gate's environment is a helper that silently stops being tested.
const ctl = typeof AbortController === "function" ? new AbortController() : null;
let timedOut = false;
let timer: ReturnType<typeof setTimeout> | null = null;
// β THE DEADLINE IS A RACE, NOT ONLY AN ABORT β and this is the shape a probe found the hour
// it was written. Aborting the request tells the TRANSPORT to stop; it does not, on its own,
// make this function's promise settle. A `fetch` that ignores its signal therefore leaves the
// caller awaiting for ever, which is precisely the state the deadline exists to end: the shell
// would sit in `phase:"loading"` exactly as it did before, with an abort controller in the
// source to prove it had been handled ([[flag-shipped-without-its-writer]]). Racing settles
// this promise whatever the transport does, and the abort still fires so the request is not
// left running behind it.
const deadline =
timeoutMs > 0
? new Promise<null>((resolve) => {
timer = setTimeout(() => {
timedOut = true;
ctl?.abort();
resolve(null);
}, timeoutMs);
})
: null;
try {
const call = fetch(`${API_V1}/nav`, {
credentials: CREDENTIALS,
...(ctl ? { signal: ctl.signal } : {}),
});
const res = deadline ? await Promise.race([call, deadline]) : await call;
if (res === null) return { ok: false, status: NAV_TIMEOUT_STATUS };
if (!res.ok) return { ok: false, status: res.status };
let body: unknown;
try {
// Headers and body share one deadline, including transports that ignore abort.
const read = res.json();
body = deadline ? await Promise.race([read, deadline]) : await read;
if (timedOut) return { ok: false, status: NAV_TIMEOUT_STATUS };
} catch (error) {
if (timedOut || (error as { name?: unknown } | null)?.name === "AbortError") {
return { ok: false, status: NAV_TIMEOUT_STATUS };
}
return { ok: false, status: NAV_MALFORMED_STATUS };
}
if (!isReadableNavEnvelope(body)) {
return { ok: false, status: NAV_MALFORMED_STATUS };
}
const envelope = body as { empty?: unknown; omitted?: unknown; degraded?: unknown };
const empty = typeof envelope.empty === "string" ? envelope.empty : undefined;
const omitted = parseKeyList(envelope.omitted);
const degraded = parseKeyList(envelope.degraded);
return {
ok: true,
pages: parsePages(body),
recents: parseRecents(body),
...(empty ? { empty } : {}),
...(omitted.length ? { omitted } : {}),
...(degraded.length ? { degraded } : {}),
};
} catch {
// The deadline has its own status so the shell can record timed-out attempts separately
// from transport failures while both take the same quiet retry path.
return { ok: false, status: timedOut ? NAV_TIMEOUT_STATUS : 0 };
} finally {
if (timer !== null) clearTimeout(timer);
}
}
// ββ C-SCHEMA (wave 2026-08-02): per-user folders over the database list βββββββββββββββββββββ
export interface NavFolder {
id: string;
name: string;
}
/** Per-user, cosmetic, server-validated β placement never grants or hides a surface. */
export interface NavPrefs {
folders: NavFolder[];
placement: Record<string, string>;
}
export const EMPTY_NAV_PREFS: NavPrefs = { folders: [], placement: {} };
export const MAX_NAV_FOLDERS = 16;
/** Mirror of the server's `_clean_nav_prefs` pruning (minus the page-key check β the client
* prunes against folders only; a stale page key is harmless and drops on the next save). */
export function parseNavPrefs(body: unknown): NavPrefs {
const raw = (body as { prefs?: unknown } | null)?.prefs ?? body;
if (!raw || typeof raw !== "object") return EMPTY_NAV_PREFS;
const p = raw as { folders?: unknown; placement?: unknown };
const folders: NavFolder[] = [];
const seen = new Set<string>();
if (Array.isArray(p.folders)) {
for (const f of p.folders.slice(0, MAX_NAV_FOLDERS)) {
if (!f || typeof f !== "object") continue;
const id = String((f as NavFolder).id ?? "").trim().slice(0, 40);
const name = String((f as NavFolder).name ?? "").trim().replace(/\s+/g, " ").slice(0, 40);
if (!id || seen.has(id) || !name) continue;
seen.add(id);
folders.push({ id, name });
}
}
const placement: Record<string, string> = {};
if (p.placement && typeof p.placement === "object") {
for (const [k, v] of Object.entries(p.placement as Record<string, unknown>)) {
const fid = String(v ?? "").slice(0, 40);
if (k && seen.has(fid)) placement[k.slice(0, 60)] = fid;
}
}
return { folders, placement };
}
export async function fetchNavPrefs(): Promise<NavPrefs> {
try {
const res = await fetch(`${API_V1}/nav/prefs`, { credentials: CREDENTIALS });
if (!res.ok) return EMPTY_NAV_PREFS;
return parseNavPrefs(await res.json());
} catch {
return EMPTY_NAV_PREFS;
}
}
/** Wholesale replace, like the table folder stratum. Resolves false on any failure so the
* caller can revert its optimistic copy and say so. */
export async function saveNavPrefs(prefs: NavPrefs): Promise<boolean> {
try {
const res = await fetch(`${API_V1}/nav/prefs`, {
method: "POST",
credentials: CREDENTIALS,
headers: { "Content-Type": "application/json" },
body: JSON.stringify(prefs),
});
return res.ok;
} catch {
return false;
}
}
// ββ WAVE 19 R8 / C1: `nav_meta` β the TENANT-WIDE name + icon overrides ββββββββββββββββββββ
/** One database's overrides. `name` is `ut_*`-only and the SERVER enforces that
* (a built-in label is a compiled registry literal); `icon` rides every key. */
export interface NavMetaPatch {
icon?: FolderIcon | null;
name?: string;
}
/**
* `POST /api/v1/nav/meta`. A PATCH of ONE key, not a wholesale replace β the
* opposite posture to `saveNavPrefs` above, and deliberately so. Prefs are one
* user's complete picture of their own rail, so replacing it whole is how a
* deleted folder stays deleted. `nav_meta` is TENANT-WIDE and every admin edits
* the same document: sending a whole picture there means the last writer erases
* whatever the previous one named while their tab was open. Explicit `null`
* clears the icon; an absent field is untouched, which is what makes a
* rename-and-an-icon two independent writes instead of a race.
*
* Resolves false on any failure so the caller reverts its optimistic copy and
* says so, rather than leaving a name on screen that the store never took.
*/
export async function saveNavMeta(key: string, patch: NavMetaPatch): Promise<boolean> {
try {
const res = await fetch(`${API_V1}/nav/meta`, {
method: "POST",
credentials: CREDENTIALS,
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ key, ...patch }),
});
return res.ok;
} catch {
return false;
}
}
// βββββββββββββββββββββββββββββ WAVE 21 item 6 (R3, contract C3): delete a database
/**
* What deleting this database would actually destroy.
*
* β EVERY FIELD IS A COUNT THE USER CAN ACT ON, which is the whole reason the
* confirm face exists. R3: "Confirm dialog discloses the footprint (rows/fields/
* views/shared users/bound automations) before DELETE." A dialog that said only
* "are you sure?" would be asking about a thing whose size nobody can see β and
* the thing that makes a user-table delete different from a view delete is that
* nine other artifact families go with it (cohorts, comments, docs + their
* dataset bytes, asset refs, grants, nav meta, alerts, automations).
*
* `automations` are NAMED, not counted, and that asymmetry is deliberate: they
* are the only footprint entry that keeps existing after the delete (C3 pauses
* them and stamps "target deleted" rather than removing them), so the user has
* to be able to go and find them.
*/
export interface TableFootprint {
rows: number;
fields: number;
views: number;
sharedUsers: number;
automations: { id: string; name: string }[];
}
const intOf = (v: unknown): number =>
typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.floor(v) : 0;
/**
* `GET /api/v1/tables/{key}/footprint` (C3, A serves).
*
* Returns null when the server would not or could not answer. The caller shows
* the confirm face WITHOUT counts in that case rather than substituting zeros:
* "0 rows" is a specific, checkable claim about the user's data, and inventing
* it to keep a dialog tidy is the fabrication this repo's counts rule forbids
* ([[no-unverifiable-aggregates]]).
*/
export async function fetchTableFootprint(key: string): Promise<TableFootprint | null> {
try {
const res = await fetch(`${API_V1}/tables/${encodeURIComponent(key)}/footprint`, {
credentials: CREDENTIALS,
});
if (!res.ok) return null;
const raw = (await res.json()) as Record<string, unknown> | null;
if (!raw || typeof raw !== "object") return null;
const autos: { id: string; name: string }[] = [];
for (const item of Array.isArray(raw.automations) ? raw.automations : []) {
if (!item || typeof item !== "object") continue;
const a = item as Record<string, unknown>;
const id = typeof a.id === "string" ? a.id : String(a.id ?? "");
const name = typeof a.name === "string" && a.name.trim() ? a.name.trim() : id;
if (id) autos.push({ id, name });
}
return {
rows: intOf(raw.rows),
fields: intOf(raw.fields),
views: intOf(raw.views),
sharedUsers: intOf(raw.sharedUsers),
automations: autos,
};
} catch {
return null;
}
}
/**
* `DELETE /api/v1/tables/{key}` (C3). The route has existed since wave 18 with
* NO client caller at all β this is that caller.
*
* Resolves the server's own message on failure so the rail can say why, and
* `true` only on a 2xx. The nav is refetched by the caller either way: a delete
* that half-succeeded server-side must not leave a row on screen whose absence
* is the only evidence anything happened.
*/
export async function deleteTable(key: string): Promise<{ ok: boolean; error?: string }> {
try {
const res = await fetch(`${API_V1}/tables/${encodeURIComponent(key)}`, {
method: "DELETE",
credentials: CREDENTIALS,
});
if (res.ok) return { ok: true };
let detail = "";
try {
const body = (await res.json()) as { detail?: unknown; error?: unknown } | null;
const d = body?.detail ?? body?.error;
if (typeof d === "string") detail = d;
} catch {
/* a non-JSON error body is not itself an error worth surfacing */
}
return { ok: false, error: detail || `The server answered ${res.status}.` };
} catch {
return { ok: false, error: "Cannot reach the server." };
}
}
/** One rendered row of the folded nav: a folder head, or an entry (optionally inside one).
*
* β `count` and `important` are DIFFERENT NUMBERS and neither is a version of the other.
* `count` is how many BLOCKS the folder holds (a top-level entry plus its depth-1 children counts
* as one), which is the number that has been drawn beside a folder name since wave 14.
* `important` is R1's aggregate over its members' record counts. Putting them in one slot would
* make a folder head say "3" and mean two different things depending on whether anything inside
* it was ever marked. */
export type NavRow =
| {
kind: "folder";
folder: NavFolder;
count: number;
open: boolean;
important?: NavImportant;
}
| { kind: "entry"; entry: NavEntry; folderId?: string };
/**
* Fold the shaped entries under the user's folders. A BLOCK (a top-level entry plus its
* depth-1 children) moves as one unit β filing a family head files the family. Folders render
* in prefs order first, loose blocks after in registry order; a folder with no members still
* renders (it was just created β it must exist on screen to receive its first member).
* A closed folder contributes only its head row.
*/
export function foldNav(
entries: NavEntry[],
prefs: NavPrefs,
closed: ReadonlySet<string>
): NavRow[] {
interface Block {
head: NavEntry;
children: NavEntry[];
}
const blocks: Block[] = [];
for (const e of entries) {
if (e.depth > 0 && blocks.length > 0) blocks[blocks.length - 1].children.push(e);
else blocks.push({ head: e, children: [] });
}
const byFolder = new Map<string, Block[]>();
const loose: Block[] = [];
const ids = new Set(prefs.folders.map((f) => f.id));
for (const b of blocks) {
const fid = prefs.placement[b.head.key];
if (fid && ids.has(fid)) {
const list = byFolder.get(fid);
if (list) list.push(b);
else byFolder.set(fid, [b]);
} else {
loose.push(b);
}
}
const out: NavRow[] = [];
const emit = (b: Block, folderId?: string) => {
out.push({ kind: "entry", entry: b.head, ...(folderId ? { folderId } : {}) });
for (const c of b.children)
out.push({ kind: "entry", entry: c, ...(folderId ? { folderId } : {}) });
};
// ββ WAVE 34 R1 / C1 β a COLLAPSED folder carries the SUM of its members' numbers.
//
// β SUMMED FROM THE SAME `members` ARRAY THAT PRODUCES `count`, in the same pass, and that is
// the whole correctness of it. The alternative β a second lookup in `Shell.tsx` keyed off
// `dbEntries` β would derive the number from one list while the rows came from another, which is
// the defect `shell.test.ts` already pins for `count` ("a folder whose only member was filtered
// out counts 0, not 1"). It bites hardest during SEARCH, when the caller passes
// `EMPTY_NAV_PREFS` and no folder renders at all.
//
// β CHILDREN CONTRIBUTE. A block is a head plus its depth-1 children, and a child is its own
// database with its own marked views, so the head's number would be short without them.
const aggregate = (blocks: Block[]): NavImportant | undefined => {
let marked = 0;
let counted = 0;
let partial = false;
for (const b of blocks) {
for (const e of [b.head, ...b.children]) {
if (!e.important) continue;
marked += e.important.marked;
counted += e.important.counted;
partial = partial || e.important.partial;
}
}
return marked > 0 ? { marked, counted, partial } : undefined;
};
for (const f of prefs.folders) {
const members = byFolder.get(f.id) ?? [];
const open = !closed.has(f.id);
// β ONLY WHEN CLOSED. An open folder shows its members' own numbers directly underneath, so a
// head number there would be the same records counted twice on one screen β the ticket's
// "an expanded one does not double-count", enforced at the source rather than in the renderer.
const imp = open ? undefined : aggregate(members);
out.push({ kind: "folder", folder: f, count: members.length, open,
...(imp ? { important: imp } : {}) });
if (open) for (const b of members) emit(b, f.id);
}
for (const b of loose) emit(b);
return out;
}
// ββ C-SCHEMA: the schema drawer payload βββββββββββββββββββββββββββββββββββββββββββββββββββββ
export interface SchemaField {
key: string;
label: string;
type: string;
source: string;
description: string;
options?: string[];
}
/** One field a database editor may use for one half of a Map coordinate pair. */
export interface SchemaMapField {
key: string;
label: string;
type: string;
}
/** Database-owned Map setup, served alongside the schema rather than a saved View. */
export interface SchemaMapSetup {
canConfigure: boolean;
fields: SchemaMapField[];
latField?: string;
lonField?: string;
/** Prerelease compatibility only; new setup saves the explicit pair above. */
coordField?: string;
}
export interface SchemaPayload {
key: string;
label: string;
source: string;
fields: SchemaField[];
measures: { key: string; label: string; type: string }[];
map: SchemaMapSetup;
note?: string;
}
function parseSchemaMap(raw: unknown): SchemaMapSetup {
const source = raw && typeof raw === "object" ? raw as Record<string, unknown> : {};
const fields: SchemaMapField[] = [];
if (Array.isArray(source.fields)) {
for (const field of source.fields) {
if (!field || typeof field !== "object") continue;
const f = field as Record<string, unknown>;
if (typeof f.key !== "string" || !f.key) continue;
fields.push({
key: f.key,
label: typeof f.label === "string" && f.label ? f.label : f.key,
type: String(f.type ?? ""),
});
}
}
return {
canConfigure: source.canConfigure === true,
fields,
...(typeof source.coordField === "string" && source.coordField
? { coordField: source.coordField }
: {}),
...(typeof source.latField === "string" && source.latField
? { latField: source.latField }
: {}),
...(typeof source.lonField === "string" && source.lonField
? { lonField: source.lonField }
: {}),
};
}
export function parseSchema(body: unknown): SchemaPayload | null {
if (!body || typeof body !== "object") return null;
const b = body as Record<string, unknown>;
if (typeof b.key !== "string" || typeof b.label !== "string") return null;
const fields: SchemaField[] = [];
if (Array.isArray(b.fields)) {
for (const f of b.fields) {
if (!f || typeof f !== "object") continue;
const r = f as Record<string, unknown>;
if (typeof r.key !== "string" || typeof r.label !== "string") continue;
fields.push({
key: r.key,
label: r.label,
type: String(r.type ?? ""),
source: String(r.source ?? ""),
description: String(r.description ?? ""),
...(Array.isArray(r.options) ? { options: r.options.map(String) } : {}),
});
}
}
const measures: SchemaPayload["measures"] = [];
if (Array.isArray(b.measures)) {
for (const m of b.measures) {
if (!m || typeof m !== "object") continue;
const r = m as Record<string, unknown>;
if (typeof r.key !== "string" || !r.key) continue;
measures.push({ key: r.key, label: String(r.label ?? r.key), type: String(r.type ?? "") });
}
}
return {
key: b.key,
label: b.label,
source: String(b.source ?? ""),
fields,
measures,
map: parseSchemaMap(b.map),
...(typeof b.note === "string" && b.note ? { note: b.note } : {}),
};
}
export async function fetchSchema(key: string): Promise<SchemaPayload | null> {
try {
const res = await fetch(`${API_V1}/nav/schema/${encodeURIComponent(key)}`, {
credentials: CREDENTIALS,
});
if (!res.ok) return null;
return parseSchema(await res.json());
} catch {
return null;
}
}
/** Persist one database's Map coordinate pair; two absent keys restore built-in `lat`/`lon`. */
export async function saveSchemaMap(
key: string,
latField: string | undefined,
lonField: string | undefined,
): Promise<SchemaMapSetup | null> {
try {
const res = await fetch(`${API_V1}/nav/schema/${encodeURIComponent(key)}/map`, {
method: "PUT",
credentials: CREDENTIALS,
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ latField: latField || null, lonField: lonField || null }),
});
if (!res.ok) return null;
const body = await res.json() as { map?: unknown } | null;
if (!body || !("map" in body)) return null;
return parseSchemaMap(body.map);
} catch {
return null;
}
}
/**
* What the shell does with an entry:
* native β this tree renders it (a hash route)
* handoff β a labelled link into the current application (`?page=<key>`)
* group β a FOLDER head, not a destination: a label row, never a link
*/
export type NavKind = "native" | "handoff" | "group";
export interface NavEntry {
key: string;
label: string;
managedBy?: "loopable";
protected?: boolean;
source?: string;
/** Server-authored Data-rail group; kept separate from the descriptive source badge. */
sourceGroup?: string;
group?: string;
sync?: { at: string | null; empty: boolean | null };
kind: NavKind;
/** 0 = top level, 1 = a sub-module rail entry (indented, like the app's rail). */
depth: number;
/** Absent for a group head β there is nowhere to go. */
href?: string;
/** WAVE 19 R8 β the tenant's chosen mark; absent β the default cylinder. */
icon?: FolderIcon;
/** WAVE 19 R14 β the server's answer to "may this session rename/re-icon it".
* Absent β no, and the route refuses independently. */
manage?: boolean;
/** WAVE 21 R3/C3 β the server's answer to "may this session DELETE it": the
* CREATOR or an admin, never the whole `may_open` set `manage` rides on (see
* the long note on `NavPage.canDelete`). Absent β no. */
canDelete?: boolean;
/** β WAVE 27 item 3 / C9 β a LOCKED database: no new records, fields still fine (see the
* long note on `NavPage.locked`). Absent β unlocked. */
locked?: boolean;
/** ββ WAVE 34 R1 / C1 β the mark-important counts (see the long note on `NavPage.important`).
* THE SECOND HALF of that flag, and it is here for the reason `canDelete` and `locked` are:
* a value parsed onto the payload and dropped in `shapeNav` reaches no row anybody renders,
* which is precisely how wave 20 shipped four wirings that went nowhere. */
important?: NavImportant;
/**
* β WAVE 25 (D-54) β THIS ROW IS A SURFACE, NOT A DATABASE.
*
* Absent β it is a database (or a folder head over some). Set by `shapeNav` from
* `SURFACE_KEYS`, so the fact is decided ONCE, where rows are built, rather than
* re-derived by every consumer that happens to remember.
*
* β THE DEBT THIS CLOSES IS NOT "Home had a bug", it is that the FILTER WAS A
* LOCAL EXPRESSION. The rail has excluded Automation since wave 19 R10 with an
* inline `entries.filter(e => e.key !== "automation")`; Home was written against
* the raw list a wave later and drew the Automation SURFACE a tile under the
* heading "Databases", beside an "Automations" section listing what it contains.
* No gate could see it β rendering a tile per granted entry is exactly what that
* code was asked to do. A rule every consumer must remember is not a control
* ([[rules-need-gates]]), so it became a property of the row plus one accessor.
*/
surface?: true;
}
/**
* Granted nav rows that are NOT databases.
*
* β A CLIENT CAPABILITY FACT, NOT A PERMISSION ONE, exactly like `NATIVE_KEYS` two
* screens down: the server decides what this account may open, and this decides
* which of those rows a DATABASE list is entitled to draw. A key here that the
* server never sends simply never matches.
*
* Intelligence and Automation (key `automation`) never appear as databases.
*/
export const SURFACE_KEYS: ReadonlySet<string> = new Set(["automation", "intelligence"]);
// W60-T39 / R16: the shell and gallery both need the Agents address. Keep it here because
// AutomationSurface is a lazily loaded chunk that neither may statically import.
export function readAgentAddress(
hash = typeof window === "undefined" ? "" : window.location.hash,
): { agent: string; voice: string } {
const query = hash.indexOf("?");
if (query < 0 || hash.slice(0, query) !== "#/automation") return { agent: "", voice: "" };
const params = new URLSearchParams(hash.slice(query + 1));
return { agent: params.get("agent") || "", voice: params.get("voice") || "" };
}
export function agentAddressHash(kind: "agent" | "voice", id: string): string {
return `#/automation?${kind}=${encodeURIComponent(id)}`;
}
/**
* A `NavEntry` that has been through {@link databaseEntries} β and the brand is the
* point, not decoration.
*
* β IT MAKES THE WRONG LIST A COMPILE ERROR RATHER THAN A CODE REVIEW. A component
* that draws databases declares `DatabaseEntry[]`, so handing it the raw `entries`
* does not type-check and `npx tsc -b` says so on the day it is written. That is the
* same lesson this repo learned about optional props (`verify_wiring.py`'s header:
* an optional prop degrades to "the feature does not exist"), applied to a LIST: an
* unfiltered one degrades to "one extra tile", which nobody notices for a wave.
*
* β `DatabaseEntry` IS a `NavEntry`, so anything taking the wider type still accepts
* these. The brand only blocks the unsafe direction.
*/
export type DatabaseEntry = NavEntry & { readonly __isDatabase: true };
/**
* The granted nav, minus the surfaces that are not databases. **The only supported
* way to obtain a database list** (D-54).
*
* β IT NARROWS, IT NEVER WIDENS β `entries` stays the outer bound, so the server's
* grant is never re-litigated here. Nothing is added, reordered or renamed; rows are
* dropped, and only rows this module has declared to be surfaces.
*/
export function databaseEntries(entries: NavEntry[]): DatabaseEntry[] {
return entries.filter((e) => !e.surface) as DatabaseEntry[];
}
/**
* The surfaces THIS TREE can actually render:
* Β· `customer_data` / `cohort` β the Customer table, the same `customer-grid`
* component the Streamlit embed ships.
*
* β This is a CLIENT capability list, not a permission list, and the two must
* not be confused. The server decides what a user MAY open; this decides what
* the shell KNOWS HOW to draw. A key here that the server did not send is
* simply never rendered β the payload is the outer bound, always.
*
* β’ THE NEXT PORTED SURFACE (Collections / Procurement) JOINS BY ADDING ITS KEY
* HERE + a server-side builder. That is the whole bet of the Y1 envelope: a
* ported page is a registry entry plus a builder, never a new component tree.
* `sales` was the proof (EXIT wave 2) and LEFT wave 16 (owner item 7, R3/R11):
* the registry row is archived, the builder unregistered, and the owner
* rebuilds sales views from the grid's chart/dashboard modes β so the envelope
* machinery (PageView, ui/, viz/) is currently a capability with no shipped
* page, kept warm by the render-smoke fixture.
*/
export const NATIVE_KEYS: ReadonlySet<string> = new Set<string>(
// `cohort` joined 2026-07-30 and LEFT wave 16 (owner item 5, R10): every cohort now
// projects as a LOCKED VIEW in the Customer rail's "Cohorts" section (wave-15 C-LOCK),
// so the separate route is gone. The cohort MACHINERY stays β `scope=cohort`,
// `workspace.cohortMode`, the events β reachable from the Customer surface.
// `product_data` joined wave 16 (C-TOPIC, owner items 9+10): the SAME grid tree over the
// SKU catalogue β Shell maps it to `scope="product"` and everything else is the topic's.
// `automation` joined wave 18 (C-AUTONAV): SESSION D's surface, its own rail + editor.
// User tables are native BY PREFIX (`ut_`), decided in `shapeNav`, not listed here.
["customer_data", "product_data", "automation", "intelligence"]);
/** The native keys the Y1 page envelope drives (as opposed to `customer_data`,
* which is its own component tree). Kept beside NATIVE_KEYS so the two cannot
* drift: everything here MUST also be native, asserted in the gate. EMPTY
* since wave 16 (sales retired) β the next builder's key lands here. */
export const ENVELOPE_KEYS: ReadonlySet<string> = new Set<string>([]);
/** Hash routes ignore the legacy host argument and stay on the serving origin. */
export function appLink(_appBase: string, key: string): string {
return `#/${encodeURIComponent(key)}`;
}
/**
* Payload β rendered rows, in registry order, children under their parent.
*
* THE GROUP RULE IS DERIVED, NOT RECEIVED. X2's nav item carries no
* `group_only` flag, but `customers` IS one (registry: the folder head of
* customer_data + cohort β "it has no PAGE_FUNCS entry, the nav never renders
* it as a leaf"). So a page that is the `parent` of at least one page IN THE
* SAME PAYLOAD renders as a group head. Derived from the contracted payload
* alone; if the API later emits an explicit flag, prefer it (posted to S1 β
* additive, no amendment).
*
* β AN ORPHANED CHILD RENDERS AT TOP LEVEL. If `may_open` granted `cohort` but
* not its parent `customers`, the payload has the child and not the head β and
* hiding it because its family head is missing would take away a surface the
* server explicitly granted. Display never re-litigates a server grant.
*/
export function shapeNav(pages: NavPage[], appBase: string): NavEntry[] {
const present = new Set(pages.map((p) => p.key));
const childrenOf = new Map<string, NavPage[]>();
for (const p of pages) {
if (!p.parent || !present.has(p.parent)) continue;
const list = childrenOf.get(p.parent);
if (list) list.push(p);
else childrenOf.set(p.parent, [p]);
}
const entry = (p: NavPage, depth: number): NavEntry => {
// Wave 18 (C3-UT): any `ut_`-prefixed key is a USER TABLE β drawable by the same grid
// tree (Shell passes the key through as the scope), so it is native BY PREFIX rather
// than by membership. The server only emits ut rows this session may open, so this is a
// capability rule, never a permission one.
const isNative = NATIVE_KEYS.has(p.key) || p.key.startsWith("ut_");
// A native surface stays native even with children β the shell can draw it,
// so it is a destination first and a family head second. Otherwise: the
// server's flag wins, and has-children is the fallback for a payload that
// predates it.
const kind: NavKind = isNative
? "native"
: p.group_only || childrenOf.has(p.key)
? "group"
: "handoff";
return {
key: p.key,
label: p.label,
...(p.source ? { source: p.source } : {}),
...(p.sourceGroup ? { sourceGroup: p.sourceGroup } : {}),
...(p.group ? { group: p.group } : {}),
...(p.sync ? { sync: p.sync } : {}),
...(p.managedBy === "loopable" ? { managedBy: "loopable" as const } : {}),
...(p.protected ? { protected: true } : {}),
...(p.icon ? { icon: p.icon } : {}),
...(p.manage ? { manage: true } : {}),
// C3 (W-5) β carried through `shapeNav` beside `manage`. THE SECOND HALF
// OF THE SAME FLAG: `parseNav` reading it and this dropping it would put
// the answer on the payload and never on the row the rail renders, which
// is precisely how wave 20 shipped four wirings that went nowhere.
...(p.canDelete ? { canDelete: true } : {}),
// β WAVE 27 item 3 / C9 β THE SECOND HALF, for the reason stated directly above: a flag
// parsed onto the payload and dropped here reaches no row anybody renders.
...(p.locked ? { locked: true } : {}),
// ββ WAVE 34 R1 / C1 β THE SECOND HALF AGAIN, AND IT WAS MISSED ON THE FIRST TRY.
// `parsePages` validated `important` onto the payload and this function dropped it, so the
// number reached the wire, survived validation, and never reached a row. The `shapeNav`
// leg in `shell.test.ts` is what found it, minutes after being written; the two comments
// above say this exact thing about two earlier flags and it happened anyway, which is the
// argument for the leg rather than for the comment.
...(p.important ? { important: p.important } : {}),
// β D-54 β the databases/surfaces split, stamped at the ONE place rows are built.
// Not `kind`: a surface is `native` (this tree renders it) and so are the grids, so the
// existing discriminator cannot answer this question and widening it would have made
// "can the shell draw it" and "is it a database" one field with two meanings.
...(SURFACE_KEYS.has(p.key) ? { surface: true as const } : {}),
kind,
depth,
...(kind === "group"
? {}
: { href: isNative ? `#/${p.key}` : appLink(appBase, p.key) }),
};
};
const out: NavEntry[] = [];
for (const p of pages) {
// Children are emitted under their head, not in payload position.
if (p.parent && present.has(p.parent)) continue;
const head = entry(p, 0);
const children = childrenOf.get(p.key) ?? [];
// β An EMPTY folder head is dropped. It is not a destination by definition,
// so with nothing under it the row says only "here is something you cannot
// reach" β which happens to a user granted `customers` but neither child.
// This is not re-litigating a grant: a container is not a surface.
if (head.kind === "group" && children.length === 0) continue;
out.push(head);
for (const c of children) out.push(entry(c, 1));
}
return out;
}
/**
* The surface the shell lands on, in preference order.
*
* β IT IS AN EXPLICIT PREFERENCE, NOT "the first native entry". It used to be
* the latter, and the result was that the shell opened on SALES β purely
* because `sales` sorts first in the registry β which is the one module the
* owner had said to leave alone. "Customer doesn't load on first
* initialization" was that, exactly: Customer loaded fine, it just was not what
* came up. A landing page is a product decision and belongs in a list somebody
* can read, not in whatever the registry happens to order first.
*/
// (`cohort` left the list with its NATIVE_KEYS exit, wave 16 β a landing must be drawable.)
//
// β WAVE 23 (contract C10, ruling R7) β THE LANDING IS NOW `#/home`.
//
// β CHROME ROUTES ARE NOT GRANTED PAGES, AND THE :1039 LAW SURVIVES INTACT. This shell's
// oldest rule is that the nav is server-filtered and an undeclared surface is denied β which is
// why Alerts is a PANEL and not a route. Home and Connectors are routes, and they do not
// violate that rule for one reason that has to be true of every future member of this set:
//
// A CHROME ROUTE RENDERS NOTHING THE SERVER DID NOT ALREADY GRANT.
//
// Home shows the entries `/nav` returned (its recents are RESOLVED against those entries and a
// key absent from them is dropped, `homeModel.groupRecents`) plus create affordances that were
// already in the rail. Connectors renders a SERVER-COMPOSED directory (`GET /connectors/
// directory`, session-gated) β it is a window onto a payload, not a surface with its own data.
// Neither can show a database, a module or a connector this session may not see; adding a route
// that could would be the hard-coded surface the frame refuses to have.
export const HOME_ROUTE = "home";
export const CONNECTORS_ROUTE = "connectors";
/** Intelligence is a granted module, never an unconditional chrome destination. */
export const INTELLIGENCE_ROUTE = "intelligence";
/**
* WAVE 55 / R1-R3: the tenant Application registry has one chrome destination.
*
* App is a directory over Application definitions already permission-filtered by the server. It
* is not a registry module and it does not replace the database Views that pre-date it. Keeping
* the route in chrome prevents a tenant's restricted module list from hiding its own Apps.
*/
export const APP_ROUTE = "app";
export interface ApplicationTemplateRole {
key: string;
label: string;
required: boolean;
types: string[];
}
export interface ApplicationTemplate {
kind: string;
label: string;
applicationType: string;
displayMode?: string;
fieldRoles: ApplicationTemplateRole[];
defaultPlacement: { section: "app"; order: number };
deepLink?: string;
/** A template bound to one database offers only that one in the wizard (S78-T17). */
sourceDatabase?: string;
}
/** Accept server template kinds without maintaining a second registry. */
export function parseApplicationTemplates(body: unknown): ApplicationTemplate[] {
const rows = (body as { templates?: unknown } | null)?.templates;
if (!Array.isArray(rows)) return [];
return rows.filter((row): row is ApplicationTemplate => {
if (!row || typeof row !== "object" || Array.isArray(row)) return false;
const template = row as Partial<ApplicationTemplate>;
return typeof template.kind === "string" && !!template.kind.trim()
&& typeof template.label === "string" && !!template.label.trim()
&& typeof template.applicationType === "string" && !!template.applicationType.trim()
&& template.defaultPlacement?.section === "app"
&& typeof template.defaultPlacement.order === "number"
&& Number.isFinite(template.defaultPlacement.order)
&& Array.isArray(template.fieldRoles) && template.fieldRoles.every((role) =>
role && typeof role.key === "string" && !!role.key.trim()
&& typeof role.label === "string" && typeof role.required === "boolean"
&& Array.isArray(role.types) && role.types.every((type) => typeof type === "string"));
});
}
/** Read page App addresses separately from the database-backed App address. */
export function readApplicationPageAddress(hash: string): { kind: "code" | "customer-card" | "template"; id: string } | null {
const match = /^#\/app\/(code|customer-card|template)\/([^/?#]+)$/.exec(hash);
if (!match || match[0] !== hash) return null;
try {
const id = decodeURIComponent(match[2]);
return id && !/[/?#\x00-\x1f\x7f]/.test(id) ? { kind: match[1] as "code" | "customer-card" | "template", id } : null;
} catch { return null; }
}
export type LegacyApplicationPage = "template" | "database" | "unavailable" | "source_unavailable";
/** Resolve the shared App before admitting its legacy source database. */
export async function resolveLegacyApplicationPage(id: string, abortSignal: AbortSignal): Promise<LegacyApplicationPage> {
try {
const response = await fetch(`${API_V1}/applications/${encodeURIComponent(id)}/availability`, {
credentials: CREDENTIALS, signal: abortSignal,
});
if (checkTenant(response)) return "unavailable";
if (response.status === 401) signal(UNAUTHORIZED_EVENT);
// Routing and Catalog use the database dispatcher and have no standalone availability.
if (response.status === 404) return "database";
if (!response.ok) return response.status >= 500 ? "source_unavailable" : "unavailable";
const body = await response.json();
const app = body?.application;
return app?.id === id && typeof app.templateView === "string" && !!app.templateView
&& app.fieldMap && typeof app.fieldMap === "object" && !Array.isArray(app.fieldMap)
? "template" : "unavailable";
} catch { return "source_unavailable"; }
}
/** W62-T19 / R52: Data is a real chrome route, rendered by Shell.tsx's Home/App/Data fallback
* branch. Joining CHROME_ROUTES is inert for firstDestination: LANDING_PREFERENCE is [HOME_ROUTE]. */
export const DATA_ROUTE = "table";
/** Commit the destination before starting any asynchronous existence or data read. */
export function commitRoute(href: string): boolean {
const previous = window.location.hash;
window.location.hash = href;
return window.location.hash !== previous;
}
/** C6's Data address, including the folder stratum above the grid's database/view path. */
export interface DataAddress { database?: string; view?: string; folder?: string; filters?: DataPath["filters"] }
/** Build C6 addresses for shell/rail navigation. These helpers own the folder stratum;
* dataPath.ts remains the grid's database/view reader and its path semantics are unchanged. */
export function dataAddressHash(address: DataAddress): string {
const params = new URLSearchParams();
for (const key of ["database", "view", "folder"] as const) {
if (address[key]) params.set(key, address[key]);
}
if (address.filters) params.set("filters", JSON.stringify(address.filters));
const query = params.toString();
return `#/${DATA_ROUTE}${query ? `?${query}` : ""}`;
}
/** Read the folder stratum and address keys for shell/rail navigation, not grid path semantics.
* dataPath.ts remains the grid reader. An explicit hash also works when evaluated under Node. */
export function readDataAddress(
hash = typeof window === "undefined" ? "" : window.location.hash
): DataAddress {
const [route, query = ""] = canonicalDataHash(hash).split("?", 2);
if (!/^#\/?table(?:\/[^?#]*)?$/.test(route)) return {};
const params = new URLSearchParams(query);
const address: DataAddress = {};
for (const key of ["database", "view", "folder"] as const) {
const value = params.get(key);
if (value !== null) address[key] = value;
}
const filters = decodeDataFilters(params.get("filters"));
if (filters) address.filters = filters;
return address;
}
/**
* ββ WAVE 32 (ruling R1, contract C5) β QUERY IS THE FOURTH CHROME ROUTE, and it satisfies the
* law above THROUGH ITS REQUIRED PROP rather than despite it.
*
* `QueryPage` takes `granted: NavEntry[]` β the database entries the shell already holds from
* `/nav`, which is to say the set the SERVER decided this session may see. It makes no listing
* call of its own, so *"a chrome route renders nothing the server did not already grant"* is true
* by construction here rather than by promise, and the AI cannot name a database the caller was
* not already given (C5's permission clause, re-used rather than re-implemented).
*
* β NOT a `registry.py` module, because the tenant module list filters registry keys: every tenant's
* `modules` list is `['analyst','automation']`, so a registry key would be omitted from the rail
* in every tenant while every gate stayed green.
*/
export const QUERY_ROUTE = "query";
/**
* ββ 2026-08-14 (owner item 2) β THE AI ASSISTANT, THE FIFTH CHROME ROUTE AND THE ONLY AI DOOR.
*
* β IT REPLACES `AI_AGENT_ROUTE`, WHICH IS DELETED. Owner, verbatim: *"Remove the 'AI agent'
* module completely. previous wave did not follow instruction. AI assistant module IS AI agent
* module. So no need to separate it like that."* Wave 33 shipped `#/ai-agent` beside an assistant
* row whose click opened an under-construction note; the note beside that row had already argued
* for exactly this collapse and deferred it as ASK C-9. So the surface is not renamed, it is
* REPLACED: the assistant row now goes somewhere, and there is one AI module rather than two.
*
* A CHROME route for the same reason `QUERY_ROUTE` is, and the argument is
* load-bearing rather than filing: every provisioned tenant's `modules` list is
* `['analyst','automation']`, so a `registry.py` key would be silently omitted from the rail in
* every tenant while every gate stayed green.
*
* β AND IT MEETS THE :1039 LAW THE SAME WAY `QueryPage` DOES β BY ITS REQUIRED PROP.
* `AssistantPage` takes `granted: NavEntry[]`, the entries the shell already holds from `/nav`,
* so the AI cannot be pointed at a database the SERVER did not already grant this session. The
* build door re-checks regardless (`routes_query._target` β `routes_templates._target_or_refuse`),
* which is the wall; this is what stops the picker offering what the wall would refuse.
*
* β THE RAIL ROW STAYS CONDITIONAL ON THE `analyst` NAV ENTRY, and that is not an inconsistency
* with "chrome needs no grant". The ROUTE is chrome (typing `#/assistant` works); the ROW is the
* registry's `analyst` utility entry, with the three arms W33-T22 built for it (ready / pending /
* unavailable). Collapsing those into an unconditional link would re-open the owner's own
* layout-jump report, which is what that ticket was.
*/
export const ASSISTANT_ROUTE = "assistant";
export const ARTIFACTS_ROUTE = "artifacts";
/**
* ββ WAVE 35 Β· T06 (owner item 13, contract C6) β the three ACCOUNT routes. Owner: *"add below
* settings the following button: Feedback β¦, Usage credits β¦, and a Subscription module β¦
* Specialized for the Royal Imports tenant, do not show it."*
* β THE SURFACE IS CALLED "Usage" SINCE W37-T02 AND THIS QUOTE IS NOT UPDATED TO MATCH. It is
* what the owner TYPED; editing their words to agree with a later rename destroys the only record
* of what was actually asked for. The route key never carried the old label anyway.
*
* β THEY MUST JOIN `CHROME_ROUTES` OR THEY RENDER NOTHING BEHIND A 200. Shell's oldest law denies
* an undeclared SURFACE; these are chrome β they need no grant because they show the caller its own
* account, never a tenant's data.
* β `SUBSCRIPTION_ROUTE` is chrome for EVERY tenant here and refused for Royal Imports at the
* DISPATCH (C6). Excluding it from this set instead would deny it to everyone, which is a different
* bug wearing the same screen.
*/
/**
* WAVE 55 instruction 2 removes Starred as a module. The old key remains only as a compatibility
* address and is rewritten to Home's starred-only filter below. Keeping the key costs no rail row,
* preserves bookmarks, and leaves the tenant's durable star flags untouched.
*/
export const STARRED_ROUTE = "starred";
export const FEEDBACK_ROUTE = "feedback";
export const USAGE_ROUTE = "usage";
export const SUBSCRIPTION_ROUTE = "subscription";
/**
* β WAVE 35 Β· T06 β the tenant that does NOT get a subscription page. Owner item 13, verbatim:
* *"Specialized for the Royal Imports tenant, do not show it."* Tenant #0 is the owner's own
* company and is not a paying customer of the platform.
* β ONE constant, read by BOTH halves of C6 (the menu row and the route), because "hidden in the
* menu while the route still answers" is not hidden β and two copies of a slug is how those two
* halves drift apart.
*/
export const NO_SUBSCRIPTION_TENANT = "royal-imports";
export const CHROME_ROUTES: ReadonlySet<string> = new Set([
HOME_ROUTE,
APP_ROUTE,
CONNECTORS_ROUTE,
DATA_ROUTE,
QUERY_ROUTE,
ASSISTANT_ROUTE,
ARTIFACTS_ROUTE,
FEEDBACK_ROUTE,
USAGE_ROUTE,
SUBSCRIPTION_ROUTE,
]);
/** Home, including its Starred filter, keeps the rail expanded until the reader folds it. */
export const NAV_STAYS_EXPANDED_ROUTES: ReadonlySet<string> = new Set([
HOME_ROUTE,
]);
// W60-T37 (R19) supersedes wave 57 R3 clause 1: App shares Data's cell-click fold, not an arrival fold.
/**
* Old route key β the key that replaced it. Applied to the hash before ANYTHING else reads it.
*
* β C3: *"the old `alerts` route redirects, it is not deleted β a stored nav preference naming
* `alerts` must not orphan."* This is that clause, and it is the RENAME checklist's step 5
* (*"grants and preferences migrate ON READ; never edit stored user records to migrate a
* rename"*) expressed for a chrome route.
*
* β MEASURED, AND IT CHANGES WHAT THIS IS FOR: **there was no `#/alerts` route to redirect.**
* Alerts was deliberately a PANEL β `Shell.tsx`'s bell is a `<button>`, and the comment beside it
* says a client-invented `#/alerts` route *"would be exactly the hard-coded surface the frame
* refuses to have"*. So no user has a stored `alerts` placement, and the clause was written
* against a route that never existed. It is kept anyway, as forward insurance rather than
* archaeology: `#/alerts` is the hash a person would GUESS, type, or have bookmarked from a
* notification email, and answering it costs one map lookup. Retiring it would need evidence
* nobody types it, which is not obtainable.
*/
export const LEGACY_ROUTES: Readonly<Record<string, string>> = {
data: DATA_ROUTE,
alerts: ASSISTANT_ROUTE,
inbox: ASSISTANT_ROUTE,
[STARRED_ROUTE]: HOME_ROUTE,
/**
* β 2026-08-14 β `#/ai-agent` was a REAL route for one wave (wave 33 shipped it, and the
* owner's *"remove that AI agent module completely"* retires it). Unlike `alerts` above, this
* one genuinely existed and genuinely was reachable, so somebody can hold the hash.
*
* β A REDIRECT IS NOT THE MODULE. Nothing of `ai-agent` survives β no page, no api file, no
* rail row, no mount, no `AI_AGENT_ROUTE` constant, and `verify_wiring.py` asserts each of
* those absences. This is one map entry that answers a stale hash with the surface that
* replaced it, which is the RENAME checklist's step 5 (*"grants and preferences migrate ON
* READ"*) for a chrome route. Without it the hash resolves to nothing and silently lands on
* Home β a worse answer to the same question.
*/
"ai-agent": ASSISTANT_ROUTE,
// R37: saved Query answers live in Artifacts, served by the same analyst grant.
[QUERY_ROUTE]: ARTIFACTS_ROUTE,
};
/** Rewrite retired hashes before the shell publishes their destination. */
export const REWRITTEN_ROUTES: Readonly<Record<string, string>> = {
[QUERY_ROUTE]: ARTIFACTS_ROUTE,
[STARRED_ROUTE]: `${HOME_ROUTE}?filter=starred`,
};
/**
* The ROUTE KEY in a hash, with any query string or nested fragment stripped.
*
* β THE BUG THIS EXISTS TO PREVENT WAS REPORTED BY LANE D BEFORE IT COULD HAPPEN (post D-1), and
* it is invisible until you try it: the shell read the WHOLE remainder of the hash as the key, so
* `#/assistant?mode=query` resolved to the key `assistant?mode=query`, matched no route, and fell
* through to Home. The redirect below would have "worked" β right URL, wrong screen β and every
* gate keyed on the redirect's target string would have been green.
*/
export function routeKeyOf(hash: string): string {
const key = hash.replace(/^#\/?/, "").split("?")[0].split("#")[0];
return /^(data|table)(\/|$)/.test(key) ? key.split("/")[0] : key;
}
/**
* The hash this one must BECOME, or null when it is already right.
*
* β RETURNS NULL FOR AN ALREADY-REWRITTEN HASH, which is the whole loop-safety argument: writing
* `location.hash` fires `hashchange`, the caller asks again, the key is now `assistant`, and this
* answers null. One rewrite, never a cycle.
*/
export function rewrittenHash(hash: string): string | null {
const canonicalHash = canonicalDataHash(hash);
const routeKey = routeKeyOf(canonicalHash);
const target = REWRITTEN_ROUTES[routeKey];
if (target) return `#/${target}`;
if (routeKey !== DATA_ROUTE) return null;
// Legacy database-backed App links keep their existing destination and raw query.
if (/^#\/?table\?/.test(canonicalHash)) {
const query = canonicalHash.slice(canonicalHash.indexOf("?") + 1);
const application = new URLSearchParams(query).get("application")?.trim();
if (application) return `${APP_PATH_PREFIX}${query}`;
}
return canonicalHash !== hash ? canonicalHash : null;
}
/** The current key for a hash that may name a retired one. Identity for everything else. */
export function canonicalRoute(route: string): string {
return LEGACY_ROUTES[route] ?? route;
}
export const LANDING_PREFERENCE: readonly string[] = [HOME_ROUTE];
/**
* The surface the shell lands on.
*
* β THE THREE LANDING SITES MOVE TOGETHER OR LOGINS STRAND (C10's own warning): this function,
* `LANDING_PREFERENCE` above, and the post-login redirect in `Shell.tsx`. Half a move leaves a
* signed-in user on a hash nothing renders.
*
* A chrome route needs no entry to be reachable β that is what makes it chrome β so the loop
* below returns it without consulting `entries`, and the old preference chain survives beneath
* it for the day a granted page becomes the landing again. `entries` stays a parameter for the
* same reason: the fallback is still a real answer about a real payload.
*/
export function defaultRoute(entries: NavEntry[]): string {
return firstDestination(entries, LANDING_PREFERENCE);
}
/**
* The landing rule itself, over an arbitrary preference list.
*
* β EXTRACTED (wave 23) SO THE FALLBACK CHAIN STAYS UNDER TEST. Before C10 the chain WAS
* `defaultRoute`, so `shell.test.ts` asserted it by calling that. With `home` at the head of the
* preference the function now returns on its first line, and the whole "preferred native entry β
* any native entry β any destination" ladder became unreachable from the outside β three checks
* would have had to be deleted rather than retargeted, which is how a gate quietly stops
* asserting the thing it was written for ([[gate-can-report-green-on-nothing]]). It is one
* function called two ways instead.
*/
export function firstDestination(
entries: NavEntry[],
preference: readonly string[]
): string {
for (const key of preference) {
// A chrome route needs no entry to be reachable β that is what makes it chrome.
if (CHROME_ROUTES.has(key)) return key;
const hit = entries.find((e) => e.key === key && e.kind === "native");
if (hit) return hit.key;
}
return (
entries.find((e) => e.kind === "native")?.key ??
entries.find((e) => e.kind !== "group")?.key ??
""
);
}
/**
* Resolve a hash route against the nav.
*
* A GROUP is never a destination β a hand-typed `#/customers` resolves to the
* family's first member, mirroring what the app itself does with a stale
* `?page=customers` deep link ("redirects to the family's first visible
* member"). An unknown route falls to the default. Both fall back rather than
* erroring, because a URL is something a person can type or a bookmark can
* outlive.
*
* β WAVE 23 (C10): the fallback is now `#/home`, which is CHROME and therefore matches no
* entry β so this returns `undefined` for an unknown route, and the frame reads "no entry" as
* "render Home". One behaviour change, stated plainly: `#/deleted_table` used to open the
* Customer grid and now opens Home. That is the better answer (the reader asked for something
* that is gone; the landing is where you choose again) and it is the SAME answer an empty hash
* gets β which is what "Home is the default" has to mean in order to be true.
*/
export function resolveRoute(entries: NavEntry[], route: string): NavEntry | undefined {
const i = entries.findIndex((e) => e.key === route);
if (i >= 0) {
const hit = entries[i];
if (hit.kind !== "group") return hit;
// A group head: fall through to its first real member β the rows that
// follow it DEEPER, stopping at the next row of its own level or shallower.
for (const e of entries.slice(i + 1)) {
if (e.depth <= hit.depth) break;
if (e.kind !== "group") return e;
}
}
const fallback = defaultRoute(entries);
return entries.find((e) => e.key === fallback);
}
// ---------------------------------------------------------------------------
// shell/nav.ts β X6: the shell's nav, shaped from `GET /api/v1/nav`.
//
// WHAT CHANGED, AND WHY IT MATTERS MORE THAN IT LOOKS. The wave-4 nav was a
// STATIC array in Shell.tsx β a hand-kept mirror of `core/registry.py` that
// nobody's build would notice going stale, and that showed every surface to
// everybody. It is now rendered from a SERVER-FILTERED payload: the API applies
// `may_open` (incl. `_LEGACY_KEYS` migration-on-read) and drops archived
// modules, so what a user sees IS what the server granted. Registry-driven at
// one end, permission-filtered at the other.
//
// β THERE IS NO CLIENT-SIDE FALLBACK LIST, deliberately. If `/api/v1/nav`
// fails or answers with a malformed envelope, the shell renders a bounded retry
// state, never a hard-coded list. A fallback would put surfaces on screen that
// the server never authorised, which is precisely the fail-closed rule the wave
// is built on ("an undeclared surface is denied"), and it would mask a broken API
// as a working one.
//
// No `import.meta` here either: `appBase` is a PARAMETER so this module
// compiles and runs under node in `verify_login.py` (see session.ts).
// ---------------------------------------------------------------------------
import { API_V1, CREDENTIALS, UNAUTHORIZED_EVENT, checkTenant, signal } from "../apiContract";
import { APP_PATH_PREFIX, canonicalDataHash, decodeDataFilters } from "../customer-grid/dataPath";
import type { DataPath } from "../customer-grid/dataPath";
// β WAVE 19 R8 / C1 β the icon vocabulary is the GRID's, imported not redefined.
// A VALUE import (not type-only) because the whitelist has to exist at runtime:
// `FolderMark` indexes `FOLDER_SHAPE_PATHS[shape]` and maps the result, so one
// unrecognised shape off the wire is `undefined.map` β a white screen, from a
// stored preference. `customer-grid/types` imports only `./windows`, which
// imports nothing, so this stays runnable under plain node (verify_login
// compiles this module and executes it there β see the header note on
// `appBase` being a parameter for exactly that reason).
import { FOLDER_SHAPES, FOLDER_TONES } from "../customer-grid/types";
import type { FolderIcon } from "../customer-grid/types";
/** One entry of X2's nav payload. `source` is the registry's connector fact
* (wave-9 I8: "Sales Β· Odoo"); `parent` names a sub-module's family head. */
export interface NavPage {
key: string;
label: string;
/** C1's injected system-table descriptor. The client displays it but never offers generic mutation. */
managedBy?: "loopable";
protected?: boolean;
source?: string;
/** Authoritative Data-rail grouping label (for example Odoo or Custom). */
sourceGroup?: string;
group?: string;
sync?: { at: string | null; empty: boolean | null };
parent?: string;
/**
* The registry's `group_only`: this key names a FOLDER, never a destination
* (`customers` is the only one today β the head of customer_data + cohort).
*
* β ADDED BY S1 2026-07-30, additive, present only when true. It supersedes
* the client's has-children DERIVATION, which stays as the fallback for a
* payload that predates the flag: the registry knows this fact, and a client
* re-deriving a fact the server holds is drift waiting to happen.
*/
group_only?: boolean;
/**
* `core.perms.nav_pages`' placement flag: `'main'` is the module list,
* `'utility'` is a live surface the HOST renders outside it (Analyst,
* Settings, the Metric Dictionary). The payload has carried it since X6;
* rendering utility rows in the main list was this client's own gap β
* `nav_pages`' docstring says "the client places them where the host does".
*/
chrome?: "main" | "utility";
/**
* WAVE 19 R8 / C1 β the mark this database wears, from the tenant-wide
* `nav_meta` bucket. Absent β the default cylinder, which is every database
* that has never been given one.
*
* β TENANT-WIDE, not per-user, and that is the whole difference between this
* and `nav_prefs` two fields down. Folders and placement are one person's
* arrangement of their own rail; an icon and a name are what the DATABASE is
* called, and a workspace where two people call the same table different
* things has no shared vocabulary to hold a conversation in.
*/
icon?: FolderIcon;
/**
* WAVE 19 R14 β may THIS session change this row's icon (and, for a `ut_` key,
* its name)? The SERVER answers, because it is the only end that can: the
* client cannot see who created a user table.
*
* β FAIL-CLOSED BY ABSENCE, like every other flag on this payload. A row that
* does not say `manage: true` offers no rename and no icon picker β and the
* route re-checks regardless, so this is the courtesy half of "the client
* hides, the server forbids", never the wall.
*/
manage?: boolean;
/**
* WAVE 21 item 6 (ruling R3, contract C3) β may THIS session DELETE this
* database?
*
* β A SEPARATE FLAG FROM `manage`, deliberately, and reusing that one would
* have been the bug. `manage` rides `user_tables.may_open` β which R14 widened
* to include everyone a table has been SHARED with (D-32, `user_tables.py:511`).
* That is the right reach for renaming and re-iconing; it is far too wide for
* a verb that destroys ten artifact families. R3 scopes delete to the CREATOR