portal-mojo 0.1.0

package/src/admin/monitoring/MetricsPermissionsPage.tsx

@@ -0,0 +1,166 @@
+import { useEffect, useState } from 'react';
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { TagInput, modal, toast } from '../../ui';
+import {
+    clearMetricsPermissions,
+    listMetricsPermissions,
+    metricsPermissionKeys,
+    normalizeMetricPermissions,
+    saveMetricsPermissions,
+    type MetricsPermissionRow,
+} from './models';
+
+function samePermissions(a: string[], b: string[]): boolean {
+    return a.length === b.length && a.every((value, index) => value === b[index]);
+}
+
+function PermissionRow({ row }: { row: MetricsPermissionRow }) {
+    const queryClient = useQueryClient();
+    const [view, setView] = useState(row.view_permissions);
+    const [write, setWrite] = useState(row.write_permissions);
+
+    useEffect(() => {
+        setView(row.view_permissions);
+        setWrite(row.write_permissions);
+    }, [row.view_permissions, row.write_permissions]);
+
+    const refresh = () => queryClient.refetchQueries({ queryKey: metricsPermissionKeys.all });
+    const save = useMutation({
+        mutationFn: saveMetricsPermissions,
+        onSuccess: async () => {
+            await refresh();
+            toast.success(`Permissions for ${row.account} saved`);
+        },
+        onError: (error) => toast.error(error instanceof Error ? error.message : 'Save failed'),
+    });
+    const clear = useMutation({
+        mutationFn: clearMetricsPermissions,
+        onSuccess: async () => {
+            // DELETE clears the two permission keys, not the account registry.
+            // Refetch the authoritative row rather than removing it locally.
+            await refresh();
+            toast.success(`Permissions for ${row.account} cleared`);
+        },
+        onError: (error) => toast.error(error instanceof Error ? error.message : 'Clear failed'),
+    });
+
+    const normalizedView = normalizeMetricPermissions(view);
+    const normalizedWrite = normalizeMetricPermissions(write);
+    const dirty = !samePermissions(normalizedView, row.view_permissions)
+        || !samePermissions(normalizedWrite, row.write_permissions);
+    const busy = save.isPending || clear.isPending;
+
+    const confirmClear = async () => {
+        const confirmed = await modal.confirm({
+            title: 'Clear permissions',
+            message: <>Clear all metric view and write permissions for <code>{row.account}</code>? The account remains listed.</>,
+            confirmText: 'Clear permissions',
+            danger: true,
+        });
+        if (confirmed) clear.mutate(row.account);
+    };
+
+    return (
+        <tr>
+            <th scope="row"><code>{row.account}</code></th>
+            <td>
+                <TagInput
+                    value={view}
+                    onChange={(_, tags) => setView(tags)}
+                    placeholder="Add view permission…"
+                    disabled={busy}
+                />
+            </td>
+            <td>
+                <TagInput
+                    value={write}
+                    onChange={(_, tags) => setWrite(tags)}
+                    placeholder="Add write permission…"
+                    disabled={busy}
+                />
+            </td>
+            <td>
+                <div className="monitoring-row-actions">
+                    <button
+                        type="button"
+                        className="btn btn-primary btn-compact"
+                        disabled={!dirty || busy}
+                        onClick={() => save.mutate({
+                            account: row.account,
+                            view_permissions: normalizedView,
+                            write_permissions: normalizedWrite,
+                        })}
+                    >
+                        {save.isPending ? 'Saving…' : 'Save'}
+                    </button>
+                    <button
+                        type="button"
+                        className="btn btn-danger btn-compact"
+                        disabled={busy || (row.view_permissions.length === 0 && row.write_permissions.length === 0)}
+                        onClick={() => void confirmClear()}
+                    >
+                        {clear.isPending ? 'Clearing…' : 'Clear permissions'}
+                    </button>
+                </div>
+            </td>
+        </tr>
+    );
+}
+
+export function MetricsPermissionsPage() {
+    const query = useQuery({
+        queryKey: metricsPermissionKeys.all,
+        queryFn: listMetricsPermissions,
+    });
+
+    return (
+        <div className="monitoring-page">
+            <header className="monitoring-page-head">
+                <div>
+                    <div className="eyebrow">System</div>
+                    <h1>Metrics permissions</h1>
+                    <p>Per-account slug-family gates for reading and writing metrics.</p>
+                </div>
+                <button
+                    type="button"
+                    className="btn btn-compact"
+                    disabled={query.isFetching}
+                    onClick={() => void query.refetch()}
+                >
+                    <i className={`bi bi-arrow-clockwise${query.isFetching ? ' spin' : ''}`} /> Refresh
+                </button>
+            </header>
+
+            <div className="panel monitoring-table-panel">
+                {query.isPending && <div className="monitoring-state">Loading metrics permissions…</div>}
+                {query.isError && (
+                    <div className="monitoring-state monitoring-state-error">
+                        <p>{query.error instanceof Error ? query.error.message : 'Failed to load metrics permissions.'}</p>
+                        <button type="button" className="btn" onClick={() => void query.refetch()}>Retry</button>
+                    </div>
+                )}
+                {!query.isPending && !query.isError && query.data.length === 0 && (
+                    <div className="monitoring-state">No metrics permission accounts found.</div>
+                )}
+                {!query.isPending && !query.isError && query.data.length > 0 && (
+                    <div className="monitoring-table-scroll">
+                        <table className="monitoring-table">
+                            <caption className="sr-only">Metrics permissions by immutable account</caption>
+                            <thead>
+                                <tr>
+                                    <th scope="col">Account</th>
+                                    <th scope="col">View permissions</th>
+                                    <th scope="col">Write permissions</th>
+                                    <th scope="col">Actions</th>
+                                </tr>
+                            </thead>
+                            <tbody>
+                                {query.data.map((row) => <PermissionRow key={row.account} row={row} />)}
+                            </tbody>
+                        </table>
+                    </div>
+                )}
+            </div>
+        </div>
+    );
+}

