toiljs 0.0.84 → 0.0.86

package/docs/auth/usage.md

@@ -0,0 +1,188 @@
+# Using auth
+
+## 1. Enable it
+
+Either the config flag (canonical) or a one-line import — both do the same thing (the build appends the
+framework's auth controller + user shape to your server as compiled entries, so `/auth/*` self-mounts):
+
+```ts
+// toil.config.ts  — canonical
+export default defineConfig({ server: { auth: true } });
+```
+
+```ts
+// server/main.ts  — escape hatch (equivalent)
+import 'toiljs/server/auth';
+```
+
+There is also an `AuthService.enable()` no-op you can call for discoverability, but enabling is done by the
+flag/import above (it happens at build time). Turn it off by removing the flag/import — with neither, no
+`/auth` routes and no accounts collection are generated. It is strictly opt-in.
+
+## 2. The client
+
+`toiljs/client` ships the browser half — it runs the OPRF blinding, Argon2id, ML-DSA keygen, and ML-KEM
+encapsulation, and talks to `/auth/*`. You never touch the crypto.
+
+```ts
+import { Auth } from 'toiljs/client';
+
+// Create an account. Throws on a taken username or a transport error.
+await Auth.register(username, password);
+
+// Log in. On success the browser holds the signed session cookie; subsequent
+// requests to @auth routes are authorized automatically.
+await Auth.login(username, password);
+```
+
+Options (second argument, `AuthOptions`):
+
+```ts
+await Auth.login(username, password, {
+    baseUrl: '/auth',                 // default; change if you mount elsewhere
+    serverKemPublicKey: MY_KEM_PUB,   // REQUIRED in production — pin your deployment's KEM key
+});
+```
+
+> **Production:** the client ships with the DEV KEM public key pinned. A real deployment MUST pass its own
+> `serverKemPublicKey` (derived from `AUTH_KEM_SK`). See [Configuration](./configuration.md).
+
+## 2b. Client-side: who's logged in, and protecting pages
+
+`register`/`login` set the session cookies; to *render* login state on the client, use the generated
+`getUser()` (emitted from the built-in `@user`). It reads the **readable** `__Secure-toil_user` companion
+cookie and returns the typed user or `null` — instant, no network call. It is **display-only**; the server
+still enforces access via `@auth`, so never trust it for authorization.
+
+```tsx
+import { getUser } from 'shared/server';   // generated; typed to the built-in @user
+
+function Nav() {
+    const user = getUser();                // { toilUserId, username } | null
+    return user
+        ? <span>Hi {user.username} <button onClick={logout}>Log out</button></span>
+        : <a href="/login">Log in</a>;
+}
+
+async function logout() {
+    await fetch('/auth/logout', { method: 'POST' });
+    location.href = '/login';              // cookies are cleared; bounce to login
+}
+```
+
+Gate a whole client route by redirecting when there's no session:
+
+```tsx
+export default function Dashboard() {
+    const user = getUser();
+    if (user == null) { location.href = '/login'; return null; }   // not logged in -> to /login
+    return <main>Welcome, {user.username}</main>;
+}
+```
+
+The authoritative check is still the server: any data this page fetches should come from an `@auth` route,
+so a user who forged/deleted the readable cookie sees the redirect OR a `401`, never real data.
+
+## 2c. Handling errors
+
+`Auth.register` / `Auth.login` reject with a message you can show. The important distinguishable cases:
+
+```ts
+try {
+    await Auth.register(username, password);
+} catch (e) {
+    const m = String(e);
+    if (m.includes('already registered')) setError('That username is taken — log in instead.');
+    else setError('Could not register, try again.');
+}
+
+try {
+    await Auth.login(username, password);
+} catch {
+    // Wrong password OR unknown user both fail generically (anti-enumeration) — one message.
+    setError('Incorrect username or password.');
+}
+```
+
+- **Username taken** → `register` throws `auth: username already registered (log in instead)` (a
+  distinguishable case so you can guide the user).
+- **Wrong password / unknown user** → `login` throws generically (`auth: request failed`) — by design,
+  the two are indistinguishable, so use ONE "incorrect username or password" message.
+- **Rate limited** → after 5 attempts / 60s a `429` surfaces as the same generic throw; back off and tell
+  the user to wait.
+
+## 3. Guard your routes — `@auth`
+
+Put `@auth` on a route method or a whole `@rest` class. The generated dispatcher checks for a valid signed
+session **before** your handler runs and returns `401` otherwise. `@auth` is unchanged by built-in auth —
+it's the same decorator you'd use with hand-written auth.
+
+```ts
+@rest('account')
+class AccountApi {
+    @auth                       // this route needs a session
+    @get('/settings')
+    public settings(): Response { /* … */ }
+
+    @get('/public')             // this one is open
+    public open(): Response { /* … */ }
+}
+
+@auth                           // …or guard the ENTIRE class
+@rest('admin')
+class AdminApi { /* every route requires a session */ }
+```
+
+## 4. Read the current user
+
+Inside any handler:
+
+```ts
+// The typed logged-in user (the built-in `@user`: toilUserId + username), or null.
+const user = AuthService.getUser();
+if (user != null) {
+    user.username;    // string
+    user.toilUserId;  // Uint8Array(32) — the stable id bytes
+}
+
+// The stable identity as a ToilUserId (gate on hasSession() first — see note).
+if (AuthService.hasSession()) {
+    const id = AuthService.userId()!;   // ToilUserId
+    // key your own data on id (see Extending)
+}
+```
+
+> `ToilUserId` overloads `==`, so `AuthService.userId() == null` does not type-check. Gate with
+> `AuthService.hasSession()` and then use `userId()!`, or use `getUser()` and null-check that.
+
+## 5. The endpoint wire contract
+
+You normally use the `Auth` client, but the raw endpoints are binary (`DataWriter`/`DataReader`, never
+JSON):
+
+| Route | Request body | Response |
+| --- | --- | --- |
+| `POST /auth/register/start` | `str(username) bytes(blinded)` | `u8(0) u32(mem) u32(iters) u32(par) bytes(salt) bytes(evaluated)` |
+| `POST /auth/register/finish` | `str(username) bytes(pubkey) bytes(proof)` | `u8(status)` — `0` ok, `1` username taken |
+| `POST /auth/login/start` | `str(username) bytes(blinded)` | `bytes(cid) str(aud) u32(mem) u32(iters) u32(par) bytes(salt) bytes(nonce) u64(iat) u64(exp) bytes(evaluated)` |
+| `POST /auth/login/finish` | `bytes(cid) bytes(ct) bytes(sig)` | `u8(0) bytes(sessionToken) bytes(serverConfirm)` + `Set-Cookie`, or `u8(≠0)` on failure |
+| `GET /auth/me` *(`@auth`)* | — | `bytes(toilUserId) str(username)` |
+| `POST /auth/logout` *(`@auth`)* | — | `200` + cookie-clearing `Set-Cookie` |
+
+Rate limiting: every register/login POST carries `@ratelimit(SlidingWindow, 5, 60)` (5 requests / 60s per
+client) out of the box, so brute-force is throttled before it reaches the crypto.
+
+## 6. Under `toiljs dev`
+
+Everything runs locally with **zero setup**: the dev server emulates the ToilDB account/challenge storage
+and the ML-DSA/ML-KEM/OPRF host functions in process, and the auth secrets fall back to insecure DEV
+values. Register and login span requests (the accounts persist for the dev session). You'll see a warning
+that `AUTH_SESSION_SECRET` is unset — that's expected in dev; set it before you deploy (see
+[Configuration](./configuration.md)).
+
+## 7. `Server.REST.auth.*`
+
+Because the controller is a normal `@rest('auth')` class, a typed `Server.REST.auth.*` fetch client is
+generated for free (`me`, `logout`, and the register/login methods). Use it for `/me` and `/logout`; but
+**drive register/login through `toiljs/client` `Auth`**, not the generated client — only the `Auth` helper
+runs the required browser-side OPRF/Argon2id/ML-DSA/ML-KEM crypto.

