@volter/twin-sentry 0.1.0

package/src/sentry-conformance.ts

@@ -0,0 +1,110 @@
+// Sentry twin conformance — offline shape conformance against Sentry's REST response
+// shapes. Sentry publishes no single machine-readable OpenAPI we can vendor cleanly, so
+// (like the rest of the suite's offline checks) we drive REAL requests through the twin and
+// validate each served object against an authored per-resource REQUIRED-FIELD spec drawn
+// from Sentry's API docs. A served object missing a required Sentry field — or the ingest→
+// grouping invariant breaking — fails the report. This is offline + deterministic (no token).
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { handleSentryTwinRequest, type SentryResponse } from './sentry-twin.ts';
+import { DEFAULT_ORG, DEFAULT_PROJECT, DEFAULT_PROJECT_ID, DEFAULT_PUBLIC_KEY } from './sentry-ingest.ts';
+
+// The Sentry fields each served object MUST carry (from Sentry's API reference). A missing
+// field is a conformance violation; extra twin-internal `_`-prefixed fields are exempt.
+const REQUIRED_FIELDS: Record<string, string[]> = {
+  issue: ['id', 'shortId', 'title', 'culprit', 'level', 'status', 'count', 'firstSeen', 'lastSeen', 'permalink', 'metadata'],
+  event: ['id', 'eventID', 'groupID', 'projectID', 'title', 'message', 'dateCreated', 'tags', 'entries'],
+  project: ['id', 'slug', 'name', 'platform'],
+  project_key: ['id', 'public', 'secret', 'projectId', 'dsn', 'isActive'],
+  organization: ['id', 'slug', 'name'],
+  team: ['id', 'slug', 'name'],
+  release: ['id', 'version', 'shortVersion', 'dateCreated'],
+  deploy: ['id', 'environment', 'release'],
+  alert_rule: ['id', 'name', 'triggers'],
+};
+
+export type SentryViolation = { object: string; id: string; field: string; reason: string };
+export type SentryConformanceReport = {
+  ok: boolean;
+  resourcesChecked: number;
+  fieldsChecked: number;
+  violations: SentryViolation[];
+};
+
+function checkObject(object: string, body: Record<string, unknown>): { fieldsChecked: number; violations: SentryViolation[] } {
+  const required = REQUIRED_FIELDS[object] ?? [];
+  const violations: SentryViolation[] = [];
+  const id = String(body.id ?? '?');
+  for (const f of required) {
+    if (!(f in body) || body[f] === undefined) {
+      violations.push({ object, id, field: f, reason: 'required Sentry field missing' });
+    }
+  }
+  return { fieldsChecked: required.length, violations };
+}
+
+/**
+ * Drive a representative request flow through the twin and validate every served object's
+ * shape against the required-field spec, plus assert the ingest→grouping invariant. Offline,
+ * deterministic (a fresh temp root, fixed occurredAt).
+ */
+export async function checkSentryConformance(opts: { root?: string } = {}): Promise<SentryConformanceReport> {
+  const root = opts.root ?? mkdtempSync(join(tmpdir(), 'sentry-conf-'));
+  const own = !opts.root;
+  const occurredAt = '2026-01-01T00:00:00.000Z';
+  const h = (method: string, path: string, body?: unknown): Promise<SentryResponse> =>
+    handleSentryTwinRequest({ method, path, body: body === undefined ? undefined : JSON.stringify(body), root, occurredAt, headers: {} });
+  const ingest = (event: unknown): Promise<SentryResponse> =>
+    handleSentryTwinRequest({ method: 'POST', path: `/api/${DEFAULT_PROJECT_ID}/store/`, body: JSON.stringify(event), root, occurredAt, headers: { 'x-sentry-auth': `Sentry sentry_key=${DEFAULT_PUBLIC_KEY}` } });
+
+  const violations: SentryViolation[] = [];
+  let resourcesChecked = 0;
+  let fieldsChecked = 0;
+  const check = (object: string, body: unknown) => {
+    if (!body || typeof body !== 'object') return;
+    resourcesChecked++;
+    const r = checkObject(object, body as Record<string, unknown>);
+    fieldsChecked += r.fieldsChecked;
+    violations.push(...r.violations);
+  };
+
+  try {
+    // Ingest the same error twice → must group into ONE issue with count 2.
+    const err1 = { exception: { values: [{ type: 'TypeError', value: 'x is undefined' }] } };
+    const e1 = await ingest(err1);
+    const e2 = await ingest(err1);
+    const id1 = (e1.body as { id?: string }).id;
+    const id2 = (e2.body as { id?: string }).id;
+
+    const issuesRes = await h('GET', `/api/0/projects/${DEFAULT_ORG}/${DEFAULT_PROJECT}/issues/?query=`);
+    const issues = issuesRes.body as Array<Record<string, unknown>>;
+    if (!Array.isArray(issues) || issues.length !== 1) {
+      violations.push({ object: 'issue', id: '?', field: 'grouping', reason: `ingest→grouping invariant broken: expected 1 issue, got ${Array.isArray(issues) ? issues.length : 'non-array'}` });
+    } else {
+      const issue = issues[0]!;
+      if (String(issue.count) !== '2') violations.push({ object: 'issue', id: String(issue.id), field: 'count', reason: `grouping count expected 2, got ${issue.count}` });
+      if (!id1 || !id2 || id1 === id2) violations.push({ object: 'event', id: '?', field: 'eventID', reason: 'distinct event ids expected for two captures' });
+      check('issue', issue);
+      const evs = await h('GET', `/api/0/issues/${issue.id}/events/`);
+      check('event', (evs.body as unknown[])[0]);
+    }
+
+    check('project', (await h('GET', `/api/0/projects/${DEFAULT_ORG}/${DEFAULT_PROJECT}/`)).body);
+    check('project_key', ((await h('GET', `/api/0/projects/${DEFAULT_ORG}/${DEFAULT_PROJECT}/keys/`)).body as unknown[])[0]);
+    check('organization', (await h('GET', `/api/0/organizations/${DEFAULT_ORG}/`)).body);
+    check('team', (await h('POST', `/api/0/organizations/${DEFAULT_ORG}/teams/`, { name: 'Backend' })).body);
+    check('release', (await h('POST', `/api/0/organizations/${DEFAULT_ORG}/releases/`, { version: '1.0.0' })).body);
+    check('deploy', (await h('POST', `/api/0/organizations/${DEFAULT_ORG}/releases/1.0.0/deploys/`, { environment: 'production' })).body);
+    check('alert_rule', (await h('POST', `/api/0/projects/${DEFAULT_ORG}/${DEFAULT_PROJECT}/rules/`, { name: 'New issues', triggers: ['new-issue'], endpoints: ['https://x.test/hook'] })).body);
+  } finally {
+    if (own) rmSync(root, { recursive: true, force: true });
+  }
+
+  return { ok: violations.length === 0, resourcesChecked, fieldsChecked, violations };
+}
+
+/** Per-object coverage: required-field count covered vs. declared (the offline coverage view). */
+export function sentryConformanceFields(): Record<string, number> {
+  return Object.fromEntries(Object.entries(REQUIRED_FIELDS).map(([k, v]) => [k, v.length]));
+}