package/src/admin/monitoring/MetricsSourcePicker.tsx

@@ -0,0 +1,136 @@
+import { useEffect, useState } from 'react';
+import { useCan } from '../../client';
+import { CollectionSelect } from '../../ui';
+import type { MetricAccount, MetricsDiscoveryPage } from './metrics-explorer-data';
+
+const GROUP_DIRECTORY_PERMISSIONS = ['sys.view_groups', 'sys.manage_groups', 'sys.groups'];
+const USER_DIRECTORY_PERMISSIONS = ['sys.view_users', 'sys.manage_users', 'sys.users'];
+
+interface DirectoryGroup { id: number; name: string }
+interface DirectoryUser { id: number; display_name?: string; username?: string }
+
+export interface MetricsSourcePickerProps {
+    account: string;
+    parsedAccount: MetricAccount | null;
+    accountError: string | null;
+    accountsPage?: MetricsDiscoveryPage;
+    accountsPending: boolean;
+    accountsError: string | null;
+    accountSearch: string;
+    onAccountSearch: (value: string) => void;
+    onAccountPage: (start: number) => void;
+    onRetryAccounts: () => void;
+    onChange: (account: string) => void;
+}
+
+export function MetricsSourcePicker({
+    account, parsedAccount, accountError, accountsPage, accountsPending, accountsError,
+    accountSearch, onAccountSearch, onAccountPage, onRetryAccounts, onChange,
+}: MetricsSourcePickerProps) {
+    const [draft, setDraft] = useState(account);
+    const groupDirectory = useCan(GROUP_DIRECTORY_PERMISSIONS).can;
+    const userDirectory = useCan(USER_DIRECTORY_PERMISSIONS).can;
+
+    useEffect(() => setDraft(account), [account]);
+
+    const apply = () => onChange(draft);
+
+    return (
+        <section className="panel panel-pad metrics-source-card" aria-labelledby="metrics-source-heading">
+            <div className="metrics-section-head">
+                <div>
+                    <div className="eyebrow">Source</div>
+                    <h2 id="metrics-source-heading">Metric account</h2>
+                    <p>Use a full public, global, group, user, or configured custom account. The backend authorizes every request.</p>
+                </div>
+                {parsedAccount && <code className="metrics-account-chip">{parsedAccount.value}</code>}
+            </div>
+
+            <div className="metrics-source-grid">
+                <div className="metrics-source-manual">
+                    <label className="field">
+                        <span className="field-label">Exact account</span>
+                        <div className="metrics-inline-control">
+                            <input
+                                id="metrics-account-input"
+                                className={`input${accountError ? ' input-error' : ''}`}
+                                value={draft}
+                                maxLength={256}
+                                spellCheck={false}
+                                onChange={(event) => setDraft(event.target.value)}
+                                onKeyDown={(event) => { if (event.key === 'Enter') apply(); }}
+                                placeholder="global or group-42"
+                            />
+                            <button type="button" className="btn btn-primary" onClick={apply}>Use account</button>
+                        </div>
+                        {accountError && <span className="field-error">{accountError}</span>}
+                        {!accountError && <span className="field-help">Exact entry remains available for older unindexed accounts.</span>}
+                    </label>
+                </div>
+
+                <div className="metrics-source-browse">
+                    <label className="field">
+                        <span className="field-label">Authorized accounts</span>
+                        <input
+                            className="input"
+                            value={accountSearch}
+                            maxLength={128}
+                            onChange={(event) => onAccountSearch(event.target.value)}
+                            placeholder="Search account registry…"
+                        />
+                    </label>
+                    {accountsPending && <div className="metrics-compact-state">Loading accounts…</div>}
+                    {accountsError && (
+                        <div className="metrics-compact-state metrics-compact-error">
+                            <span>{accountsError}</span>
+                            <button type="button" className="btn btn-compact" onClick={onRetryAccounts}>Retry</button>
+                        </div>
+                    )}
+                    {accountsPage && !accountsError && (
+                        <>
+                            <select
+                                className="input"
+                                value={accountsPage.data.includes(account) ? account : ''}
+                                onChange={(event) => { if (event.target.value) onChange(event.target.value); }}
+                                aria-label="Authorized metric account"
+                            >
+                                <option value="">Choose an authorized account…</option>
+                                {accountsPage.data.map((value) => <option key={value} value={value}>{value}</option>)}
+                            </select>
+                            <div className="metrics-pager">
+                                <span>{accountsPage.count === 0 ? 'No accounts' : `${accountsPage.start + 1}–${accountsPage.start + accountsPage.pageCount} of ${accountsPage.count}`}</span>
+                                <button type="button" className="btn btn-compact" disabled={accountsPage.start === 0} onClick={() => onAccountPage(Math.max(0, accountsPage.start - accountsPage.size))}>Previous</button>
+                                <button type="button" className="btn btn-compact" disabled={accountsPage.nextStart == null} onClick={() => onAccountPage(accountsPage.nextStart ?? accountsPage.start)}>Next</button>
+                            </div>
+                        </>
+                    )}
+                </div>
+            </div>
+
+            {(groupDirectory || userDirectory) && (
+                <div className="metrics-directory-grid">
+                    {groupDirectory && (
+                        <CollectionSelect<DirectoryGroup>
+                            endpoint="/api/group"
+                            value={parsedAccount?.kind === 'group' ? parsedAccount.id : null}
+                            onChange={(id) => { if (id != null) onChange(`group-${id}`); }}
+                            label="Group directory convenience"
+                            labelField="name"
+                            placeholder="Search groups…"
+                        />
+                    )}
+                    {userDirectory && (
+                        <CollectionSelect<DirectoryUser>
+                            endpoint="/api/user"
+                            value={parsedAccount?.kind === 'user' ? parsedAccount.id : null}
+                            onChange={(id) => { if (id != null) onChange(`user-${id}`); }}
+                            label="User directory convenience"
+                            labelField="display_name"
+                            placeholder="Search users…"
+                        />
+                    )}
+                </div>
+            )}
+        </section>
+    );
+}

