@volter/twin-sentry 0.1.0

package/src/sentry-ingest.ts

@@ -0,0 +1,471 @@
+// Sentry INGESTION — the SDK side of Sentry (the "store"/"envelope" endpoints the
+// `@sentry/node` SDK POSTs captured events to). This is the CORE of the twin: an
+// unmodified `Sentry.captureException()` configured with the twin's DSN lands an event
+// here, the twin GROUPS it into an ISSUE by a deterministic fingerprint, increments the
+// issue's count + first/last seen, persists the event, and returns the event id — exactly
+// like real Sentry's relay/ingest pipeline.
+//
+// State lives in the kernel action log (D1): every event AND its derived issue is written
+// as a local action via applyTwinWrite; reads (the Web API) are the projection. No real
+// Sentry is ever called (D4) — ingestion is fully local/offline.
+//
+// Auth: Sentry authenticates ingestion by the DSN's PUBLIC KEY, supplied either in the
+// `X-Sentry-Auth` header (`Sentry sentry_key=<publicKey>,...`) or the `?sentry_key=`
+// query param, or embedded in the envelope header's `dsn`. The twin validates that a
+// project with that public key exists (faithful 401 otherwise). The store/envelope path
+// is unauthenticated by the SECRET key (that's the modern DSN model — public key only).
+import { applyTwinWrite, projectResources } from '@volter/world-core';
+import type { TwinResource } from '@volter/world-core';
+
+const SERVICE = 'sentry';
+
+export type SentryEventPayload = {
+  event_id?: string;
+  level?: string;
+  platform?: string;
+  message?: string | { message?: string; formatted?: string };
+  logentry?: { message?: string; formatted?: string };
+  transaction?: string;
+  culprit?: string;
+  environment?: string;
+  release?: string;
+  server_name?: string;
+  timestamp?: number | string;
+  tags?: Record<string, unknown> | Array<[string, string]>;
+  exception?: { values?: SentryExceptionValue[] } | SentryExceptionValue[];
+  [k: string]: unknown;
+};
+export type SentryExceptionValue = {
+  type?: string;
+  value?: string;
+  module?: string;
+  stacktrace?: { frames?: SentryFrame[] };
+};
+export type SentryFrame = {
+  filename?: string;
+  function?: string;
+  module?: string;
+  lineno?: number;
+  colno?: number;
+  in_app?: boolean;
+  abs_path?: string;
+  [k: string]: unknown;
+};
+
+export type IngestResult = { status: number; body: unknown };
+
+// ── DSN public key extraction (auth) ─────────────────────────────────────────────
+// The SDK sends the public key in one of three places. We accept all three, mirroring
+// real Sentry's auth resolution order: header → query → envelope-header dsn.
+export function publicKeyFromAuthHeader(header: string | undefined): string | undefined {
+  if (!header) return undefined;
+  // `Sentry sentry_version=7,sentry_client=...,sentry_key=<key>,sentry_secret=...`
+  const m = /sentry_key=([^,\s]+)/.exec(header);
+  return m ? m[1] : undefined;
+}
+export function publicKeyFromDsn(dsn: string | undefined): string | undefined {
+  if (!dsn) return undefined;
+  // `https://<publicKey>@host/<projectId>` (or `<publicKey>:<secret>@host/...`)
+  const m = /\/\/([^:@/]+)(?::[^@]*)?@/.exec(dsn);
+  return m ? m[1] : undefined;
+}
+/** Resolve the ingest public key from header, query string, or envelope-header dsn. */
+export function resolvePublicKey(opts: { authHeader?: string; query?: string; envelopeDsn?: string }): string | undefined {
+  const fromHeader = publicKeyFromAuthHeader(opts.authHeader);
+  if (fromHeader) return fromHeader;
+  if (opts.query) {
+    const params = new URLSearchParams(opts.query);
+    const k = params.get('sentry_key');
+    if (k) return k;
+  }
+  return publicKeyFromDsn(opts.envelopeDsn);
+}
+
+// ── Project key (DSN) resolution against twin state ──────────────────────────────
+// A project_key resource carries { public, projectId, projectSlug, organizationSlug }.
+// Ingestion is authorized iff a project_key with this public key exists. The twin is
+// seeded with a default key/project so an out-of-the-box DSN works (see ensureDefaultKey).
+export type ResolvedKey = { public: string; projectId: string; projectSlug: string; organizationSlug: string };
+
+export function resolveProjectKey(publicKey: string | undefined, root?: string): ResolvedKey | undefined {
+  if (!publicKey) return undefined;
+  const key = projectResources(SERVICE, root).find((r) => r.type === 'project_key' && r.public === publicKey && !r.deleted);
+  if (!key) return undefined;
+  return {
+    public: String(key.public),
+    projectId: String(key.projectId),
+    projectSlug: String(key.projectSlug ?? ''),
+    organizationSlug: String(key.organizationSlug ?? ''),
+  };
+}
+
+// ── Deterministic fingerprint / grouping ─────────────────────────────────────────
+// Real Sentry groups events into issues via a fingerprint. We keep this FAITHFUL-BUT-
+// SIMPLE (real Sentry's full grouping-enhancement/stack-aware algorithm is a filed todo,
+// sentry.ingest.grouping_enhancements). Our rule, in priority order, mirrors Sentry's default-grouping inputs:
+//   1. exception present  → `${type}: ${value-with-numbers-normalized}` + top in-app frame
+//   2. message/logentry   → the message template (formatted message, numbers normalized)
+//   3. fallback           → the culprit/transaction or 'unknown'
+// The fingerprint is hashed to a stable short hex used as the issue id, so the SAME error
+// captured twice ALWAYS lands in the same issue (the grouping guarantee).
+export function normalizeFingerprintText(text: string): string {
+  // Strip volatile tokens so "User 42 not found" and "User 99 not found" group together,
+  // mirroring Sentry's parameterization of numbers/hex/uuids in default grouping.
+  return text
+    .replace(/\b[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\b/gi, '<uuid>')
+    .replace(/0x[0-9a-f]+/gi, '<hex>')
+    .replace(/\b\d+\b/g, '<num>')
+    .trim();
+}
+
+function exceptionValues(event: SentryEventPayload): SentryExceptionValue[] {
+  const ex = event.exception;
+  if (!ex) return [];
+  if (Array.isArray(ex)) return ex;
+  return Array.isArray(ex.values) ? ex.values : [];
+}
+
+function messageText(event: SentryEventPayload): string | undefined {
+  const m = event.message;
+  if (typeof m === 'string') return m;
+  if (m && typeof m === 'object') return m.formatted ?? m.message;
+  const le = event.logentry;
+  if (le) return le.formatted ?? le.message;
+  return undefined;
+}
+
+/** The human title of an issue derived from an event (Sentry's issue title rules). */
+export function eventTitle(event: SentryEventPayload): string {
+  const values = exceptionValues(event);
+  const top = values[values.length - 1];
+  if (top && (top.type || top.value)) {
+    return top.value ? `${top.type ?? 'Error'}: ${top.value}` : String(top.type);
+  }
+  const msg = messageText(event);
+  if (msg) return msg;
+  return event.transaction || event.culprit || '<unknown>';
+}
+
+/** The culprit: Sentry's "where" line — the top in-app frame's function@module, or transaction. */
+export function eventCulprit(event: SentryEventPayload): string {
+  if (event.culprit) return String(event.culprit);
+  const values = exceptionValues(event);
+  const top = values[values.length - 1];
+  const frames = top?.stacktrace?.frames ?? [];
+  // Sentry uses the last (innermost) in-app frame, else the last frame.
+  const inApp = [...frames].reverse().find((f) => f.in_app) ?? frames[frames.length - 1];
+  if (inApp) {
+    const where = inApp.function ?? inApp.filename ?? inApp.module ?? '?';
+    const mod = inApp.module ?? inApp.filename;
+    return mod ? `${where}(${mod})` : where;
+  }
+  return event.transaction || '';
+}
+
+/** The deterministic grouping key text (pre-hash) for an event. */
+export function fingerprintText(event: SentryEventPayload): string {
+  const values = exceptionValues(event);
+  const top = values[values.length - 1];
+  if (top && (top.type || top.value)) {
+    const base = `${top.type ?? 'Error'}: ${normalizeFingerprintText(top.value ?? '')}`;
+    return `${base}|${eventCulprit(event)}`;
+  }
+  const msg = messageText(event);
+  if (msg) return `message:${normalizeFingerprintText(msg)}`;
+  return `culprit:${event.culprit ?? event.transaction ?? 'unknown'}`;
+}
+
+/** djb2 hash → 16-hex-char stable short id (deterministic, no crypto needed). */
+export function hashFingerprint(text: string): string {
+  // 64-bit-ish via two 32-bit accumulators so collisions are vanishingly unlikely.
+  let h1 = 5381 >>> 0;
+  let h2 = 52711 >>> 0;
+  for (let i = 0; i < text.length; i++) {
+    const c = text.charCodeAt(i);
+    h1 = (((h1 << 5) + h1) ^ c) >>> 0;
+    h2 = (((h2 << 5) + h2) + c) >>> 0;
+  }
+  return (h1.toString(16).padStart(8, '0') + h2.toString(16).padStart(8, '0')).slice(0, 16);
+}
+
+/** The issue id (a stable hex group id) for an event in a given project. */
+export function issueIdFor(projectId: string, event: SentryEventPayload): string {
+  return hashFingerprint(`${projectId}|${fingerprintText(event)}`);
+}
+
+function levelOf(event: SentryEventPayload): string {
+  const l = typeof event.level === 'string' ? event.level : 'error';
+  return ['fatal', 'error', 'warning', 'info', 'debug'].includes(l) ? l : 'error';
+}
+
+function tagsObject(event: SentryEventPayload): Record<string, string> {
+  const t = event.tags;
+  if (!t) return {};
+  if (Array.isArray(t)) return Object.fromEntries(t.map(([k, v]) => [String(k), String(v)]));
+  return Object.fromEntries(Object.entries(t).map(([k, v]) => [k, String(v)]));
+}
+
+function toIso(ts: number | string | undefined, fallback: string): string {
+  if (typeof ts === 'number') return new Date(ts * 1000).toISOString();
+  if (typeof ts === 'string' && ts) {
+    const d = new Date(/^\d+(\.\d+)?$/.test(ts) ? Number(ts) * 1000 : ts);
+    if (!Number.isNaN(d.getTime())) return d.toISOString();
+  }
+  return fallback;
+}
+
+function rows(type: string, root?: string): TwinResource[] {
+  return projectResources(SERVICE, root).filter((r) => r.type === type);
+}
+
+let eventCounter = 0;
+function genEventId(provided?: string): string {
+  if (provided && /^[0-9a-f]{32}$/i.test(provided.replace(/-/g, ''))) return provided.replace(/-/g, '').toLowerCase();
+  // 32-hex deterministic-ish id (mirrors Sentry's UUID-without-dashes event_id shape).
+  const seq = (++eventCounter).toString(16).padStart(8, '0');
+  return (seq + 'f'.repeat(24)).slice(0, 32);
+}
+
+export type IngestOutcome = {
+  eventId: string;
+  issueId: string;
+  isNew: boolean;        // true if this created a brand-new issue (→ new-issue alert)
+  wasResolved: boolean;  // true if the issue was resolved/ignored and this event reopened it (→ regression)
+  issue: Record<string, unknown>;
+  event: Record<string, unknown>;
+};
+
+/**
+ * Ingest ONE event into the twin: derive its issue group, upsert the issue (count/seen/
+ * status), persist the event, and return the outcome (for the caller to fire alerts).
+ * Pure local writes via the kernel — no network. `occurredAt` keeps it deterministic.
+ */
+export async function ingestEvent(
+  key: ResolvedKey,
+  event: SentryEventPayload,
+  opts: { root?: string; occurredAt?: string } = {},
+): Promise<IngestOutcome> {
+  const occurredAt = opts.occurredAt ?? new Date().toISOString();
+  const eventTs = toIso(event.timestamp, occurredAt);
+  const eventId = genEventId(event.event_id);
+  const issueId = issueIdFor(key.projectId, event);
+  const level = levelOf(event);
+  const title = eventTitle(event);
+  const culprit = eventCulprit(event);
+  const tags = tagsObject(event);
+
+  const existing = rows('issue', opts.root).find((r) => r.id === issueId);
+  const isNew = !existing;
+  const prevStatus = existing ? String(existing.status ?? 'unresolved') : 'unresolved';
+  // A new event on a resolved/ignored issue REOPENS it (Sentry "regression").
+  const wasResolved = !isNew && (prevStatus === 'resolved' || prevStatus === 'ignored');
+  const prevCount = existing ? Number(existing.count ?? 0) : 0;
+  const firstSeen = existing ? String(existing.firstSeen ?? eventTs) : eventTs;
+
+  const issueFields: Record<string, unknown> = {
+    projectId: key.projectId,
+    projectSlug: key.projectSlug,
+    shortId: `${(key.projectSlug || 'PROJECT').toUpperCase()}-${issueId.slice(0, 4).toUpperCase()}`,
+    title,
+    culprit,
+    level,
+    platform: typeof event.platform === 'string' ? event.platform : 'other',
+    status: wasResolved ? 'unresolved' : prevStatus,
+    count: String(prevCount + 1),
+    userCount: 0,
+    firstSeen,
+    lastSeen: eventTs,
+    type: existing && existing.metadataType ? existing.metadataType : (exceptionValues(event).length ? 'error' : 'default'),
+    metadata: { type: exceptionValues(event)[exceptionValues(event).length - 1]?.type, value: exceptionValues(event)[exceptionValues(event).length - 1]?.value, title },
+    isUnhandled: event.level === 'fatal',
+    ...(existing?.assignedTo !== undefined ? { assignedTo: existing.assignedTo } : {}),
+  };
+
+  const { resource: issueRes } = await applyTwinWrite(SERVICE, {
+    operation: isNew ? 'issue.create' : 'issue.observe',
+    subjectType: 'issue', subjectId: issueId, fields: issueFields, occurredAt,
+    actor: { kind: 'system' },
+  }, opts.root);
+
+  const eventFields: Record<string, unknown> = {
+    eventID: eventId,
+    groupID: issueId,
+    projectID: key.projectId,
+    title,
+    culprit,
+    level,
+    platform: issueFields.platform,
+    message: messageText(event) ?? '',
+    dateCreated: eventTs,
+    dateReceived: occurredAt,
+    tags: Object.entries(tags).map(([k, v]) => ({ key: k, value: v })),
+    environment: typeof event.environment === 'string' ? event.environment : null,
+    release: typeof event.release === 'string' ? event.release : null,
+    'entries:exception': exceptionValues(event),
+  };
+  await applyTwinWrite(SERVICE, {
+    operation: 'event.observe', subjectType: 'event', subjectId: eventId, fields: eventFields, occurredAt,
+    actor: { kind: 'system' },
+  }, opts.root);
+
+  return {
+    eventId, issueId, isNew, wasResolved,
+    issue: { id: issueId, ...issueFields },
+    event: { id: eventId, ...eventFields },
+  };
+}
+
+// ── Envelope parsing ─────────────────────────────────────────────────────────────
+// The modern SDK POSTs an "envelope": newline-delimited JSON —
+//   {envelope header}\n {item header}\n {item payload}\n {item header}\n {item payload}...
+// We parse the header (for the dsn) and extract every `event` / `transaction` item.
+// `attachment`/`session`/`client_report` items are accepted and ignored (faithful — Sentry
+// 200s the whole envelope regardless), so the SDK's transport sees success.
+export type ParsedEnvelope = { header: Record<string, unknown>; items: Array<{ header: Record<string, unknown>; payload: unknown }> };
+
+export function parseEnvelope(body: string): ParsedEnvelope {
+  const lines = body.split('\n');
+  let idx = 0;
+  const header = safeJson(lines[idx++] ?? '{}') as Record<string, unknown>;
+  const items: Array<{ header: Record<string, unknown>; payload: unknown }> = [];
+  while (idx < lines.length) {
+    const headerLine = lines[idx++];
+    if (headerLine === undefined || headerLine === '') continue;
+    const itemHeader = safeJson(headerLine) as Record<string, unknown>;
+    const payloadLine = lines[idx++] ?? '';
+    items.push({ header: itemHeader, payload: safeJson(payloadLine) });
+  }
+  return { header, items };
+}
+
+function safeJson(s: string): unknown {
+  try { return JSON.parse(s); } catch { return {}; }
+}
+
+/** Extract the event payloads (type 'event') from a parsed envelope. */
+export function envelopeEvents(env: ParsedEnvelope): SentryEventPayload[] {
+  return env.items
+    .filter((it) => it.header.type === 'event')
+    .map((it) => it.payload as SentryEventPayload);
+}
+
+/** Attachment item metadata from an envelope (type 'attachment'). The binary payload bytes
+ * are not stored (there is no blob store yet); the metadata (name, size, type, content_type)
+ * IS captured so the attachments listing endpoint can serve it faithfully. */
+export type EnvelopeAttachment = { name: string; size: number; contentType: string; attachmentType: string };
+export function envelopeAttachments(env: ParsedEnvelope): EnvelopeAttachment[] {
+  return env.items
+    .filter((it) => it.header.type === 'attachment')
+    .map((it) => {
+      const h = it.header;
+      const payload = it.payload;
+      const declared = typeof h.length === 'number' ? h.length : undefined;
+      const size = declared ?? (typeof payload === 'string' ? payload.length : JSON.stringify(payload ?? '').length);
+      return {
+        name: String(h.filename ?? 'attachment'),
+        size,
+        contentType: String(h.content_type ?? 'application/octet-stream'),
+        attachmentType: String(h.attachment_type ?? 'event.attachment'),
+      };
+    });
+}
+
+/** A session item from an envelope (type 'session'): the SDK's release-health heartbeat. */
+export type EnvelopeSession = { sid: string; status: string; release?: string; environment?: string; errors: number };
+export function envelopeSessions(env: ParsedEnvelope): EnvelopeSession[] {
+  return env.items
+    .filter((it) => it.header.type === 'session')
+    .map((it) => {
+      const p = (it.payload && typeof it.payload === 'object') ? it.payload as Record<string, unknown> : {};
+      const attrs = (p.attrs && typeof p.attrs === 'object') ? p.attrs as Record<string, unknown> : {};
+      return {
+        sid: String(p.sid ?? ''),
+        status: String(p.status ?? 'ok'),
+        release: typeof attrs.release === 'string' ? attrs.release : undefined,
+        environment: typeof attrs.environment === 'string' ? attrs.environment : undefined,
+        errors: typeof p.errors === 'number' ? p.errors : 0,
+      };
+    });
+}
+
+/** Persist release-health sessions as `session` resources (upsert by sid: a session is a
+ * lifecycle, the final status wins). This is fully reproducible offline — crash-free counts
+ * are exact tallies over the persisted sessions (NOT a fabricated metrics engine). */
+export async function persistSessions(
+  projectId: string,
+  sessions: EnvelopeSession[],
+  opts: { root?: string; occurredAt?: string } = {},
+): Promise<void> {
+  const occurredAt = opts.occurredAt ?? new Date().toISOString();
+  for (const s of sessions) {
+    if (!s.sid) continue;
+    await applyTwinWrite(SERVICE, {
+      operation: 'session.observe', subjectType: 'session', subjectId: s.sid,
+      fields: {
+        projectID: projectId, status: s.status, release: s.release ?? null,
+        environment: s.environment ?? null, errors: s.errors, lastUpdate: occurredAt,
+      },
+      occurredAt, actor: { kind: 'system' },
+    }, opts.root);
+  }
+}
+
+/** Persist an event's attachments (metadata only) as `event_attachment` resources. */
+export async function persistEventAttachments(
+  eventId: string,
+  projectId: string,
+  attachments: EnvelopeAttachment[],
+  opts: { root?: string; occurredAt?: string } = {},
+): Promise<void> {
+  const occurredAt = opts.occurredAt ?? new Date().toISOString();
+  let i = rows('event_attachment', opts.root).length;
+  for (const a of attachments) {
+    i += 1;
+    await applyTwinWrite(SERVICE, {
+      operation: 'event_attachment.create', subjectType: 'event_attachment', subjectId: `att_${i}`,
+      fields: {
+        eventId, projectID: projectId, name: a.name, size: a.size,
+        mimetype: a.contentType, type: a.attachmentType,
+        sha1: hashFingerprint(`${eventId}|${a.name}|${a.size}`),
+        dateCreated: occurredAt,
+        headers: { 'Content-Type': a.contentType },
+      },
+      occurredAt, actor: { kind: 'system' },
+    }, opts.root);
+  }
+}
+
+// ── Default project + key seeding ────────────────────────────────────────────────
+// So an out-of-the-box DSN works against a fresh twin, ensure a default org/project/key
+// exists. Idempotent: only writes when absent. The default public key is deterministic.
+export const DEFAULT_ORG = 'twin-org';
+export const DEFAULT_PROJECT = 'twin-project';
+export const DEFAULT_PROJECT_ID = '1';
+export const DEFAULT_PUBLIC_KEY = 'twinpublickey00000000000000000000';
+
+export async function ensureDefaultProject(root?: string, occurredAt?: string): Promise<void> {
+  const ts = occurredAt ?? '1970-01-01T00:00:00.000Z';
+  const haveOrg = rows('organization', root).some((r) => r.slug === DEFAULT_ORG);
+  if (!haveOrg) {
+    await applyTwinWrite(SERVICE, { operation: 'organization.create', subjectType: 'organization', subjectId: 'org_1', fields: { slug: DEFAULT_ORG, name: 'Twin Org', dateCreated: ts }, occurredAt: ts, actor: { kind: 'system' } }, root);
+  }
+  const haveProj = rows('project', root).some((r) => r.id === DEFAULT_PROJECT_ID);
+  if (!haveProj) {
+    await applyTwinWrite(SERVICE, { operation: 'project.create', subjectType: 'project', subjectId: DEFAULT_PROJECT_ID, fields: { slug: DEFAULT_PROJECT, name: 'Twin Project', platform: 'node', organizationSlug: DEFAULT_ORG, dateCreated: ts }, occurredAt: ts, actor: { kind: 'system' } }, root);
+  }
+  const haveKey = rows('project_key', root).some((r) => r.public === DEFAULT_PUBLIC_KEY);
+  if (!haveKey) {
+    await applyTwinWrite(SERVICE, {
+      operation: 'project_key.create', subjectType: 'project_key', subjectId: 'key_1',
+      fields: { public: DEFAULT_PUBLIC_KEY, secret: 'twinsecret00000000000000000000000', projectId: DEFAULT_PROJECT_ID, projectSlug: DEFAULT_PROJECT, organizationSlug: DEFAULT_ORG, name: 'Default', dateCreated: ts, isActive: true },
+      occurredAt: ts, actor: { kind: 'system' },
+    }, root);
+  }
+}
+
+/** The default DSN an SDK can use against a twin server at `origin` (e.g. http://127.0.0.1:PORT). */
+export function defaultDsn(origin: string): string {
+  const host = origin.replace(/^https?:\/\//, '');
+  const protocol = origin.startsWith('https') ? 'https' : 'http';
+  return `${protocol}://${DEFAULT_PUBLIC_KEY}@${host}/${DEFAULT_PROJECT_ID}`;
+}

package/src/sentry-mirror-ui.ts

@@ -0,0 +1,162 @@
+// Sentry MIRROR UI — a Sentry-dashboard-like view served as a React/TSX app (Bun-bundled,
+// the repo convention). It renders by consuming the twin's OWN Web API on the same origin
+// (/api/0/...) — the same endpoints a real client uses. API↔UI parity: every screen is
+// backed by real twin state, never a hand-made fixture.
+//
+// PURE FRONTEND (R3): the mirror imports no handler and no twin internals — it MOUNTS the
+// pack's OWN fetch adapter (createSentryTwinFetch) as its API backend and reads every byte
+// of state back over the wire, exactly as a browser does.
+//
+// The pure format/level helpers live here so they can be unit-tested AND shared by the
+// React client (Bun tree-shakes the server-only exports out of the browser bundle).
+import { readFile } from 'node:fs/promises';
+import { bundleClient, fileResponse } from '@volter/world-core';
+import { serveHttp } from '@volter/world-core';
+import { createSentryTwinFetch } from './sentry-server.ts';
+import { DEFAULT_ORG, DEFAULT_PROJECT } from './sentry-ingest.ts';
+
+const CLIENT_ENTRY = () => new URL('../client/sentry-mirror.tsx', import.meta.url).pathname;  // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
+const CLIENT_CSS = () => new URL('../client/sentry-mirror.css', import.meta.url).pathname;  // lazy: workerd rejects top-level relative URL from import.meta.url (bundled via pack index)
+
+// ---------------------------------------------------------------------------
+// Pure, dependency-free render/format helpers (plain data in → plain data out).
+// Keep them free of any @volter/world-core / Bun / handler usage.
+// ---------------------------------------------------------------------------
+export type IssueRow = Record<string, any>;
+
+/** Map a Sentry level to a UI tone class. */
+export function levelTone(level: unknown): 'fatal' | 'error' | 'warning' | 'info' | 'debug' | 'muted' {
+  const l = String(level ?? '').toLowerCase();
+  if (l === 'fatal' || l === 'error' || l === 'warning' || l === 'info' || l === 'debug') return l;
+  return 'muted';
+}
+
+/** Map an issue status to a UI tone class. */
+export function statusTone(status: unknown): 'unresolved' | 'resolved' | 'ignored' | 'muted' {
+  const s = String(status ?? '').toLowerCase();
+  if (s === 'resolved') return 'resolved';
+  if (s === 'ignored' || s === 'muted') return 'ignored';
+  if (s === 'unresolved') return 'unresolved';
+  return 'muted';
+}
+
+/** "12.3k", "1.2M", "999" — Sentry's compact event-count formatting. */
+export function formatCount(value: unknown): string {
+  const n = Number(value);
+  if (!Number.isFinite(n)) return '0';
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1).replace(/\.0$/, '')}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(1).replace(/\.0$/, '')}k`;
+  return String(Math.trunc(n));
+}
+
+/** Relative "time ago" for a lastSeen/firstSeen ISO string (deterministic given `now`). */
+export function timeAgo(iso: unknown, now = Date.now()): string {
+  if (typeof iso !== 'string' || !iso) return '—';
+  const t = Date.parse(iso);
+  if (Number.isNaN(t)) return '—';
+  const s = Math.max(0, Math.floor((now - t) / 1000));
+  if (s < 60) return `${s}s ago`;
+  if (s < 3600) return `${Math.floor(s / 60)}m ago`;
+  if (s < 86400) return `${Math.floor(s / 3600)}h ago`;
+  return `${Math.floor(s / 86400)}d ago`;
+}
+
+/** Extract the latest event's exception stacktrace frames for the detail view. */
+export type StackFrame = { filename?: string; function?: string; lineno?: number; module?: string };
+export function latestStacktrace(event: unknown): StackFrame[] {
+  if (!event || typeof event !== 'object') return [];
+  const entries = (event as Record<string, unknown>).entries;
+  if (!Array.isArray(entries)) return [];
+  const ex = entries.find((e) => e && typeof e === 'object' && (e as Record<string, unknown>).type === 'exception');
+  const values = ex && (ex as any).data?.values;
+  if (!Array.isArray(values)) return [];
+  const top = values[values.length - 1];
+  const frames = top?.stacktrace?.frames;
+  return Array.isArray(frames) ? frames : [];
+}
+
+/** The event's tags as a flat [key,value] list for rendering. */
+export function eventTags(event: unknown): Array<{ key: string; value: string }> {
+  if (!event || typeof event !== 'object') return [];
+  const tags = (event as Record<string, unknown>).tags;
+  if (!Array.isArray(tags)) return [];
+  return tags
+    .filter((t) => t && typeof t === 'object')
+    .map((t) => ({ key: String((t as any).key), value: String((t as any).value) }));
+}
+
+// ---------------------------------------------------------------------------
+// Server-only: bundle the React client + serve it alongside the twin Web API.
+// ---------------------------------------------------------------------------
+let clientBundle: Promise<string> | null = null;
+export function buildSentryMirrorClient(): Promise<string> {
+  if (!clientBundle) {
+    clientBundle = bundleClient(CLIENT_ENTRY())
+      .catch((error) => { clientBundle = null; throw error; });
+  }
+  return clientBundle;
+}
+
+const APP_SHELL = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <base href="/"><title>Sentry (twin)</title>
+    <link rel="stylesheet" href="assets/styles.css" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="assets/app.js"></script>
+  </body>
+</html>`;
+
+/** Serve the Sentry dashboard mirror UI (React app) + its backing Web API. */
+export async function createSentryMirrorServer(options: { root?: string; port?: number } = {}): Promise<{ port: number; stop: () => void }> {
+  const twin = createSentryTwinFetch(options);
+  const server = await serveHttp({
+    // LOOPBACK-SPECIFIC bind (2026-08-20, the roving ui-verify flake): with the default
+    // wildcard hostname, `port: 0` can be handed a port some long-running app already LISTENS
+    // on at 127.0.0.1 (SO_REUSEADDR allows the overlapping non-identical bind), and the more
+    // specific loopback listener then shadows this server for every 127.0.0.1 fetch — the
+    // verify talks to a STRANGER (captured: a desktop app's asset server answering 404s on the
+    // mirror's port). Binding 127.0.0.1 makes the kernel allocate a port that is actually free
+    // on loopback, so the verify's fetches deterministically reach THIS server.
+    hostname: '127.0.0.1',
+    port: options.port ?? 0,
+    idleTimeout: 60,
+    async fetch(request) {
+      const url = new URL(request.url);
+      if (request.method === 'GET' && url.pathname === '/assets/app.js') {
+        try { return new Response(await buildSentryMirrorClient(), { headers: { 'content-type': 'text/javascript; charset=utf-8' } }); }
+        catch (error) { return new Response(String(error), { status: 500 }); }
+      }
+      if (request.method === 'GET' && url.pathname === '/assets/styles.css') {
+        return fileResponse(CLIENT_CSS(), { headers: { 'content-type': 'text/css; charset=utf-8' } });
+      }
+      if (request.method === 'GET' && (url.pathname === '/' || url.pathname === '')) {
+        return new Response(APP_SHELL, { headers: { 'content-type': 'text/html; charset=utf-8' } });
+      }
+      // everything else → the twin's OWN FETCH ADAPTER (composition, R2): the Web API the React
+      // client calls (/api/0/...), the SDK's ingest path (/api/:projectId/envelope/) and the
+      // uniform doors (GET /twin) all come from the SAME closure `createSentryTwinServer` serves,
+      // so the mirror port cannot drift from the API port — one serving code path, one truth.
+      return twin(request);
+    },
+  });
+  return { port: server.port ?? options.port ?? 0, stop: () => server.stop(true) };
+}
+
+/** The app-shell HTML (pure, for tests). */
+export function sentryMirrorHtml(): string {
+  return APP_SHELL;
+}
+
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export function sentryMirrorStyles(): Promise<string> {
+  return readFile(CLIENT_CSS(), 'utf8');
+}
+
+/** The default org/project the mirror lists issues for (matches the seeded defaults). */
+export const MIRROR_DEFAULT_ORG = DEFAULT_ORG;
+export const MIRROR_DEFAULT_PROJECT = DEFAULT_PROJECT;

