@volter/twin-sentry 0.1.0

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

@@ -0,0 +1,22 @@
+export type SentryViolation = {
+    object: string;
+    id: string;
+    field: string;
+    reason: string;
+};
+export type SentryConformanceReport = {
+    ok: boolean;
+    resourcesChecked: number;
+    fieldsChecked: number;
+    violations: SentryViolation[];
+};
+/**
+ * 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 declare function checkSentryConformance(opts?: {
+    root?: string;
+}): Promise<SentryConformanceReport>;
+/** Per-object coverage: required-field count covered vs. declared (the offline coverage view). */
+export declare function sentryConformanceFields(): Record<string, number>;

package/dist/src/sentry-conformance.js

@@ -0,0 +1,97 @@
+// 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 } from "./sentry-twin.js";
+import { DEFAULT_ORG, DEFAULT_PROJECT, DEFAULT_PROJECT_ID, DEFAULT_PUBLIC_KEY } from "./sentry-ingest.js";
+// 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 = {
+    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'],
+};
+function checkObject(object, body) {
+    const required = REQUIRED_FIELDS[object] ?? [];
+    const violations = [];
+    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 = {}) {
+    const root = opts.root ?? mkdtempSync(join(tmpdir(), 'sentry-conf-'));
+    const own = !opts.root;
+    const occurredAt = '2026-01-01T00:00:00.000Z';
+    const h = (method, path, body) => handleSentryTwinRequest({ method, path, body: body === undefined ? undefined : JSON.stringify(body), root, occurredAt, headers: {} });
+    const ingest = (event) => 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 = [];
+    let resourcesChecked = 0;
+    let fieldsChecked = 0;
+    const check = (object, body) => {
+        if (!body || typeof body !== 'object')
+            return;
+        resourcesChecked++;
+        const r = checkObject(object, body);
+        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.id;
+        const id2 = e2.body.id;
+        const issuesRes = await h('GET', `/api/0/projects/${DEFAULT_ORG}/${DEFAULT_PROJECT}/issues/?query=`);
+        const issues = issuesRes.body;
+        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[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[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() {
+    return Object.fromEntries(Object.entries(REQUIRED_FIELDS).map(([k, v]) => [k, v.length]));
+}

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

@@ -0,0 +1,77 @@
+import type { PerformContext, PushOutcome, RemoteExecute, SyncResource, TwinAction } from '@volter/world-core';
+import { SentryBudget, type SentryBudgetOptions } from './sentry-budget.js';
+/**
+ * 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 declare function liveSentryExecute(token: string, base?: string, opts?: LiveSentryOptions): SentryExecute;
+export declare function mapIssue(i: Record<string, unknown>): SyncResource;
+export declare function mapProject(p: Record<string, unknown>): SyncResource;
+export declare function mapRelease(r: Record<string, unknown>, orgSlug: string): SyncResource;
+export declare function pullSentryIssues(execute: SentryExecute, org: string, project: string, opts?: {
+    query?: string;
+}): Promise<SyncResource[]>;
+export declare function pullSentryProjects(execute: SentryExecute): Promise<SyncResource[]>;
+export declare function pullSentryReleases(execute: SentryExecute, org: string): Promise<SyncResource[]>;
+/** Pull issues + projects + releases from real Sentry and fold them into the event log. */
+export declare function syncSentryFromReal(execute: SentryExecute, opts: {
+    org: string;
+    project: string;
+    root?: string;
+    occurredAt: string;
+}): Promise<{
+    pulled: number;
+}>;
+/** The real-Sentry request for a pending action (PUT /api/0/issues/:id/ with the patch). */
+export declare function sentryRequestForAction(action: Pick<TwinAction, 'operation' | 'subject' | 'fields'>): {
+    method: 'PUT';
+    path: string;
+    body: Record<string, unknown>;
+};
+/** Push ONE pending issue.update action to REAL Sentry via the injected executor. */
+export declare function pushSentryAction(execute: SentryExecute, action: Pick<TwinAction, 'operation' | 'subject' | 'fields'>): Promise<{
+    externalId: string;
+}>;
+/** The pack's executor over the kernel's: the same Sentry REST call, carried by the head. */
+export declare function sentryExecuteOver(execute: RemoteExecute): SentryExecute;
+/** The refresh adapter: pull the organization's projects and issues through the executor. */
+export declare function syncSentryFromRemote(execute: RemoteExecute, opts?: {
+    root?: string;
+    origin?: string;
+    occurredAt?: string;
+    org?: string;
+    project?: string;
+}): Promise<{
+    pulled: number;
+}>;
+/** 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 declare function performSentryAction(execute: RemoteExecute, action: TwinAction, _ctx: PerformContext): Promise<PushOutcome>;

package/dist/src/sentry-connector.js

@@ -0,0 +1,226 @@
+// 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 { SentryBudget, SentryBudgetError, sentryCallWeight } from "./sentry-budget.js";
+const SERVICE = 'sentry';
+/**
+ * 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, base = 'https://sentry.io', opts = {}) {
+    // `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 = { Authorization: `Bearer ${token}` };
+        const init = { 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 = {};
+        res.headers.forEach((v, k) => { 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) {
+    return {
+        type: 'issue', id: String(i.id),
+        fields: {
+            projectId: i.project && typeof i.project === 'object' ? String(i.project.id ?? '') : String(i.projectId ?? ''),
+            projectSlug: i.project && typeof i.project === 'object' ? String(i.project.slug ?? '') : String(i.projectSlug ?? ''),
+            shortId: i.shortId ?? null,
+            title: i.title ?? (i.metadata && i.metadata.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) {
+    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.slug ?? '') : String(p.organizationSlug ?? ''),
+            dateCreated: p.dateCreated ?? null,
+        },
+    };
+}
+export function mapRelease(r, orgSlug) {
+    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, org, project, opts = {}) {
+    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));
+}
+export async function pullSentryProjects(execute) {
+    const res = await execute('GET', `/api/0/projects/`);
+    return (Array.isArray(res) ? res : []).map((p) => mapProject(p));
+}
+export async function pullSentryReleases(execute, org) {
+    const res = await execute('GET', `/api/0/organizations/${org}/releases/`);
+    return (Array.isArray(res) ? res : []).map((r) => mapRelease(r, org));
+}
+/** Pull issues + projects + releases from real Sentry and fold them into the event log. */
+export async function syncSentryFromReal(execute, opts) {
+    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) {
+    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) {
+    const fields = action.fields ?? {};
+    const patch = {};
+    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, action) {
+    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.detail ?? 'unknown error'}`);
+    }
+    const id = res?.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) {
+    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);
+        }
+        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, opts = {}) {
+    // 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, action, _ctx) {
+    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/dist/src/sentry-events.d.ts

@@ -0,0 +1,54 @@
+import type { TwinResource } from '@volter/world-core';
+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;
+/** HMAC-SHA256(secret, rawBody) as lowercase hex — Sentry's Sentry-Hook-Signature. */
+export declare function computeSentrySignature(rawBody: string, secret: string): string;
+export declare class SentrySignatureVerificationError extends Error {
+    constructor(message: string);
+}
+/** Verify a delivered webhook body against the header signature + secret (constant-time). */
+export declare function verifySentrySignature(rawBody: string, signatureHeader: string | undefined, secret: string): boolean;
+/** Verify or throw (mirrors a consumer's "reject bad signature" branch). */
+export declare function constructSentryWebhook(rawBody: string, signatureHeader: string | undefined, secret: string): SentryWebhook;
+export type AlertTrigger = 'new-issue' | 'regression';
+export declare function registerAlertRule(rule: {
+    id: string;
+    projectId: string;
+    name?: string;
+    triggers: AlertTrigger[];
+    endpoints: string[];
+    secret: string;
+    installationUuid?: string;
+}, opts?: {
+    root?: string;
+    occurredAt?: string;
+}): Promise<void>;
+export declare function listAlertRules(projectId: string | undefined, root?: string): TwinResource[];
+/**
+ * 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 declare function emitIssueAlert(trigger: AlertTrigger, issue: Record<string, unknown>, opts?: {
+    root?: string;
+    deliver?: SentryWebhookDelivery;
+    occurredAt?: string;
+}): Promise<Array<{
+    url: string;
+    payload: SentryWebhook;
+    signature: string;
+}>>;

package/dist/src/sentry-events.js

@@ -0,0 +1,131 @@
+// 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 { worldEgressRefusal } from '@volter/world-core/network-policy';
+const SERVICE = 'sentry';
+function 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');
+}
+/** HMAC-SHA256(secret, rawBody) as lowercase hex — Sentry's Sentry-Hook-Signature. */
+export function computeSentrySignature(rawBody, secret) {
+    return nodeCrypto().createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex');
+}
+export class SentrySignatureVerificationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'SentrySignatureVerificationError';
+    }
+}
+/** Verify a delivered webhook body against the header signature + secret (constant-time). */
+export function verifySentrySignature(rawBody, signatureHeader, secret) {
+    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, signatureHeader, secret) {
+    if (!verifySentrySignature(rawBody, signatureHeader, secret)) {
+        throw new SentrySignatureVerificationError('Sentry-Hook-Signature does not match the expected signature for payload.');
+    }
+    return JSON.parse(rawBody);
+}
+function rows(type, root) {
+    return projectResources(SERVICE, root).filter((r) => r.type === type);
+}
+export async function registerAlertRule(rule, opts = {}) {
+    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, root) {
+    return rows('alert_rule', root).filter((r) => !r.deleted && (projectId === undefined || r.projectId === projectId));
+}
+// ── Webhook emission on issue lifecycle ──────────────────────────────────────────
+const httpDelivery = 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) {
+    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, issue, opts = {}) {
+    const projectId = String(issue.projectId ?? '');
+    const rules = listAlertRules(projectId, opts.root).filter((r) => Array.isArray(r.triggers) && r.triggers.includes(trigger));
+    if (rules.length === 0)
+        return [];
+    const deliver = opts.deliver ?? httpDelivery;
+    const action = trigger === 'new-issue' ? 'created' : 'triggered';
+    const out = [];
+    for (const rule of rules) {
+        const installationUuid = String(rule.installationUuid ?? `inst_${rule.id}`);
+        const webhook = {
+            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) {
+            await deliver(url, rawBody, headers);
+            out.push({ url, payload: webhook, signature });
+        }
+    }
+    return out;
+}