package/src/admin/monitoring/index.ts

@@ -0,0 +1,55 @@
+import type { AdminSection } from '../index';
+import { LogsPage } from './LogsPage';
+import { MetricsPermissionsPage } from './MetricsPermissionsPage';
+import { MetricsExplorerPage } from './MetricsExplorerPage';
+import {
+    LOGS_ADMIN_PERMISSIONS,
+    METRICS_EXPLORER_PERMISSIONS,
+    METRICS_PERMISSIONS_ADMIN_PERMISSIONS,
+} from './models';
+
+export * from './models';
+export * from './LogInspector';
+export * from './LogsPage';
+export * from './MetricsPermissionsPage';
+export * from './MetricsExplorerPage';
+export * from './MetricsSourcePicker';
+export * from './metrics-explorer-data';
+export * from './metrics-explorer-client';
+
+/**
+ * Reusable registry contribution. The section gate is the union needed to see
+ * at least one child; each direct route then applies its exact backend gate.
+ */
+export const MONITORING_ADMIN_SECTION: AdminSection = {
+    id: 'monitoring',
+    basePath: '',
+    title: 'Monitoring',
+    icon: 'bi-activity',
+    navigationGroup: 'observability',
+    permissions: [...new Set([
+        ...LOGS_ADMIN_PERMISSIONS,
+        ...METRICS_EXPLORER_PERMISSIONS,
+        ...METRICS_PERMISSIONS_ADMIN_PERMISSIONS,
+    ])],
+    routes: [
+        {
+            path: 'logs',
+            label: 'Logs',
+            component: LogsPage,
+            permissions: LOGS_ADMIN_PERMISSIONS,
+        },
+        {
+            path: 'metrics/explorer',
+            label: 'Metrics Explorer',
+            component: MetricsExplorerPage,
+            permissions: METRICS_EXPLORER_PERMISSIONS,
+        },
+        {
+            path: 'metrics/permissions',
+            label: 'Metrics Permissions',
+            component: MetricsPermissionsPage,
+            permissions: METRICS_PERMISSIONS_ADMIN_PERMISSIONS,
+        },
+    ],
+};