package/src/sentry-perform-harness.ts

@@ -0,0 +1,19 @@
+// A MINIATURE OF THE HEAD, for this pack's own claims and suites (protocol 2). Not on the serve path.
+import { confirmAction, deployableEntries, worldNow } from '@volter/world-core';
+import { pushSentryAction, type SentryExecute } from './sentry-connector.ts';
+
+export async function performPending(execute: SentryExecute, opts: { root?: string; occurredAt: string }): Promise<{ pushed: number; confirmed: string[]; externalIds: Record<string, string> }> {
+  const confirmed: string[] = [];
+  const externalIds: Record<string, string> = {};
+  for (const entry of deployableEntries('sentry', opts.root)) {
+    if (entry.operation !== 'issue.update') continue; // only triage crosses
+    const { externalId } = await pushSentryAction(execute, { operation: entry.operation, subject: entry.subject, fields: entry.fields ?? {} });
+    confirmAction({
+      service: 'sentry', actionId: entry.id, subject: entry.subject, fields: entry.fields ?? {},
+      occurredAt: opts.occurredAt ?? worldNow(), vendorSubjectId: externalId, receipt: { status: 'deployed' },
+      ...(opts.root !== undefined ? { root: opts.root } : {}),
+    });
+    confirmed.push(entry.id); externalIds[entry.id] = externalId;
+  }
+  return { pushed: confirmed.length, confirmed, externalIds };
+}