package/src/sentry-connector.ts

@@ -0,0 +1,260 @@
+// Sentry CONNECTOR — the live-vendor pull/push path that gives the Sentry twin the full
+// "git for SaaS" lifecycle.
+//
+// PULL  (real → twin):  fetch real Sentry issues/projects/releases over the injected
+//                       client, map → SyncResource[], fold into the event log via syncPull
+//                       (shadow-diff dedup, so a re-pull of identical state appends nothing).
+// PUSH  (twin → real):  for every PENDING local issue.update action (resolve/ignore/assign),
+//                       PUT the real Sentry issue and confirmAction on success — which records
+//                       the confirmed fields as an observed event and suppresses the local
+//                       projection (the change is counted exactly once).
+//
+// The vendor I/O is an INJECTED executor (the auth-boundary): the kernel and this pack hold
+// NO Sentry token and import NO network client. Offline/tests pass a fake executor; live runs
+// pass `liveSentryExecute(token)`. Same code path either way.
+import { assertBudgetGuardIntact, observeResources } from '@volter/world-core';
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import { SentryBudget, SentryBudgetError, sentryCallWeight, type SentryBudgetOptions } from './sentry-budget.ts';
+
+const SERVICE = 'sentry';
+
+/**
+ * The injected real-Sentry boundary. `request` issues ONE Sentry Web API call:
+ *   method — 'GET' | 'PUT' | 'POST' | 'DELETE'
+ *   path   — e.g. '/api/0/projects/org/proj/issues/' or '/api/0/issues/123/'
+ *   body   — JSON body for writes; omitted for GETs
+ * Returns the parsed JSON body (an object or array). A real client (a fetch wrapper around
+ * sentry.io with a bearer token) is structurally assignable; tests pass a fake.
+ */
+export type SentryExecute = (
+  method: 'GET' | 'PUT' | 'POST' | 'DELETE',
+  path: string,
+  body?: Record<string, unknown>,
+) => Promise<any>;
+
+/** Construction options for the live executor. `budget` cannot be null and cannot be loosened. */
+export type LiveSentryOptions = {
+  /** Injected `fetch`, so a test can COUNT the requests the guard did or did not let through. */
+  fetchImpl?: typeof fetch;
+  /** An existing budget to share across executors. Omit and one is constructed. Cannot be null. */
+  budget?: SentryBudget;
+  /** Construction options for the default budget (ledger path, clock). Cannot loosen it. */
+  budgetOptions?: SentryBudgetOptions;
+};
+
+/**
+ * A live executor against real Sentry (token = the user's own auth token). Never imported
+ * by the pack's own runtime path — only constructed by a caller that opts into real I/O.
+ *
+ * THIS IS THE ONE PLACE this pack issues a live `sentry.io` request, and therefore the one place
+ * the rate budget has to be enforced. EVERY call is guarded: the budget is charged BEFORE the
+ * request goes out (`checkBudget`, which THROWS `SentryBudgetError` instead of returning when the
+ * ceiling or a cooldown says stop) and the response is fed back (`recordCall`) so a `Retry-After` /
+ * 429 / `X-Sentry-Rate-Limit-Remaining: 0` signal becomes a persisted cooldown that makes every
+ * later call fail fast WITHOUT touching Sentry. Sentry publishes no scalar limit, so that cooldown
+ * is the part that matters most — see `sentry-budget.ts`. There is deliberately no OPTION to disable the guard, and no value a caller can pass for `budget`
+ * that yields an unguarded client — though not immunity from a caller who wants one (a fresh
+ * `budgetOptions.path` or an injected clock restores the allowance; the kernel header says so).
+ */
+export function liveSentryExecute(
+  token: string,
+  base = 'https://sentry.io',
+  opts: LiveSentryOptions = {},
+): SentryExecute {
+  // `null`/`undefined` (or omitting it) build the default budget. Anything else must be an
+  // UNMODIFIED SentryBudget: a duck-typed stand-in, a SUBCLASS that overrides `checkBudget`, and a
+  // Proxy that traps it are all refused, because all three are one-liners that would otherwise
+  // hand back a client with no ceiling at all (§9 finding, 2026-07-26 — `instanceof` alone was
+  // not a check). What this cannot stop is deliberate sabotage from inside the process (an
+  // injected clock, a throwaway ledger path); the kernel's header says so rather than pretending
+  // otherwise, and this guards the accident and the one-liner, which are the shapes that happen.
+  const doFetch = opts.fetchImpl ?? fetch;
+  // The default ledger is keyed by a hash of THIS token — Sentry's limits attach to the token's
+  // organization, so a cwd-scoped ledger would hand it a fresh allowance per checkout/worktree/CI leg.
+  // ONE expression decides which budget is used, so there is no second, weaker test that could
+  // disagree with the first. `null`/`undefined` (or omitting it) build the default; anything else
+  // must be an UNMODIFIED SentryBudget — a duck-typed stand-in, a SUBCLASS overriding
+  // `checkBudget`, and a Proxy trapping it are ALL refused, because each is a one-liner that
+  // would otherwise hand back a client with no ceiling (§9 finding, 2026-07-26: `instanceof`
+  // alone was not a check — a subclass satisfied it). What this cannot stop is deliberate
+  // sabotage from inside the process (an injected clock, a throwaway ledger path); the kernel
+  // header states that limit rather than pretending otherwise. This closes the accident and the
+  // one-liner, which are the shapes that actually happen.
+  const budget = opts.budget !== undefined && opts.budget !== null
+    ? assertBudgetGuardIntact(opts.budget, SentryBudget, 'liveSentryExecute')
+    : new SentryBudget({ token, ...(opts.budgetOptions ?? {}) });
+  return async (method, path, reqBody) => {
+    const headers: Record<string, string> = { Authorization: `Bearer ${token}` };
+    const init: { method: string; headers: Record<string, string>; body?: string } = { method, headers };
+    if (method !== 'GET' && reqBody) {
+      headers['Content-Type'] = 'application/json';
+      init.body = JSON.stringify(reqBody);
+    }
+    const weight = sentryCallWeight(method, path);
+    // THROWS instead of calling. Nothing below this line runs when the budget refuses.
+    const reservation = budget.checkBudget(weight);
+    const res = await doFetch(`${base}${path}`, init);
+    const resHeaders: Record<string, string> = {};
+    res.headers.forEach((v: string, k: string) => { resHeaders[k.toLowerCase()] = v; });
+    const text = await res.text();
+    // Settles the reservation and, on a back-off signal, arms the cooldown. May itself throw (a
+    // `Retry-After` beyond the cap is not something to sleep off) — the cooldown is persisted
+    // first either way, so the refusal survives the throw.
+    // recordCall may THROW after arming the cooldown (a back-off beyond the cap). On a refused
+    // call that louder refusal wins; an answer Sentry ACCEPTED is kept, so a write that landed is
+    // never recorded as failed and performed again on retry.
+    try {
+      budget.recordCall(weight, resHeaders, { status: res.status, reservation });
+    } catch (error) {
+      if (!(error instanceof SentryBudgetError) || !res.ok) throw error;
+    }
+    return text ? JSON.parse(text) : {};
+  };
+}
+
+// ── Mapping (real Sentry snake/camel → twin SyncResource) ────────────────────────
+export function mapIssue(i: Record<string, unknown>): SyncResource {
+  return {
+    type: 'issue', id: String(i.id),
+    fields: {
+      projectId: i.project && typeof i.project === 'object' ? String((i.project as Record<string, unknown>).id ?? '') : String(i.projectId ?? ''),
+      projectSlug: i.project && typeof i.project === 'object' ? String((i.project as Record<string, unknown>).slug ?? '') : String(i.projectSlug ?? ''),
+      shortId: i.shortId ?? null,
+      title: i.title ?? (i.metadata && (i.metadata as Record<string, unknown>).title) ?? '',
+      culprit: i.culprit ?? '',
+      level: i.level ?? 'error',
+      status: i.status ?? 'unresolved',
+      count: String(i.count ?? '0'),
+      userCount: i.userCount ?? 0,
+      firstSeen: i.firstSeen ?? null,
+      lastSeen: i.lastSeen ?? null,
+      assignedTo: i.assignedTo ?? null,
+    },
+  };
+}
+export function mapProject(p: Record<string, unknown>): SyncResource {
+  return {
+    type: 'project', id: String(p.id),
+    fields: {
+      slug: p.slug ?? '', name: p.name ?? '', platform: p.platform ?? null,
+      organizationSlug: p.organization && typeof p.organization === 'object' ? String((p.organization as Record<string, unknown>).slug ?? '') : String(p.organizationSlug ?? ''),
+      dateCreated: p.dateCreated ?? null,
+    },
+  };
+}
+export function mapRelease(r: Record<string, unknown>, orgSlug: string): SyncResource {
+  const version = String(r.version);
+  return {
+    type: 'release', id: `${orgSlug}:${version}`,
+    fields: {
+      version, organizationSlug: orgSlug,
+      ref: r.ref ?? null, url: r.url ?? null,
+      dateCreated: r.dateCreated ?? null, dateReleased: r.dateReleased ?? null,
+      commitCount: r.commitCount ?? 0,
+    },
+  };
+}
+
+// ── PULL ─────────────────────────────────────────────────────────────────────────
+export async function pullSentryIssues(execute: SentryExecute, org: string, project: string, opts: { query?: string } = {}): Promise<SyncResource[]> {
+  const q = opts.query ? `?query=${encodeURIComponent(opts.query)}` : '';
+  const res = await execute('GET', `/api/0/projects/${org}/${project}/issues/${q}`);
+  return (Array.isArray(res) ? res : []).map((i) => mapIssue(i as Record<string, unknown>));
+}
+export async function pullSentryProjects(execute: SentryExecute): Promise<SyncResource[]> {
+  const res = await execute('GET', `/api/0/projects/`);
+  return (Array.isArray(res) ? res : []).map((p) => mapProject(p as Record<string, unknown>));
+}
+export async function pullSentryReleases(execute: SentryExecute, org: string): Promise<SyncResource[]> {
+  const res = await execute('GET', `/api/0/organizations/${org}/releases/`);
+  return (Array.isArray(res) ? res : []).map((r) => mapRelease(r as Record<string, unknown>, org));
+}
+
+/** Pull issues + projects + releases from real Sentry and fold them into the event log. */
+export async function syncSentryFromReal(
+  execute: SentryExecute,
+  opts: { org: string; project: string; root?: string; occurredAt: string },
+): Promise<{ pulled: number }> {
+  const [issues, projects, releases] = await Promise.all([
+    pullSentryIssues(execute, opts.org, opts.project),
+    pullSentryProjects(execute),
+    pullSentryReleases(execute, opts.org),
+  ]);
+  const resources = [...projects, ...issues, ...releases];
+  // protocol 2: the observation lands on the head through the kernel's fold — one batch, one instant
+  const result = observeResources(SERVICE, resources.map((r) => ({ type: r.type, id: r.id, fields: r.fields })), { ...(opts.root !== undefined ? { root: opts.root } : {}), at: opts.occurredAt, batch: `obs:${SERVICE}:${opts.occurredAt}` });
+  return { pulled: result.appended };
+}
+
+// ── PUSH ─────────────────────────────────────────────────────────────────────────
+// The twin write operations this connector can faithfully push back to real Sentry. The
+// connector pushes ISSUE STATUS changes (resolve / ignore / unresolve / assign) — the
+// human "triage" actions an operator drives the twin with. Anything else FAILS LOUDLY
+// rather than silently hitting the wrong real endpoint.
+const PUSHABLE_OPS = new Set(['issue.update']);
+
+function assertPushable(op: string): void {
+  if (!PUSHABLE_OPS.has(op)) {
+    throw new Error(`sentry push: unsupported operation '${op}' — refusing to silently drop a local write`);
+  }
+}
+
+/** The real-Sentry request for a pending action (PUT /api/0/issues/:id/ with the patch). */
+export function sentryRequestForAction(action: Pick<TwinAction, 'operation' | 'subject' | 'fields'>): { method: 'PUT'; path: string; body: Record<string, unknown> } {
+  const fields = action.fields ?? {};
+  const patch: Record<string, unknown> = {};
+  if (fields.status !== undefined) patch.status = fields.status;
+  if (fields.assignedTo !== undefined) patch.assignedTo = fields.assignedTo;
+  if (fields.statusDetails !== undefined) patch.statusDetails = fields.statusDetails;
+  return { method: 'PUT', path: `/api/0/issues/${action.subject.id}/`, body: patch };
+}
+
+/** Push ONE pending issue.update action to REAL Sentry via the injected executor. */
+export async function pushSentryAction(
+  execute: SentryExecute,
+  action: Pick<TwinAction, 'operation' | 'subject' | 'fields'>,
+): Promise<{ externalId: string }> {
+  assertPushable(action.operation ?? '');
+  const { method, path, body } = sentryRequestForAction(action);
+  const res = await execute(method, path, body);
+  if (res && typeof res === 'object' && 'detail' in res && !('id' in res)) {
+    throw new Error(`sentry push issue ${action.subject.id} failed: ${(res as { detail?: string }).detail ?? 'unknown error'}`);
+  }
+  const id = (res as { id?: unknown })?.id;
+  return { externalId: typeof id === 'string' && id ? id : action.subject.id };
+}
+
+// ── PROTOCOL 2: the pack's half of the real state system ────────────────────────────────────
+/** The pack's executor over the kernel's: the same Sentry REST call, carried by the head. */
+export function sentryExecuteOver(execute: RemoteExecute): SentryExecute {
+  return async (method, path, body) => {
+    const res = await execute({
+      method, path,
+      // Sentry authenticates with a bearer token; at a real boundary the kernel's executor sets the sealed
+      // credential over this header, and at the twin's own wire any bearer is a bearer.
+      headers: { accept: 'application/json', authorization: 'Bearer twin', ...(body ? { 'content-type': 'application/json' } : {}) },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    });
+    if (res.body === '') return {};
+    try { return JSON.parse(res.body) as Record<string, unknown>; } catch { return { detail: res.body.slice(0, 200) }; }
+  };
+}
+/** The refresh adapter: pull the organization's projects and issues through the executor. */
+export async function syncSentryFromRemote(execute: RemoteExecute, opts: { root?: string; origin?: string; occurredAt?: string; org?: string; project?: string } = {}): Promise<{ pulled: number }> {
+  // Sentry's reads are scoped to an org and a project. A world names them on its root (`scope`); the twin's
+  // own defaults stand in when a refresh runs against the twin itself.
+  return syncSentryFromReal(sentryExecuteOver(execute), {
+    org: opts.org ?? 'twin-org',
+    project: opts.project ?? 'twin-project',
+    ...(opts.root !== undefined ? { root: opts.root } : {}),
+    occurredAt: opts.occurredAt ?? new Date().toISOString(),
+  });
+}
+/** The perform adapter: TRIAGE is what crosses — an issue's resolution, assignment, mute. Everything else
+ *  this twin holds is something Sentry told it (an event, a release, a project), not a write it owes back. */
+export async function performSentryAction(execute: RemoteExecute, action: TwinAction, _ctx: PerformContext): Promise<PushOutcome> {
+  if (action.operation !== 'issue.update') {
+    return { externalId: action.subject.id, data: { performed: false, reason: `${action.operation ?? action.subject.type} is the twin's own record — only issue triage crosses to Sentry` } };
+  }
+  return pushSentryAction(sentryExecuteOver(execute), { operation: action.operation, subject: action.subject, fields: action.fields ?? {} });
+}