package/src/admin/monitoring/metrics-explorer-client.ts

@@ -0,0 +1,229 @@
+import { mojoCall, type Envelope, type MetricsResponse } from '../../client';
+import type { Params } from '../../client';
+import type { MetricsFetchParams } from '../../charts';
+import {
+    METRIC_DISCOVERY_PAGE_SIZE,
+    METRIC_SEARCH_MAX_LENGTH,
+    assertAddressableMetricSlug,
+    dedupeMetricSlugs,
+    metricSlugTail,
+    parseMetricAccount,
+    planMetricHistoryRequests,
+    type MetricGaugeValue,
+    type MetricPoint,
+    type MetricsDiscoveryFilters,
+    type MetricsDiscoveryPage,
+    type MetricsDiscoveryRequest,
+    type MetricsDiscoveryResource,
+} from './metrics-explorer-data';
+
+type UnknownRecord = Record<string, unknown>;
+
+export interface MetricsBreakdownResponse extends MetricsResponse {
+    groups: Record<string, number>;
+}
+
+function record(value: unknown, label: string): UnknownRecord {
+    if (value == null || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error(`Malformed metrics response: ${label} must be an object.`);
+    }
+    return value as UnknownRecord;
+}
+
+function stringArray(value: unknown, label: string): string[] {
+    if (!Array.isArray(value) || value.some((entry) => typeof entry !== 'string')) {
+        throw new Error(`Malformed metrics response: ${label} must be a string array.`);
+    }
+    return value as string[];
+}
+
+function integer(value: unknown, label: string, minimum = 0): number {
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < minimum) {
+        throw new Error(`Malformed metrics response: ${label} must be an integer >= ${minimum}.`);
+    }
+    return value;
+}
+
+function finiteNumber(value: unknown, label: string): number {
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        throw new Error(`Malformed metrics response: ${label} must be a finite number.`);
+    }
+    return value;
+}
+
+function sameKeys(value: UnknownRecord, expected: readonly string[], label: string): void {
+    const actual = Object.keys(value).sort();
+    const wanted = [...expected].sort();
+    if (actual.length !== wanted.length || actual.some((key, index) => key !== wanted[index])) {
+        throw new Error(`Malformed metrics response: ${label} keys do not match the request.`);
+    }
+}
+
+function validateDiscoveryRequest(request: MetricsDiscoveryRequest): Required<Pick<MetricsDiscoveryRequest, 'resource' | 'search' | 'start' | 'size'>> & Pick<MetricsDiscoveryRequest, 'account' | 'category'> {
+    if (!['accounts', 'categories', 'slugs'].includes(request.resource)) throw new Error('Unknown metrics discovery resource.');
+    const search = request.search ?? '';
+    if (search.length > METRIC_SEARCH_MAX_LENGTH) throw new Error(`Metrics search must be ${METRIC_SEARCH_MAX_LENGTH} characters or fewer.`);
+    const start = request.start ?? 0;
+    const size = request.size ?? METRIC_DISCOVERY_PAGE_SIZE;
+    if (!Number.isInteger(start) || start < 0) throw new Error('Metrics discovery start must be a non-negative integer.');
+    if (!Number.isInteger(size) || size < 1 || size > 500) throw new Error('Metrics discovery size must be between 1 and 500.');
+    if (request.resource === 'accounts') {
+        if (request.account !== undefined || request.category !== undefined) throw new Error('Account discovery does not accept account or category.');
+        return { resource: request.resource, search, start, size };
+    }
+    if (!request.account) throw new Error(`${request.resource === 'categories' ? 'Category' : 'Slug'} discovery requires an account.`);
+    if (request.resource === 'categories' && request.category !== undefined) throw new Error('Category discovery does not accept category.');
+    return { resource: request.resource, account: request.account, ...(request.category !== undefined ? { category: request.category } : {}), search, start, size };
+}
+
+function expectedFilters(resource: MetricsDiscoveryResource, request: ReturnType<typeof validateDiscoveryRequest>): MetricsDiscoveryFilters {
+    if (resource === 'accounts') return { search: request.search };
+    if (resource === 'categories') return { account: request.account, search: request.search };
+    return { account: request.account, category: request.category ?? null, search: request.search };
+}
+
+/** Exact #1438 envelope. `mojoCall` is required because list normalization drops its metadata. */
+export async function discoverMetrics(input: MetricsDiscoveryRequest): Promise<MetricsDiscoveryPage> {
+    const request = validateDiscoveryRequest(input);
+    const response = await mojoCall('/api/metrics/discover', { params: request as Params }) as Envelope & UnknownRecord;
+    if (response.resource !== request.resource) throw new Error('Malformed metrics discovery response: resource echo mismatch.');
+    const filters = record(response.filters, 'filters');
+    const expected = expectedFilters(request.resource, request);
+    sameKeys(filters, Object.keys(expected), 'filters');
+    for (const [key, value] of Object.entries(expected)) {
+        if (filters[key] !== value) throw new Error(`Malformed metrics discovery response: filters.${key} echo mismatch.`);
+    }
+    const data = stringArray(response.data, 'data');
+    const start = integer(response.start, 'start');
+    const size = integer(response.size, 'size', 1);
+    const count = integer(response.count, 'count');
+    const pageCount = integer(response.page_count, 'page_count');
+    if (pageCount !== data.length || start !== request.start || size !== request.size || pageCount > size || count < pageCount) {
+        throw new Error('Malformed metrics discovery response: paging metadata is inconsistent.');
+    }
+    const nextStart = response.next_start === null ? null : integer(response.next_start, 'next_start');
+    if ((nextStart == null) !== (start + pageCount >= count)) {
+        throw new Error('Malformed metrics discovery response: next_start is inconsistent.');
+    }
+    return { resource: request.resource, filters: expected, data, start, size, count, pageCount, nextStart };
+}
+
+function historyPayload(response: Envelope, expectedTails: readonly string[]): { labels: string[]; data: Record<string, number[]>; groups?: Record<string, number> } {
+    const payload = record(response.data, 'data');
+    const labels = stringArray(payload.labels, 'data.labels');
+    const values = record(payload.data, 'data.data');
+    sameKeys(values, expectedTails, 'data.data');
+    const data: Record<string, number[]> = {};
+    for (const tail of expectedTails) {
+        if (!Array.isArray(values[tail])) throw new Error(`Malformed metrics response: series ${tail} must be an array.`);
+        data[tail] = (values[tail] as unknown[]).map((entry, index) => finiteNumber(entry, `${tail}[${index}]`));
+        if (data[tail]!.length !== labels.length) throw new Error(`Malformed metrics response: series ${tail} length does not match labels.`);
+    }
+    let groups: Record<string, number> | undefined;
+    if (payload.groups !== undefined) {
+        const rawGroups = record(payload.groups, 'data.groups');
+        sameKeys(rawGroups, expectedTails, 'data.groups');
+        groups = Object.fromEntries(Object.entries(rawGroups).map(([key, value]) => [key, integer(value, `groups.${key}`, 1)]));
+    }
+    return { labels, data, groups };
+}
+
+async function requestHistory(params: MetricsFetchParams, slugs: readonly string[]) {
+    const wire: Params = { ...params, slugs: slugs.join(',') };
+    const response = await mojoCall('/api/metrics/fetch', { params: wire });
+    return historyPayload(response, slugs.map(metricSlugTail));
+}
+
+/**
+ * Safe `MetricsChart.loadSeries` implementation. It uses the request as the
+ * identity source, splits duplicate tails, and rejects every ambiguous echo.
+ */
+export async function loadExactMetricSeries(params: MetricsFetchParams): Promise<MetricsResponse> {
+    const slugs = dedupeMetricSlugs(params.slugs.split(','));
+    if (!slugs.length) throw new Error('Choose at least one metric slug.');
+    if (params.child_kind) {
+        if (parseMetricAccount(params.account).kind !== 'group') {
+            throw new Error('Group fan-out requires account=group-<parent-id>.');
+        }
+        if (!params.child_kind.trim()) throw new Error('Group fan-out requires a child kind.');
+    }
+    if (params.breakdown) {
+        if (slugs.length !== 1) throw new Error('Fan-out breakdown requires exactly one metric slug.');
+        if (!params.child_kind) throw new Error('Fan-out breakdown requires a child kind.');
+        const response = await mojoCall('/api/metrics/fetch', { params: { ...params, slugs: slugs[0] } });
+        const payload = record(response.data, 'data');
+        const childData = record(payload.data, 'data.data');
+        const result = historyPayload(response, Object.keys(childData));
+        if (!result.groups) throw new Error('Malformed fan-out breakdown: groups map is required.');
+        return {
+            labels: result.labels,
+            datasets: Object.keys(result.data).map((label) => ({ label, data: result.data[label]! })),
+            groups: result.groups,
+        } as MetricsBreakdownResponse;
+    }
+    const plans = planMetricHistoryRequests(slugs);
+    const bySlug = new Map<string, number[]>();
+    let labels: string[] | null = null;
+    for (const batch of plans) {
+        const result = await requestHistory(params, batch);
+        if (labels == null) labels = result.labels;
+        else if (labels.length !== result.labels.length || labels.some((label, index) => label !== result.labels[index])) {
+            throw new Error('Malformed metrics response: collision-split requests returned incompatible labels.');
+        }
+        for (const slug of batch) bySlug.set(slug, result.data[metricSlugTail(slug)]!);
+    }
+    if (bySlug.size !== slugs.length) throw new Error('Malformed metrics response: one or more requested series are missing.');
+    return { labels: labels ?? [], datasets: slugs.map((label) => ({ label, data: bySlug.get(label)! })) };
+}
+
+export interface FetchMetricPointsInput {
+    account: string;
+    slugs: string[];
+    when: number;
+    granularity: string;
+}
+
+/** `/series?with_delta=true` preserves full keys, so validate them directly. */
+export async function fetchMetricPoints(input: FetchMetricPointsInput): Promise<MetricPoint[]> {
+    const slugs = dedupeMetricSlugs(input.slugs);
+    if (!slugs.length) return [];
+    const response = await mojoCall('/api/metrics/series', {
+        params: { account: input.account, slugs: slugs.join(','), when: input.when, granularity: input.granularity, with_delta: true },
+    }) as Envelope & UnknownRecord;
+    const data = record(response.data, 'data');
+    const previous = record(response.prev_data, 'prev_data');
+    const deltas = record(response.deltas, 'deltas');
+    sameKeys(data, slugs, 'data');
+    sameKeys(previous, slugs, 'prev_data');
+    sameKeys(deltas, slugs, 'deltas');
+    return slugs.map((slug) => {
+        const delta = record(deltas[slug], `deltas.${slug}`);
+        const keys = Object.keys(delta);
+        if (!keys.includes('delta') || keys.some((key) => key !== 'delta' && key !== 'delta_pct')) {
+            throw new Error(`Malformed metrics response: delta keys for ${slug} are invalid.`);
+        }
+        return {
+            slug,
+            value: finiteNumber(data[slug], `data.${slug}`),
+            previous: finiteNumber(previous[slug], `prev_data.${slug}`),
+            delta: finiteNumber(delta.delta, `deltas.${slug}.delta`),
+            ...(delta.delta_pct === undefined ? {} : { deltaPct: finiteNumber(delta.delta_pct, `deltas.${slug}.delta_pct`) }),
+        };
+    });
+}
+
+/** `/value/get` truncates keys, so one exact full slug is read per call. */
+export async function readMetricValue(account: string, slug: string): Promise<MetricGaugeValue> {
+    const exact = slug.trim();
+    if (!exact) throw new Error('Scalar slug is required.');
+    assertAddressableMetricSlug(exact);
+    const response = await mojoCall('/api/metrics/value/get', { params: { account, slugs: exact } }) as Envelope & UnknownRecord;
+    const data = record(response.data, 'data');
+    const tail = metricSlugTail(exact);
+    sameKeys(data, [tail], 'data');
+    const echoedSlugs = stringArray(response.slugs, 'slugs');
+    if (echoedSlugs.length !== 1 || echoedSlugs[0] !== exact || response.account !== account) {
+        throw new Error('Malformed scalar response: request echo mismatch.');
+    }
+    return { account, slug: exact, value: data[tail] };
+}