package/docs/auth.md

@@ -1,5 +1,11 @@
 # Auth, sessions, and `@user`
 
+> **Just want login working?** Enable **built-in auth** with one line — `server: { auth: true }` — and
+> you get the whole `/auth/*` API + sessions with no code. Start at **[the auth guide](./auth/index.md)**
+> ([how it works](./auth/how-it-works.md) · [usage](./auth/usage.md) · [configuration](./auth/configuration.md) ·
+> [extending](./auth/extending.md)). This page is the deeper reference on the underlying primitives, used
+> both by built-in auth and when you hand-write your own.
+
 toiljs ships **Toil PQ-Auth**: a post-quantum password login where the password
 never leaves the browser and the server stores only public verifier material.
 On top of it sit HMAC-signed session cookies, a `@auth` route guard, and a

package/examples/basic/client/routes/analytics.tsx

@@ -1,53 +1,191 @@
-// Demo of the per-domain Analytics API. `Server.REST.analytics.self()` is the real, typed
-// fetch client generated from the `@rest` controller in server/routes/Analytics.ts; the route
-// reads the toilscript `Analytics.self()` snapshot. Under `toiljs dev` the dev server returns
-// sample data; at the edge the same code reads the real metering.
-import { useState } from 'react';
+// Demo of the per-domain Analytics API + the historical time-series (graphs).
+//
+//   Server.REST.analytics.self()                                -> the current snapshot (typed getters)
+//   Server.REST.analytics.series({ query: { metric, range } })  -> a metric's history for a range
+//
+// Both are the real, typed fetch clients generated from the `@rest` controller in
+// server/routes/Analytics.ts, which reads the toilscript `Analytics.self()` / `Analytics.series()` API.
+// Under `toiljs dev` the dev server returns sample data; at the edge the SAME code reads the real
+// metering rings. The chart is a self-contained inline SVG (no chart library).
+import { useEffect, useState } from 'react';
 
