pgkiln 0.70.0 → 0.72.0

package/src/history.ts

@@ -0,0 +1,155 @@
+// (sprint 138, AP-5) Change history per component (APEX: Application Utilities ›
+// Change History) and application checksums (APEX: Application Checksum).
+//
+// meta.app_snapshot keeps an application's export after its last recorded
+// change. After a builder change (app-updates.ts, onSend) and inside an import
+// --replace (cli/replace.ts: restores, merges, the command line and the MCP
+// server), recordHistory() exports the application again, splits both exports
+// into components the way working copies compare them (workingcopy.ts
+// components(): a region with its SQL, a page's settings, a list of values, …)
+// and stores each added, changed or deleted component with its files before and
+// after in meta.component_change (migration 138). The first change of an
+// application without a snapshot has nothing to compare with: ensureSnapshot()
+// takes one before a builder POST runs (a preHandler hook).
+//
+// appChecksum(): a SHA-256 over the export's files (the text layout, without the
+// format marker and with the alias blanked), so two installations, or an
+// application and its working copy, compare at a glance; pageChecksums() per page.
+import { createHash } from 'node:crypto';
+import type pg from 'pg';
+import { docToFiles, MARKER, type Doc, type FileMap } from './appfiles.ts';
+import { owner } from './db.ts';
+import { components, describe } from './workingcopy.ts';
+
+type Db = { query: (sql: string, params?: unknown[]) => Promise<pg.QueryResult<any>> };
+
+/** Days a change stays in the history (CHANGE_HISTORY_DAYS, default 365; 0 keeps everything). */
+export const historyDays = () => {
+  const n = Number(process.env.CHANGE_HISTORY_DAYS ?? 365);
+  return Number.isFinite(n) && n >= 0 ? Math.floor(n) : 365;
+};
+
+/** The export as files of the text layout (SQL inline in YAML: readable diffs), the alias blanked. */
+export function appFiles(doc: Doc): FileMap {
+  const d = { ...doc, app: { ...(doc.app ?? {}), alias: '' } };
+  const files = docToFiles(d, 'text');
+  files.delete(MARKER);
+  return files;
+}
+
+const isText = (b: Buffer) => !b.subarray(0, 8000).includes(0);
+const asText = (files: Map<string, Buffer> | undefined) =>
+  files ? Object.fromEntries([...files].map(([p, b]) => [p, isText(b) ? b.toString('utf8') : `(binary, ${b.length} bytes, sha256 ${createHash('sha256').update(b).digest('hex').slice(0, 16)})`])) : null;
+
+const sameFiles = (a?: Map<string, Buffer>, b?: Map<string, Buffer>) => {
+  if (!a || !b) return !a && !b;
+  if (a.size !== b.size) return false;
+  for (const [p, buf] of a) if (!b.get(p)?.equals(buf)) return false;
+  return true;
+};
+
+export interface ComponentDiff {
+  component: string;
+  label: string;
+  page: number | null;
+  op: 'added' | 'changed' | 'deleted';
+  before: Record<string, string> | null;
+  after: Record<string, string> | null;
+}
+
+/** The components that differ between two exports. */
+export function diffDocs(before: Doc, after: Doc): ComponentDiff[] {
+  const a = components(appFiles(before)), b = components(appFiles(after));
+  const out: ComponentDiff[] = [];
+  for (const id of [...new Set([...a.keys(), ...b.keys()])].sort()) {
+    const x = a.get(id), y = b.get(id);
+    if (sameFiles(x, y)) continue;
+    const { label, page } = describe(id);
+    out.push({ component: id, label, page, op: !x ? 'added' : !y ? 'deleted' : 'changed', before: asText(x), after: asText(y) });
+  }
+  return out;
+}
+
+const exportDoc = async (db: Db, appId: number): Promise<Doc | null> =>
+  (await db.query('select meta.export_app(alias) as d from meta.app where id = $1', [appId])).rows[0]?.d ?? null;
+
+/** Take a first snapshot of an application that has none (before its first recorded change); with `db`, inside its transaction. */
+export async function ensureSnapshot(appId: number, db?: pg.ClientBase) {
+  const sql = `insert into meta.app_snapshot (app_id, doc) select id, meta.export_app(alias) from meta.app
+                where id = $1 and not exists (select 1 from meta.app_snapshot where app_id = $1)
+               on conflict (app_id) do nothing`;
+  if (!db) return void (await owner.query(sql, [appId]));
+  await db.query('savepoint history_snapshot');
+  try {
+    await db.query(sql, [appId]);
+    await db.query('release savepoint history_snapshot');
+  } catch {
+    await db.query('rollback to savepoint history_snapshot');
+  }
+}
+
+/**
+ * Compare the application with its snapshot, record what changed and keep the new snapshot.
+ * With `db` a client in the caller's transaction (an import --replace), else a transaction of its own.
+ */
+export async function recordHistory(appId: number, changedBy: string | null, source: 'builder' | 'import' | 'upgrade' = 'builder', db?: pg.ClientBase): Promise<number> {
+  const run = async (c: Db) => {
+    // one change at a time per application: the snapshot row is the lock
+    const snap = (await c.query('select doc from meta.app_snapshot where app_id = $1 for update', [appId])).rows[0];
+    const now = await exportDoc(c, appId);
+    if (!now) return 0;
+    if (!snap) {
+      await c.query('insert into meta.app_snapshot (app_id, doc) values ($1, $2) on conflict (app_id) do update set doc = excluded.doc, taken_at = now()', [appId, now]);
+      return 0;
+    }
+    const changes = diffDocs(snap.doc, now);
+    if (!changes.length) return 0;
+    await c.query(
+      `insert into meta.component_change (app_id, component, label, page_no, op, before, after, changed_by, source)
+       select $1, x.component, x.label, x.page, x.op, x.before, x.after, $2, $3
+         from jsonb_to_recordset($4::jsonb) as x(component text, label text, page int, op text, before jsonb, after jsonb)`,
+      [appId, changedBy?.slice(0, 200) ?? null, source, JSON.stringify(changes)],
+    );
+    await c.query('update meta.app_snapshot set doc = $2, taken_at = now() where app_id = $1', [appId, now]);
+    const days = historyDays();
+    if (days) await c.query(`delete from meta.component_change where app_id = $1 and changed_at < now() - make_interval(days => $2)`, [appId, days]);
+    return changes.length;
+  };
+  if (db) {
+    await db.query('savepoint history');
+    try {
+      const n = await run(db);
+      await db.query('release savepoint history');
+      return n;
+    } catch (e) {
+      await db.query('rollback to savepoint history');
+      throw e;
+    }
+  }
+  return owner.tx(run);
+}
+
+/** SHA-256 of a set of files (paths and contents, in path order). */
+function hashFiles(files: [string, Buffer][]) {
+  const h = createHash('sha256');
+  for (const [p, b] of files.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) h.update(p).update('\0').update(b).update('\0');
+  return h.digest('hex');
+}
+
+/** The application checksum of an export (the same definition gives the same checksum on any installation). */
+export const appChecksum = (doc: Doc) => hashFiles([...appFiles(doc)]);
+
+/** A checksum per page: page number → the hash of the page's files. */
+export function pageChecksums(doc: Doc): Map<number, string> {
+  const byPage = new Map<number, [string, Buffer][]>();
+  for (const [id, files] of components(appFiles(doc))) {
+    const page = id.startsWith('pages/') ? describe(id).page : null;
+    if (page === null) continue;
+    if (!byPage.has(page)) byPage.set(page, []);
+    byPage.get(page)!.push(...files);
+  }
+  return new Map([...byPage].sort(([a], [b]) => a - b).map(([p, f]) => [p, hashFiles(f)]));
+}
+
+/** A short form for display (the first 16 hex digits). */
+export const shortSum = (sum: string) => sum.slice(0, 16);