package/src/sentry-events.ts

@@ -0,0 +1,171 @@
+// Sentry ALERTS + WEBHOOKS — Sentry fires webhooks (to "internal integrations" /
+// alert-rule actions) on new-issue and regression (issue-reopened) events so an app's
+// handler runs. A faithful twin must too. On ingest, the twin builds the Sentry webhook
+// envelope and delivers it, SIGNED, to registered endpoints.
+//
+// Signature: Sentry signs each webhook delivery with HMAC-SHA256 over the raw JSON body
+// keyed by the integration's client secret, in the `Sentry-Hook-Signature` header. We
+// reproduce that byte-for-byte (pure node:crypto, deterministic, offline) so a consumer
+// can verify twin-delivered webhooks with the same code it uses in prod.
+//
+// Delivery is an INJECTED seam (the auth-boundary): tests pass a fake deliverer, live runs
+// pass the HTTP deliverer. verify() in the manifest stays fully offline.
+import { applyTwinWrite, projectResources, nodeBuiltin } from '@volter/world-core';
+import type { TwinResource } from '@volter/world-core';
+import { worldEgressRefusal } from '@volter/world-core/network-policy';
+
+const SERVICE = 'sentry';
+
+export type SentryWebhookResource = 'issue' | 'error' | 'event_alert' | 'metric_alert';
+export type SentryWebhookAction = 'created' | 'resolved' | 'assigned' | 'ignored' | 'triggered';
+
+export type SentryWebhook = {
+  action: SentryWebhookAction;
+  installation: { uuid: string };
+  data: Record<string, unknown>;
+  actor: { type: 'application' | 'user'; id: string; name: string };
+};
+
+export type SentryWebhookDelivery = (
+  url: string,
+  payload: string,
+  headers: Record<string, string>,
+) => Promise<void> | void;
+
+// ── Signature (Sentry's scheme) ──────────────────────────────────────────────────
+type NodeCrypto = typeof import('node:crypto');
+function nodeCrypto(): NodeCrypto {
+  // Lazy require so this module can be pulled into the browser UI bundle without
+  // Bun's browser target choking on node:crypto (the signature helpers are server-only).
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  return nodeBuiltin('node:crypto') as NodeCrypto;
+}
+
+/** HMAC-SHA256(secret, rawBody) as lowercase hex — Sentry's Sentry-Hook-Signature. */
+export function computeSentrySignature(rawBody: string, secret: string): string {
+  return nodeCrypto().createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex');
+}
+
+export class SentrySignatureVerificationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SentrySignatureVerificationError';
+  }
+}
+
+/** Verify a delivered webhook body against the header signature + secret (constant-time). */
+export function verifySentrySignature(rawBody: string, signatureHeader: string | undefined, secret: string): boolean {
+  if (!signatureHeader) return false;
+  const expected = computeSentrySignature(rawBody, secret);
+  const a = Buffer.from(expected, 'utf8');
+  const b = Buffer.from(signatureHeader, 'utf8');
+  return a.length === b.length && nodeCrypto().timingSafeEqual(a, b);
+}
+
+/** Verify or throw (mirrors a consumer's "reject bad signature" branch). */
+export function constructSentryWebhook(rawBody: string, signatureHeader: string | undefined, secret: string): SentryWebhook {
+  if (!verifySentrySignature(rawBody, signatureHeader, secret)) {
+    throw new SentrySignatureVerificationError('Sentry-Hook-Signature does not match the expected signature for payload.');
+  }
+  return JSON.parse(rawBody) as SentryWebhook;
+}
+
+// ── Alert-rule registry (stored as twin state) ───────────────────────────────────
+// An alert rule fires its action(s) when its trigger condition is met. We model the two
+// triggers an issue's lifecycle produces: 'new-issue' (first time a group is seen) and
+// 'regression' (a resolved/ignored issue reopened). Each rule has webhook target URLs +
+// a signing secret. Rules live in the action log (D1) like every other resource.
+export type AlertTrigger = 'new-issue' | 'regression';
+
+function rows(type: string, root?: string): TwinResource[] {
+  return projectResources(SERVICE, root).filter((r) => r.type === type);
+}
+
+export async function registerAlertRule(
+  rule: { id: string; projectId: string; name?: string; triggers: AlertTrigger[]; endpoints: string[]; secret: string; installationUuid?: string },
+  opts: { root?: string; occurredAt?: string } = {},
+): Promise<void> {
+  await applyTwinWrite(SERVICE, {
+    operation: 'alert_rule.create', subjectType: 'alert_rule', subjectId: rule.id,
+    fields: {
+      projectId: rule.projectId,
+      name: rule.name ?? rule.id,
+      triggers: rule.triggers,
+      endpoints: rule.endpoints,
+      secret: rule.secret,
+      installationUuid: rule.installationUuid ?? `inst_${rule.id}`,
+      dateCreated: opts.occurredAt ?? '1970-01-01T00:00:00.000Z',
+    },
+    occurredAt: opts.occurredAt ?? '1970-01-01T00:00:00.000Z', actor: { kind: 'system' },
+  }, opts.root);
+}
+
+export function listAlertRules(projectId: string | undefined, root?: string): TwinResource[] {
+  return rows('alert_rule', root).filter((r) => !r.deleted && (projectId === undefined || r.projectId === projectId));
+}
+
+// ── Webhook emission on issue lifecycle ──────────────────────────────────────────
+const httpDelivery: SentryWebhookDelivery = async (url, payload, headers) => {
+  if (worldEgressRefusal(url) !== null) return; // the World's egress rule: refused like an unreachable endpoint
+  try {
+    await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json', ...headers }, body: payload });
+  } catch {
+    /* fire-and-forget, like Sentry */
+  }
+};
+
+/** A delivery's request id, DERIVED from the delivery itself — never a process counter, so two identical
+ *  worlds send the same hook with the same id (protocol 2, R9). */
+function hookRequestId(seed: string): string {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < seed.length; i += 1) { h ^= seed.charCodeAt(i); h = Math.imul(h, 0x01000193) >>> 0; }
+  return `whk_twin_${h.toString(16).padStart(8, '0')}`;
+}
+
+/**
+ * Fire alert webhooks for an issue lifecycle event. `trigger` is 'new-issue' or
+ * 'regression'; `issue` is the issue resource (Web-API shape). Delivers a SIGNED webhook
+ * to every endpoint of every matching rule for the issue's project. Returns the delivered
+ * payloads (for assertions). No-op when no rule matches. `deliver` is injected.
+ */
+export async function emitIssueAlert(
+  trigger: AlertTrigger,
+  issue: Record<string, unknown>,
+  opts: { root?: string; deliver?: SentryWebhookDelivery; occurredAt?: string } = {},
+): Promise<Array<{ url: string; payload: SentryWebhook; signature: string }>> {
+  const projectId = String(issue.projectId ?? '');
+  const rules = listAlertRules(projectId, opts.root).filter((r) =>
+    Array.isArray(r.triggers) && (r.triggers as string[]).includes(trigger),
+  );
+  if (rules.length === 0) return [];
+  const deliver = opts.deliver ?? httpDelivery;
+  const action: SentryWebhookAction = trigger === 'new-issue' ? 'created' : 'triggered';
+  const out: Array<{ url: string; payload: SentryWebhook; signature: string }> = [];
+  for (const rule of rules) {
+    const installationUuid = String(rule.installationUuid ?? `inst_${rule.id}`);
+    const webhook: SentryWebhook = {
+      action,
+      installation: { uuid: installationUuid },
+      actor: { type: 'application', id: 'sentry', name: 'Sentry' },
+      data: {
+        issue,
+        trigger,
+        triggered_rule: rule.name ?? rule.id,
+      },
+    };
+    const rawBody = JSON.stringify(webhook);
+    const signature = computeSentrySignature(rawBody, String(rule.secret));
+    const resource = trigger === 'regression' ? 'error' : 'issue';
+    const headers = {
+      'sentry-hook-resource': resource,
+      'sentry-hook-signature': signature,
+      'sentry-hook-timestamp': String(Math.floor(Date.parse(opts.occurredAt ?? '1970-01-01T00:00:00.000Z') / 1000) || 0),
+      'request-id': hookRequestId(`${rawBody}|${signature}`),
+    };
+    for (const url of rule.endpoints as string[]) {
+      await deliver(url, rawBody, headers);
+      out.push({ url, payload: webhook, signature });
+    }
+  }
+  return out;
+}