-import { SiteAnalytics } from 'shared/server';
+import { SeriesData, SiteAnalytics } from 'shared/server';
 
 export const metadata: Toil.Metadata = {
     title: 'Analytics',
-    description: "This site's own analytics via the toilscript Analytics.self() API."
+    description: "This site's own analytics + historical graphs via the toilscript Analytics API."
 };
 
+// MetricId (mirrors the server enum). Only the graph-worthy ones are listed for the picker.
+const METRICS = [
+    { id: 0, label: 'Requests', unit: 'count' },
+    { id: 1, label: 'Bytes out (L1)', unit: 'bytes' },
+    { id: 2, label: 'Bytes in (L1)', unit: 'bytes' },
+    { id: 12, label: 'Gas used', unit: 'count' },
+    { id: 13, label: 'DB ops', unit: 'count' },
+    { id: 26, label: 'Stream bytes out', unit: 'bytes' },
+    { id: 39, label: 'Memory bandwidth', unit: 'bytes' },
+    { id: 41, label: 'Cache hits', unit: 'count' },
+    { id: 42, label: 'Cache misses', unit: 'count' },
+    { id: 43, label: 'Connected streams', unit: 'count' },
+    { id: 45, label: 'Committed memory', unit: 'bytes' }
+] as const;
+
+// AnalyticsRange (mirrors the server enum).
+const RANGES = [
+    { id: 0, label: '1h' },
+    { id: 1, label: '6h' },
+    { id: 3, label: '24h' },
+    { id: 5, label: '7d' },
+    { id: 7, label: '30d' }
+] as const;
+
+type Unit = 'count' | 'bytes';
+
+function fmt(n: number, unit: Unit): string {
+    if (unit === 'bytes') {
+        const u = ['B', 'KB', 'MB', 'GB'];
+        let i = 0;
+        while (n >= 1024 && i < u.length - 1) {
+            n /= 1024;
+            i++;
+        }
+        return `${n.toFixed(i === 0 ? 0 : 1)} ${u[i]}`;
+    }
+    return n >= 1000 ? `${(n / 1000).toFixed(1)}k` : String(Math.round(n));
+}
+
+/** A dependency-free SVG line chart of the per-second rate (value / bucketSecs). */
+function LineChart({ points, bucketSecs, unit }: { points: number[]; bucketSecs: number; unit: Unit }) {
+    const W = 640;
+    const H = 220;
+    const pad = 40;
+    const rate = points.map((v) => (bucketSecs > 0 ? v / bucketSecs : 0));
+    const max = Math.max(1, ...rate);
+    const n = rate.length;
+    const x = (i: number) => pad + (n <= 1 ? 0 : (i / (n - 1)) * (W - 2 * pad));
+    const y = (v: number) => H - pad - (v / max) * (H - 2 * pad);
+    const line = rate.map((v, i) => `${i === 0 ? 'M' : 'L'}${x(i).toFixed(1)},${y(v).toFixed(1)}`).join(' ');
+    const area = `${line} L${x(n - 1).toFixed(1)},${H - pad} L${x(0).toFixed(1)},${H - pad} Z`;
+
+    return (
+        <svg
+            viewBox={`0 0 ${W} ${H}`}
+            width="100%"
+            role="img"
+            aria-label="time series chart"
+            style={{ maxWidth: W, background: '#0b0f19', borderRadius: 8 }}>
+            <line x1={pad} y1={H - pad} x2={W - pad} y2={H - pad} stroke="#33415580" />
+            <line x1={pad} y1={pad} x2={pad} y2={H - pad} stroke="#33415580" />
+            <text x={6} y={pad + 4} fill="#94a3b8" fontSize={11}>
+                {fmt(max, unit)}/s
+            </text>
+            <text x={6} y={H - pad} fill="#94a3b8" fontSize={11}>
+                0
+            </text>
+            {n > 0 && <path d={area} fill="#38bdf822" />}
+            {n > 1 && <path d={line} fill="none" stroke="#38bdf8" strokeWidth={2} />}
+            {n === 1 && <circle cx={x(0)} cy={y(rate[0])} r={3} fill="#38bdf8" />}
+        </svg>
+    );
+}
+
 export default function AnalyticsDemo() {
     const [stats, setStats] = useState<SiteAnalytics | null>(null);
+    const [series, setSeries] = useState<SeriesData | null>(null);
+    const [metric, setMetric] = useState(0);
+    const [range, setRange] = useState(3);
     const [err, setErr] = useState('');
 
-    const load = async () => {
+    const loadStats = async () => {
         try {
-            setStats(await Server.REST.analytics.self());
+            setStats(await Server.REST.analyticsRoutes.self());
             setErr('');
         } catch (e) {
             setErr(parseError(e));
         }
     };
 
+    // Refetch the graph whenever the metric or range changes.
+    useEffect(() => {
+        Server.REST.analyticsRoutes
+            .series({ query: { metric, range } })
+            .then(setSeries)
+            .catch((e: unknown) => setErr(parseError(e)));
+    }, [metric, range]);
+
     const cap = (used: bigint, max: bigint) => `${used} / ${max ? String(max) : '∞'}`;
+    const meta = METRICS.find((m) => m.id === metric) ?? METRICS[0];
+    const points = series ? series.points.map(Number) : [];
 
     return (
         <main>
             <h1>Analytics</h1>
             <p>
-                <code>Server.REST.analytics.self()</code> reads this site's own analytics via the toilscript{' '}
-                <code>Analytics.self()</code> API (the per-domain metering counters + plan limits). Under{' '}
-                <code>toiljs dev</code> you get sample data; at the edge it is the real metering, with the same code.
+                <code>analytics.self()</code> reads this site's snapshot; <code>analytics.series(metric, range)</code>{' '}
+                reads the historical rings (30-day retention). Under <code>toiljs dev</code> you get sample data; at
+                the edge it is the real metering, same code.
             </p>
-            <button onClick={load}>Load my site analytics</button>
-            {err && <p>{err}</p>}
-            {stats && (
-                <ul>
-                    <li>requests: {String(stats.requests)}</li>
-                    <li>bytes served: {String(stats.bytesServed)}</li>
-                    <li>2xx responses: {String(stats.status2xx)}</li>
-                    <li>wasm dispatches: {String(stats.wasmDispatches)}</li>
-                    <li>db ops: {String(stats.dbOps)}</li>
-                    <li>requests this minute: {cap(stats.reqMinuteUsed, stats.reqMinuteCap)}</li>
-                    <li>requests today: {cap(stats.reqDayUsed, stats.reqDayCap)}</li>
-                </ul>
-            )}
-            <p>
+
+            <section>
+                <h2>History</h2>
+                <div style={{ display: 'flex', gap: 12, alignItems: 'center', flexWrap: 'wrap', marginBottom: 8 }}>
+                    <label>
+                        Metric{' '}
+                        <select value={metric} onChange={(e) => setMetric(Number(e.currentTarget.value))}>
+                            {METRICS.map((m) => (
+                                <option key={m.id} value={m.id}>
+                                    {m.label}
+                                </option>
+                            ))}
+                        </select>
+                    </label>
+                    <label>
+                        Range{' '}
+                        <select value={range} onChange={(e) => setRange(Number(e.currentTarget.value))}>
+                            {RANGES.map((r) => (
+                                <option key={r.id} value={r.id}>
+                                    {r.label}
+                                </option>
+                            ))}
+                        </select>
+                    </label>
+                    <span style={{ color: '#64748b' }}>
+                        {series ? `${series.points.length} buckets · ${series.bucketSecs}s each` : ''}
+                    </span>
+                </div>
+                <LineChart points={points} bucketSecs={series?.bucketSecs ?? 3600} unit={meta.unit} />
+            </section>
+
+            <section style={{ marginTop: 24 }}>
+                <h2>Snapshot</h2>
+                <p style={{ color: '#64748b', marginTop: 0 }}>
+                    All <code>total*</code> values are all-time cumulative totals (since the site was first seen);
+                    the <code>live</code> gauges are the current level, and the windows are the current rate-limit
+                    usage vs the plan cap (cap ∞ = unlimited).
+                </p>
+                <button onClick={loadStats}>Load my site analytics</button>
+                {err && <p style={{ color: '#f87171' }}>{err}</p>}
+                {stats && (
+                    <ul>
+                        <li>total requests: {String(stats.totalRequests)}</li>
+                        <li>total bytes out (L1): {String(stats.totalBytesOutL1)}</li>
+                        <li>total bytes in (L1): {String(stats.totalBytesInL1)}</li>
+                        <li>total gas used: {String(stats.totalGasUsed)}</li>
+                        <li>total 2xx responses: {String(stats.totalStatus2xx)}</li>
+                        <li>total db ops: {String(stats.totalDbOps)}</li>
+                        <li>total cache hits: {String(stats.totalCacheHits)}</li>
+                        <li>total cache misses: {String(stats.totalCacheMisses)}</li>
+                        <li>cache hit ratio: {(stats.cacheHitRatio * 100).toFixed(1)}%</li>
+                        <li>connected streams (live): {String(stats.liveConnectedStreams)}</li>
+                        <li>committed memory (live): {fmt(Number(stats.liveCommittedMemoryBytes), 'bytes')}</li>
+                        <li>requests this minute: {cap(stats.requestsThisMinute, stats.requestsThisMinuteCap)}</li>
+                        <li>requests today: {cap(stats.requestsToday, stats.requestsTodayCap)}</li>
+                    </ul>
+                )}
+            </section>
+
+            <p style={{ marginTop: 24 }}>
                 <Toil.Link href="/">Back home</Toil.Link>
             </p>
         </main>

package/examples/basic/server/models/SiteAnalytics.ts

@@ -1,14 +1,142 @@
-/** This site's own analytics, mapped from the toilscript `Analytics.self()` snapshot for the
- *  client. Counts + usage are i64; the rate-limit caps are i64 too (0 = unlimited). */
+/**
+ * This site's own analytics snapshot, mapped 1:1 from the toilscript `Analytics.self()` frame.
+ *
+ * Every `total*` field is an ALL-TIME CUMULATIVE COUNT — a running total since the site was first
+ * seen, monotonically increasing, never reset by a query. They are NOT "last hour" or "last minute":
+ * for time-windowed history use the separate `SeriesData` time-series (`/series`).
+ *
+ * All counter fields are `u64` (the guest exposes `u64` getters, so the mapping needs zero casts). The
+ * `live*` gauges are the current instantaneous level (not a total). The request-window fields are the
+ * current rate-limit bucket usage paired with the plan cap (cap `0` = unlimited).
+ */
 @data
 export class SiteAnalytics {
-    requests: i64 = 0;
-    bytesServed: i64 = 0;
-    status2xx: i64 = 0;
-    wasmDispatches: i64 = 0;
-    dbOps: i64 = 0;
-    reqMinuteUsed: i64 = 0;
-    reqMinuteCap: i64 = 0;
-    reqDayUsed: i64 = 0;
-    reqDayCap: i64 = 0;
+    // --- Requests / L1 edge (all-time totals) ---
+    /** Total HTTP requests served, all-time. */
+    totalRequests: u64 = 0;
+    /** Total response bytes sent from the L1 edge, all-time. */
+    totalBytesOutL1: u64 = 0;
+    /** Total request bytes received at the L1 edge, all-time. */
+    totalBytesInL1: u64 = 0;
+    /** Total 2xx responses, all-time. */
+    totalStatus2xx: u64 = 0;
+    /** Total 3xx responses, all-time. */
+    totalStatus3xx: u64 = 0;
+    /** Total 4xx responses, all-time. */
+    totalStatus4xx: u64 = 0;
+    /** Total 5xx responses, all-time. */
+    totalStatus5xx: u64 = 0;
+    /** Total static-asset hits (served without a wasm dispatch), all-time. */
+    totalStaticHits: u64 = 0;
+    /** Total wasm handler dispatches, all-time. */
+    totalWasmDispatches: u64 = 0;
+    /** Total requests rejected because the executor pool was full, all-time. */
+    totalExecutorFullRejects: u64 = 0;
+    /** Total requests rejected for an unknown host, all-time. */
+    totalUnknownHostRejects: u64 = 0;
+    /** Total requests rejected by rate limiting, all-time. */
+    totalRateLimitedRejects: u64 = 0;
+    /** Total wasm gas consumed across all dispatches, all-time. */
+    totalGasUsed: u64 = 0;
+
+    // --- Database (all-time totals) ---
+    /** Total ToilDB operations issued, all-time. */
+    totalDbOps: u64 = 0;
+    /** Total ToilDB read operations, all-time. */
+    totalDbReads: u64 = 0;
+    /** Total ToilDB write operations, all-time. */
+    totalDbWrites: u64 = 0;
+    /** Total ToilDB operations that errored, all-time. */
+    totalDbErrors: u64 = 0;
+    /** Summed host-observed ToilDB op latency in nanoseconds, all-time (divide by totalDbOps for a mean). */
+    totalDbLatencyNsSum: u64 = 0;
+
+    // --- Streams / WebTransport (all-time totals) ---
+    /** Total stream connections accepted, all-time. */
+    totalStreamAccepts: u64 = 0;
+    /** Total streams rejected because they landed on the wrong node, all-time. */
+    totalStreamRejectWrongNode: u64 = 0;
+    /** Total streams rejected for capacity, all-time. */
+    totalStreamRejectCapacity: u64 = 0;
+    /** Total streams rejected for a missing/invalid artifact, all-time. */
+    totalStreamRejectArtifact: u64 = 0;
+    /** Total streams rejected by the guest, all-time. */
+    totalStreamRejectGuest: u64 = 0;
+    /** Total stream guest traps, all-time. */
+    totalStreamTraps: u64 = 0;
+    /** Total streams closed for idle timeout, all-time. */
+    totalStreamIdleTimeouts: u64 = 0;
+    /** Total bytes received on streams, all-time. */
+    totalStreamBytesIn: u64 = 0;
+    /** Total bytes sent on streams, all-time. */
+    totalStreamBytesOut: u64 = 0;
+    /** Total stream backpressure events, all-time. */
+    totalStreamBackpressureEvents: u64 = 0;
+    /** Total clean stream closes, all-time. */
+    totalStreamCloses: u64 = 0;
+    /** Total stream disconnects (abrupt), all-time. */
+    totalStreamDisconnects: u64 = 0;
+
+    // --- Daemons / L4 (all-time totals) ---
+    /** Total daemon starts, all-time. */
+    totalDaemonStarts: u64 = 0;
+    /** Total daemon start failures, all-time. */
+    totalDaemonStartFailures: u64 = 0;
+    /** Total daemon ticks fired, all-time. */
+    totalDaemonTicksFired: u64 = 0;
+    /** Total daemon ticks skipped because this node was not the leader, all-time. */
+    totalDaemonTicksSkippedNotLeader: u64 = 0;
+    /** Total daemon ticks that failed, all-time. */
+    totalDaemonTicksFailed: u64 = 0;
+    /** Total daemon leadership acquisitions, all-time. */
+    totalDaemonLeaderAcquires: u64 = 0;
+    /** Total daemon leadership fences (lost leadership), all-time. */
+    totalDaemonLeaderFenced: u64 = 0;
+    /** Total daemon outbound http_call attempts, all-time. */
+    totalDaemonHttpCallAttempts: u64 = 0;
+    /** Total daemon outbound http_call failures, all-time. */
+    totalDaemonHttpCallFailures: u64 = 0;
+
+    // --- Memory / email / cache (all-time totals) ---
+    /** Total wasm linear-memory bytes grown, all-time. */
+    totalMemGrownBytes: u64 = 0;
+    /** Total emails sent, all-time. */
+    totalEmails: u64 = 0;
+    /** Total responses served from the edge cache, all-time. */
+    totalCacheHits: u64 = 0;
+    /** Total cacheable responses that missed the edge cache, all-time. */
+    totalCacheMisses: u64 = 0;
+
+    // --- Derived ---
+    /** Fraction of cacheable responses served from cache: hits / (hits + misses), in 0..1. 0 when there
+     *  were no cacheable responses. */
+    cacheHitRatio: f64 = 0;
+
+    // --- Live gauges (current instantaneous level, NOT a total) ---
+    /** Streams currently connected right now. */
+    liveConnectedStreams: u64 = 0;
+    /** Wasm linear memory currently committed right now, in bytes. */
+    liveCommittedMemoryBytes: u64 = 0;
+
+    // --- Request windows: current rate-limit usage vs plan cap (cap 0 = unlimited) ---
+    /** Requests used in the current 1-minute window. */
+    requestsThisMinute: u64 = 0;
+    /** Plan cap for the 1-minute window (0 = unlimited). */
+    requestsThisMinuteCap: u64 = 0;
+    /** Requests used in the current 24-hour window. */
+    requestsToday: u64 = 0;
+    /** Plan cap for the 24-hour window (0 = unlimited). */
+    requestsTodayCap: u64 = 0;
+}
+
+/** One metric's historical TIME-SERIES for a range, from `Analytics.series(metric, range)`: the raw
+ *  per-bucket totals (oldest→newest) plus the bucket width + newest-bucket end, so the client can draw a
+ *  graph and derive per-second rates. This is per-bucket HISTORY — distinct from the all-time totals in
+ *  `SiteAnalytics`. Demonstrates the typed series API. */
+@data
+export class SeriesData {
+    metric: i32 = 0;
+    bucketSecs: u32 = 0;
+    headMs: u64 = 0;
+    points: i64[] = [];
 }