@volter/twin-sentry 0.1.0

package/dist/src/sentry-ingest.d.ts

@@ -0,0 +1,137 @@
+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;
+};
+export declare function publicKeyFromAuthHeader(header: string | undefined): string | undefined;
+export declare function publicKeyFromDsn(dsn: string | undefined): string | undefined;
+/** Resolve the ingest public key from header, query string, or envelope-header dsn. */
+export declare function resolvePublicKey(opts: {
+    authHeader?: string;
+    query?: string;
+    envelopeDsn?: string;
+}): string | undefined;
+export type ResolvedKey = {
+    public: string;
+    projectId: string;
+    projectSlug: string;
+    organizationSlug: string;
+};
+export declare function resolveProjectKey(publicKey: string | undefined, root?: string): ResolvedKey | undefined;
+export declare function normalizeFingerprintText(text: string): string;
+/** The human title of an issue derived from an event (Sentry's issue title rules). */
+export declare function eventTitle(event: SentryEventPayload): string;
+/** The culprit: Sentry's "where" line — the top in-app frame's function@module, or transaction. */
+export declare function eventCulprit(event: SentryEventPayload): string;
+/** The deterministic grouping key text (pre-hash) for an event. */
+export declare function fingerprintText(event: SentryEventPayload): string;
+/** djb2 hash → 16-hex-char stable short id (deterministic, no crypto needed). */
+export declare function hashFingerprint(text: string): string;
+/** The issue id (a stable hex group id) for an event in a given project. */
+export declare function issueIdFor(projectId: string, event: SentryEventPayload): string;
+export type IngestOutcome = {
+    eventId: string;
+    issueId: string;
+    isNew: boolean;
+    wasResolved: boolean;
+    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 declare function ingestEvent(key: ResolvedKey, event: SentryEventPayload, opts?: {
+    root?: string;
+    occurredAt?: string;
+}): Promise<IngestOutcome>;
+export type ParsedEnvelope = {
+    header: Record<string, unknown>;
+    items: Array<{
+        header: Record<string, unknown>;
+        payload: unknown;
+    }>;
+};
+export declare function parseEnvelope(body: string): ParsedEnvelope;
+/** Extract the event payloads (type 'event') from a parsed envelope. */
+export declare function envelopeEvents(env: ParsedEnvelope): 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 declare function envelopeAttachments(env: ParsedEnvelope): EnvelopeAttachment[];
+/** 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 declare function envelopeSessions(env: ParsedEnvelope): EnvelopeSession[];
+/** 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 declare function persistSessions(projectId: string, sessions: EnvelopeSession[], opts?: {
+    root?: string;
+    occurredAt?: string;
+}): Promise<void>;
+/** Persist an event's attachments (metadata only) as `event_attachment` resources. */
+export declare function persistEventAttachments(eventId: string, projectId: string, attachments: EnvelopeAttachment[], opts?: {
+    root?: string;
+    occurredAt?: string;
+}): Promise<void>;
+export declare const DEFAULT_ORG = "twin-org";
+export declare const DEFAULT_PROJECT = "twin-project";
+export declare const DEFAULT_PROJECT_ID = "1";
+export declare const DEFAULT_PUBLIC_KEY = "twinpublickey00000000000000000000";
+export declare function ensureDefaultProject(root?: string, occurredAt?: string): Promise<void>;
+/** The default DSN an SDK can use against a twin server at `origin` (e.g. http://127.0.0.1:PORT). */
+export declare function defaultDsn(origin: string): string;

package/dist/src/sentry-ingest.js

@@ -0,0 +1,387 @@
+// 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';
+const SERVICE = 'sentry';
+// ── 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) {
+    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) {
+    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) {
+    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);
+}
+export function resolveProjectKey(publicKey, root) {
+    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) {
+    // 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) {
+    const ex = event.exception;
+    if (!ex)
+        return [];
+    if (Array.isArray(ex))
+        return ex;
+    return Array.isArray(ex.values) ? ex.values : [];
+}
+function messageText(event) {
+    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) {
+    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) {
+    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) {
+    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) {
+    // 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, event) {
+    return hashFingerprint(`${projectId}|${fingerprintText(event)}`);
+}
+function levelOf(event) {
+    const l = typeof event.level === 'string' ? event.level : 'error';
+    return ['fatal', 'error', 'warning', 'info', 'debug'].includes(l) ? l : 'error';
+}
+function tagsObject(event) {
+    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, fallback) {
+    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, root) {
+    return projectResources(SERVICE, root).filter((r) => r.type === type);
+}
+let eventCounter = 0;
+function genEventId(provided) {
+    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);
+}
+/**
+ * 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, event, opts = {}) {
+    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 = {
+        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 = {
+        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 },
+    };
+}
+export function parseEnvelope(body) {
+    const lines = body.split('\n');
+    let idx = 0;
+    const header = safeJson(lines[idx++] ?? '{}');
+    const items = [];
+    while (idx < lines.length) {
+        const headerLine = lines[idx++];
+        if (headerLine === undefined || headerLine === '')
+            continue;
+        const itemHeader = safeJson(headerLine);
+        const payloadLine = lines[idx++] ?? '';
+        items.push({ header: itemHeader, payload: safeJson(payloadLine) });
+    }
+    return { header, items };
+}
+function safeJson(s) {
+    try {
+        return JSON.parse(s);
+    }
+    catch {
+        return {};
+    }
+}
+/** Extract the event payloads (type 'event') from a parsed envelope. */
+export function envelopeEvents(env) {
+    return env.items
+        .filter((it) => it.header.type === 'event')
+        .map((it) => it.payload);
+}
+export function envelopeAttachments(env) {
+    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'),
+        };
+    });
+}
+export function envelopeSessions(env) {
+    return env.items
+        .filter((it) => it.header.type === 'session')
+        .map((it) => {
+        const p = (it.payload && typeof it.payload === 'object') ? it.payload : {};
+        const attrs = (p.attrs && typeof p.attrs === 'object') ? p.attrs : {};
+        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, sessions, opts = {}) {
+    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, projectId, attachments, opts = {}) {
+    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, occurredAt) {
+    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) {
+    const host = origin.replace(/^https?:\/\//, '');
+    const protocol = origin.startsWith('https') ? 'https' : 'http';
+    return `${protocol}://${DEFAULT_PUBLIC_KEY}@${host}/${DEFAULT_PROJECT_ID}`;
+}

package/dist/src/sentry-mirror-ui.d.ts

@@ -0,0 +1,38 @@
+export type IssueRow = Record<string, any>;
+/** Map a Sentry level to a UI tone class. */
+export declare function levelTone(level: unknown): 'fatal' | 'error' | 'warning' | 'info' | 'debug' | 'muted';
+/** Map an issue status to a UI tone class. */
+export declare function statusTone(status: unknown): 'unresolved' | 'resolved' | 'ignored' | 'muted';
+/** "12.3k", "1.2M", "999" — Sentry's compact event-count formatting. */
+export declare function formatCount(value: unknown): string;
+/** Relative "time ago" for a lastSeen/firstSeen ISO string (deterministic given `now`). */
+export declare function timeAgo(iso: unknown, now?: number): string;
+/** Extract the latest event's exception stacktrace frames for the detail view. */
+export type StackFrame = {
+    filename?: string;
+    function?: string;
+    lineno?: number;
+    module?: string;
+};
+export declare function latestStacktrace(event: unknown): StackFrame[];
+/** The event's tags as a flat [key,value] list for rendering. */
+export declare function eventTags(event: unknown): Array<{
+    key: string;
+    value: string;
+}>;
+export declare function buildSentryMirrorClient(): Promise<string>;
+/** Serve the Sentry dashboard mirror UI (React app) + its backing Web API. */
+export declare function createSentryMirrorServer(options?: {
+    root?: string;
+    port?: number;
+}): Promise<{
+    port: number;
+    stop: () => void;
+}>;
+/** The app-shell HTML (pure, for tests). */
+export declare function sentryMirrorHtml(): string;
+/** The mirror's stylesheet, for a host serving the shell's `assets/styles.css` itself (the hosted mirror mount). */
+export declare function sentryMirrorStyles(): Promise<string>;
+/** The default org/project the mirror lists issues for (matches the seeded defaults). */
+export declare const MIRROR_DEFAULT_ORG = "twin-org";
+export declare const MIRROR_DEFAULT_PROJECT = "twin-project";