package/src/instance-checks.ts

@@ -36,16 +36,23 @@ export interface SecretColumn {
   schema: string;
   table: string;
   column: string;
+  /** (sprint 139) only the rows that match (meta.setting: the settings named *_enc) */
+  where?: string;
 }
 
+/** (sprint 139) instance settings that hold a secret: meta.instance_setting rows named *_enc (otel_headers_enc) */
+const SETTING_SECRETS: SecretColumn = { schema: 'meta', table: 'instance_setting', column: 'value', where: `name like '%\\_enc'` };
+
 export async function encryptedColumns(): Promise<SecretColumn[]> {
-  return (await owner.query<SecretColumn>(
+  return [...(await owner.query<SecretColumn>(
     `select table_schema as schema, table_name as table, column_name as column from information_schema.columns
       where table_schema = 'meta' and data_type = 'text'
         and (column_name like '%\\_enc' or (table_name = 'push_key' and column_name = 'private_key'))
-      order by 2, 3`)).rows;
+      order by 2, 3`)).rows, SETTING_SECRETS];
 }
 
+const rowsOf = (c: SecretColumn) => `${quoteIdent(c.column)} is not null${c.where ? ` and (${c.where})` : ''}`;
+
 const quoteIdent = (s: string) => `"${s.replace(/"/g, '""')}"`;
 const tableOf = (c: SecretColumn) => `${quoteIdent(c.schema)}.${quoteIdent(c.table)}`;
 
@@ -54,7 +61,7 @@ export async function secretStatus(withKey?: string) {
   const out: (SecretColumn & { stored: number; unreadable: number })[] = [];
   const usable = (withKey ?? process.env.PGKILN_SECRET_KEY ?? '').length >= 32;
   for (const c of await encryptedColumns()) {
-    const rows = (await owner.query<{ v: string }>(`select ${quoteIdent(c.column)} as v from ${tableOf(c)} where ${quoteIdent(c.column)} is not null`)).rows;
+    const rows = (await owner.query<{ v: string }>(`select ${quoteIdent(c.column)} as v from ${tableOf(c)} where ${rowsOf(c)}`)).rows;
     let unreadable = 0;
     for (const r of rows) {
       try {
@@ -228,7 +235,7 @@ export async function rotateKey(oldKey: string, newKey: string, { dryRun = false
     const failed: string[] = [];
     for (const col of cols) {
       const rows = (await c.query<{ ctid: string; v: string }>(
-        `select ctid::text as ctid, ${quoteIdent(col.column)} as v from ${tableOf(col)} where ${quoteIdent(col.column)} is not null for update`)).rows;
+        `select ctid::text as ctid, ${quoteIdent(col.column)} as v from ${tableOf(col)} where ${rowsOf(col)} for update`)).rows;
       let rotated = 0;
       let already = 0;
       for (const r of rows) {

package/src/layout.ts

@@ -1,5 +1,6 @@
 import { html, type Raw } from './html.ts';
 import { staticUrl } from './static-version.ts';
+import { browserTraceMeta } from './telemetry/browser.ts';
 
 /** Attributes of <html>: language, text direction and a fixed theme (light/dark; absent = follow the OS). */
 export interface RootAttrs {
@@ -20,7 +21,7 @@ export function documentShell(title: string, body: Raw, bodyClass = '', data: Re
 <title>${title}</title>
 <link rel="stylesheet" href="${staticUrl('app.css')}">
 <script src="${staticUrl('app.js')}" defer></script>
-${head}
+${browserTraceMeta()}${head}
 </head>
 <body class="${bodyClass}"${attrs}>
 ${body}

package/src/mail/mail.ts

@@ -14,6 +14,7 @@ import { owner } from '../db.ts';
 import { decryptSecret } from '../secrets.ts';
 import { mailHostAddress, scopeForWorkspace } from '../network-acl.ts';
 import { deliver, MailError, verifyConnection, type OutgoingMail, type Provider, type ServiceSettings } from './providers.ts';
+import { count, markError, rootSpan, setAttrs, traceApp } from '../telemetry/trace.ts';
 
 export interface MailService {
   id: number;
@@ -95,6 +96,14 @@ interface Claimed {
 }
 
 async function sendOne(m: Claimed) {
+  // (sprint 139, AP-6) each attempt a trace of its own (or a span of the request that sends at once)
+  return rootSpan('mail send', { 'pgkiln.mail.id': String(m.id), 'pgkiln.mail.attempt': m.attempts }, async () => {
+    traceApp({ appId: m.app_id });
+    await sendOneTraced(m);
+  });
+}
+
+async function sendOneTraced(m: Claimed) {
   // the application's service, else (sprint 118) its workspace's own
   const service = await owner.one<MailService>(`select s.* from meta.mail_service s where s.id = meta.mail_service_for_app($1)`, [m.app_id]);
   const t0 = performance.now();
@@ -112,10 +121,15 @@ async function sendOne(m: Claimed) {
     await owner.query(`update meta.mail_queue set status = 'sent', sent_at = now(), provider_id = $2, service = $3, message = null,
                               last_attempt_at = now(), duration_ms = $4, provider = $5 where id = $1`,
       [m.id, id ? String(id).slice(0, 500) : null, service.name, ms, provider]);
+    setAttrs({ 'pgkiln.mail.provider': provider, 'pgkiln.mail.service': service.name });
+    count('pgkiln.mail.sent', { status: 'sent' });
   } catch (e) {
     const retry = e instanceof MailError ? e.retry : true;
     const message = (e as Error).message.slice(0, 2000);
     const [ms, provider] = timing();
+    setAttrs({ 'pgkiln.mail.provider': provider, 'pgkiln.mail.service': service?.name ?? null, 'pgkiln.mail.retry': retry && m.attempts < ATTEMPTS });
+    markError(message);
+    count('pgkiln.mail.sent', { status: retry && m.attempts < ATTEMPTS ? 'retry' : 'error' });
     if (retry && m.attempts < ATTEMPTS)
       await owner.query(`update meta.mail_queue set status = 'queued', not_before = now() + make_interval(mins => $2), message = $3, service = $4,
                                 last_attempt_at = now(), duration_ms = $5, provider = $6 where id = $1`,

package/src/runtime/ai-agents.ts

@@ -8,6 +8,7 @@ import { isAuthorized, pageAllowed } from './authz.ts';
 import { bindValues, dbg, publicError, stripSemicolon, type PageContext } from './context.ts';
 import { txContext } from './routes.ts';
 import { retrieve } from './search.ts';
+import { recordSpan } from '../telemetry/trace.ts';
 
 // AI agents and AI tools (migration 121; APEX 26.1 / 26.2: Shared Components
 // → AI Agents). Both are lists in meta.app (ai_agents, ai_tools), exported
@@ -397,6 +398,14 @@ export async function logToolCall(
   ctx: PageContext, regionId: number, agent: string | null, tool: string, type: string, input: Record<string, unknown>, out: AgentOutcome, ms: number,
 ) {
   const status = out.refused ? 'refused' : out.isError ? 'error' : 'ok';
+  // (sprint 139, AP-6) the tool call as a span of the page's trace (its arguments only where values are included)
+  recordSpan(`AI tool ${tool}`.slice(0, 120), {
+    ms,
+    kind: 1,
+    attrs: { 'gen_ai.operation.name': 'execute_tool', 'gen_ai.tool.name': tool, 'gen_ai.tool.type': type, 'pgkiln.ai.agent': agent, 'pgkiln.ai.tool.status': status },
+    vals: { 'gen_ai.tool.call.arguments': JSON.stringify(input ?? {}).slice(0, 2000) },
+    error: status === 'ok' ? null : status,
+  });
   let args = JSON.stringify(input ?? {});
   if (args.length > MAX_ARG_CHARS) args = JSON.stringify({ cut_off: args.slice(0, MAX_ARG_CHARS) });
   dbg(ctx, 4, 'ai', () => `AI tool ${tool} (${type}${agent ? `, agent ${agent}` : ''}) ${args} → ${status} in ${Math.round(ms)} ms${out.isError ? `: ${out.content.slice(0, 300)}` : ''}`);

package/src/runtime/builtin-components.ts

@@ -1,8 +1,8 @@
 import type { TemplateComponent } from './template-components.ts';
 
 // Built-in template components (APEX: the Universal Theme's template
-// components: Avatar, Badge, Comments, Media List, Timeline, and 26.1's
-// Metric Card). Every application can use them in a template_component
+// components: Avatar, Badge, Comments, Content Row (137), Media List,
+// Timeline, and 26.1's Metric Card). Every application can use them in a template_component
 // region or as a report column template without importing anything; a
 // component of the application with the same static id takes its place
 // (Shared Components → Template components → Copy into this application).
@@ -53,6 +53,27 @@ export const BUILTIN_COMPONENTS: readonly TemplateComponent[] = [
     css_classes: [],
     attributes: [text('USER', 'User'), text('INITIALS', 'Initials'), text('DATE', 'Date'), text('COMMENT', 'Comment'), text('ACTIONS', 'Extra text', 'Optional, e.g. "edited".')],
   },
+  {
+    // (137) APEX: Content Row: an avatar, a title and description, and on the right a secondary text and a badge
+    static_id: 'ut_content_row',
+    name: 'Content row',
+    description: 'Rows with initials or a picture, a title (linked when the region has a link) and a description, and on the right a secondary text and a badge. Show the region as "multiple".',
+    template:
+      '<li class="tc-content-row">{if ?IMAGE/}<img class="tc-avatar tc-avatar-md" src="#IMAGE#" alt="" loading="lazy">{else/}<span class="tc-avatar tc-avatar-md" aria-hidden="true">#INITIALS#</span>{endif/}' +
+      '<div class="tc-stack"><p class="tc-title">{if ?LINK/}<a href="#LINK#">#TITLE#</a>{else/}#TITLE#{endif/}</p>{if ?DESCRIPTION/}<p class="tc-meta">#DESCRIPTION#</p>{endif/}</div>' +
+      '<div class="tc-content-row-end">{if ?MISC/}<span class="tc-meta">#MISC#</span>{endif/}{if ?BADGE/}<span class="tc-badge tc-badge-' + STATE + '">#BADGE#</span>{endif/}</div></li>',
+    wrapper: '<ul class="tc-content-rows">#APEX$ROWS#</ul>',
+    css_classes: [],
+    attributes: [
+      text('TITLE', 'Title'),
+      text('DESCRIPTION', 'Description'),
+      text('MISC', 'Secondary text', 'Shown on the right, e.g. a date or an amount.'),
+      text('INITIALS', 'Initials', 'Shown without a picture.'),
+      text('IMAGE', 'Picture URL', 'Optional: a relative or https URL.'),
+      text('BADGE', 'Badge'),
+      text('STATE', 'Badge state', 'success, warning, danger, info or neutral.'),
+    ],
+  },
   {
     static_id: 'ut_media_list',
     name: 'Media list',

package/src/runtime/items.ts

@@ -309,9 +309,11 @@ export async function renderItem(ctx: PageContext, item: Item, hiddenByDa = fals
       case 'checkbox_group': {
         useLegend = true;
         const selected = new Set(splitValues(value));
-        control = html`<div class="radio-group">${options.map(
+        // (137) {"switches": true}: each value as a switch (the Configuration page's build options)
+        const switches = item.config?.switches === true;
+        control = html`<div class="radio-group${switches ? ' switch-group' : ''}">${options.map(
           (o, i) =>
-            html`<label class="check"><input type="checkbox" id="${i === 0 ? id : `${id}_${i}`}" name="${id}" value="${o.value}"${selected.has(o.value) ? raw(' checked') : ''}${aria}> ${o.display}</label>`,
+            html`<label class="check${switches ? ' switch' : ''}"><input type="checkbox" id="${i === 0 ? id : `${id}_${i}`}" name="${id}" value="${o.value}"${switches ? raw(' role="switch"') : ''}${selected.has(o.value) ? raw(' checked') : ''}${aria}> ${o.display}</label>`,
         )}</div>`;
         break;
       }

package/src/runtime/routes.ts

@@ -55,6 +55,7 @@ import { availabilityRefusal } from './availability.ts';
 import { feedbackRoutes } from './feedback.ts';
 import { dataItemRoutes, loadPreferences, savePreferences } from './data-items.ts';
 import { ajaxRoutes } from './ajax.ts';
+import { traceApp } from '../telemetry/trace.ts';
 
 const XLSX_TYPE = 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet';
 
@@ -266,6 +267,8 @@ export async function loadContext(req: Req, reply: FastifyReply, { json = false,
   if (!page) return simplePage(reply, 404, locale.t('error.not_found'), locale.t('error.page_not_found', { page: req.params.page, app: app.name }), base, locale), null;
   if (locale.lang !== app.language) translatePage(page, locale.tr);
   const user = app.authentication === 'none' ? 'nobody' : (session.username ?? 'nobody');
+  // (sprint 139, AP-6) the request's trace: which application (its workspace decides where it goes), page and user
+  await traceApp({ appId: app.id, alias: app.alias, page: page.page_no, user });
 
   if (app.authentication !== 'none' && (page.requires_auth || fixedPage) && !session.username) {
     if (json) reply.code(401).send({ error: locale.t('error.session_ended') });

package/src/session.ts

@@ -1,4 +1,6 @@
 import type { FastifyReply, FastifyRequest } from 'fastify';
+import { count, emitLog } from './telemetry/trace.ts';
+import { appOf } from './telemetry/config.ts';
 import { runtime, sharedRuntime } from './db.ts';
 import { runtimeForApp } from './workspace-db.ts';
 import { hashToken, loginMaxFailuresPerIp, loginMaxFailuresPerUser, loginWindowMinutes, newToken } from './security.ts';
@@ -121,6 +123,7 @@ export async function logActivity(entry: {
   elapsedMs?: number;
   detail?: string;
 }) {
+  activityTelemetry(entry);
   try {
     // (090) on the connection of the entry's application (an isolated workspace's own); without one, the shared one
     const db = entry.appId != null ? await runtimeForApp(entry.appId) : sharedRuntime;
@@ -152,3 +155,26 @@ export async function loginThrottled(appId: number | null, username: string, ip:
   );
   return !!counts && (counts.user_fails >= loginMaxFailuresPerUser() || counts.ip_fails >= loginMaxFailuresPerIp());
 }
+
+// (sprint 139, AP-6) errors, refusals and failed sign-ins as OpenTelemetry logs and metrics
+const OTEL_EVENTS: Record<string, ['ERROR' | 'WARN', string]> = {
+  error: ['ERROR', 'pgkiln.errors'],
+  forbidden: ['WARN', 'pgkiln.access_denied'],
+  login_failed: ['WARN', 'pgkiln.signin_failures'],
+  login_locked: ['WARN', 'pgkiln.signin_failures'],
+};
+
+function activityTelemetry(e: { appId?: number | null; pageNo?: number | null; username?: string | null; event: string; detail?: string }) {
+  const known = OTEL_EVENTS[e.event];
+  if (!known) return;
+  const app = e.appId == null ? 'builder' : appOf(e.appId)?.[0] ?? 'unknown';
+  count(known[1], e.event === 'login_locked' ? { app, reason: 'locked' } : { app });
+  emitLog({
+    severity: known[0],
+    body: e.event,
+    detail: e.detail,
+    attrs: { 'pgkiln.event': e.event, 'pgkiln.app.id': e.appId ?? null, 'pgkiln.app.alias': e.appId == null ? null : app, 'pgkiln.page': e.pageNo == null ? null : String(e.pageNo) },
+    appId: e.appId ?? null,
+    user: e.username ?? null,
+  });
+}

package/src/telemetry/browser.ts

@@ -0,0 +1,91 @@
+import { html, type Raw } from '../html.ts';
+import { checksumValid, signText } from '../security.ts';
+import { browserSpans } from './export.ts';
+import { currentCtx, now, SPAN_KIND, type Span } from './trace.ts';
+
+// (sprint 139, AP-6) Browser spans: a page whose trace is sent carries a signed
+// <meta name="pgkiln-trace"> (layout.ts); app.js reports the page load and the
+// page's Ajax calls to POST /a/:alias/telemetry (src/telemetry/http.ts), and
+// relay() turns them into spans of the page's trace. The token is bound to the
+// trace, the page's span, the time and the application, and is good for 30
+// minutes and 200 spans. No collector address or token reaches the browser.
+
+const TOKEN_MINUTES = 30;
+const MAX_PER_TOKEN = 200;
+const used = new Map<string, number>();
+let usedSince = Date.now();
+
+/** The page's <meta> for browser spans: its trace, span, time and a signature (empty when not wanted). */
+export function browserTraceMeta(): Raw | '' {
+  const ctx = currentCtx();
+  if (!ctx?.trace.browser || !ctx.trace.sampled || !ctx.trace.alias) return '';
+  const root = ctx.trace.spans[0];
+  const ts = Math.floor(Date.now() / 1000);
+  const payload = `${root.traceId}.${root.spanId}.${ts}`;
+  return html`<meta name="pgkiln-trace" content="${payload}.${signText('otel-browser', `${payload}.${ctx.trace.alias.toLowerCase()}`)}">`;
+}
+
+interface BrowserSpan {
+  k?: unknown;
+  path?: unknown;
+  method?: unknown;
+  status?: unknown;
+  start?: unknown;
+  dur?: unknown;
+  t?: Record<string, unknown>;
+}
+
+const num = (v: unknown, max: number) => (typeof v === 'number' && Number.isFinite(v) ? Math.min(Math.max(v, 0), max) : null);
+
+/** Check a page's token and turn its reports into spans. Returns the number kept, or null for a bad token. */
+export function relay(alias: string, token: unknown, spans: unknown): number | null {
+  const m = typeof token === 'string' ? /^([0-9a-f]{32})\.([0-9a-f]{16})\.(\d{1,12})\.([\w-]{22})$/.exec(token) : null;
+  if (!m) return null;
+  const [, traceId, spanId, ts, sig] = m;
+  if (!checksumValid(signText('otel-browser', `${traceId}.${spanId}.${ts}.${alias.toLowerCase()}`), sig)) return null;
+  if (Date.now() / 1000 - Number(ts) > TOKEN_MINUTES * 60) return null;
+  if (Date.now() - usedSince > 3_600_000) {
+    used.clear();
+    usedSince = Date.now();
+  }
+  const list = Array.isArray(spans) ? (spans as BrowserSpan[]).slice(0, 50) : [];
+  const room = MAX_PER_TOKEN - (used.get(`${traceId}.${spanId}`) ?? 0);
+  if (room <= 0 || !list.length) return 0;
+  const prefix = `/a/${alias}/`.toLowerCase();
+  const out: Span[] = [];
+  const t = now();
+  for (const b of list.slice(0, room)) {
+    const dur = num(b.dur, 600_000);
+    const start = num(b.start, 8.64e15);
+    if (dur === null || start === null || Math.abs(start - t) > 3_600_000) continue;
+    const path = typeof b.path === 'string' ? b.path.split('#')[0] : '';
+    const [p, query] = path.split('?');
+    const s: Span = {
+      traceId, spanId: '', parentId: spanId, kind: SPAN_KIND.client, start, end: start + dur, name: '', attrs: { 'pgkiln.browser': true },
+    };
+    if (b.k === 'load') {
+      s.kind = SPAN_KIND.internal;
+      s.name = 'browser page load';
+      for (const k of ['ttfb', 'dom_interactive', 'dom_complete', 'load']) {
+        const v = num(b.t?.[k], 600_000);
+        if (v !== null) s.attrs[`pgkiln.browser.${k}_ms`] = Math.round(v);
+      }
+    } else if (b.k === 'ajax' && p.toLowerCase().startsWith(prefix) && p.length <= 500) {
+      const method = typeof b.method === 'string' && /^(GET|POST|PUT|PATCH|DELETE)$/.test(b.method) ? b.method : 'GET';
+      s.name = `browser ${method}`;
+      s.attrs['http.request.method'] = method;
+      s.attrs['url.path'] = p;
+      const st = num(b.status, 599);
+      if (st !== null) {
+        s.attrs['http.response.status_code'] = Math.round(st);
+        if (st >= 500 || st === 0) s.error = st ? `HTTP ${Math.round(st)}` : 'network error';
+      }
+      if (query) s.vals = { 'url.query': query.slice(0, 2000) };
+    } else continue;
+    out.push(s);
+  }
+  used.set(`${traceId}.${spanId}`, MAX_PER_TOKEN - room + out.length);
+  if (out.length) browserSpans(traceId, alias, out);
+  return out.length;
+}
+