@volter/twin-sentry 0.1.37 → 1.0.1

package/package.json

@@ -1,75 +1,50 @@
 {
   "name": "@volter/twin-sentry",
-  "version": "0.1.37",
-  "description": "Local Sentry twin — a faithful, stateful local Sentry error-monitoring API your real `@sentry/node` SDK talks to unmodified. Ingest captureException events into grouped issues, browse the Web API + dashboard mirror, simulate, and fork. Built on @volter/world-core.",
+  "version": "1.0.1",
+  "description": "Sentry Protocol 3 twin: demanded SDK envelopes, release/source-map APIs, account project and client-key setup, and derived vendor-backed reads.",
   "keywords": [
     "twin",
-    "local",
-    "mock",
-    "mirror",
-    "simulator",
-    "fixtures",
-    "testing",
-    "sdk",
-    "api",
-    "localstack",
     "sentry",
-    "error-monitoring",
-    "observability"
+    "error-tracking",
+    "envelope",
+    "sentry-cli",
+    "source-maps"
   ],
   "author": "Volter (https://github.com/volter-ai)",
   "license": "Apache-2.0",
   "files": [
     "src",
-    "client",
-    "test-fixtures",
+    "journeys",
+    "api",
+    "spec",
+    "ingest",
     "README.md",
     "LICENSE",
     "!**/*.test.ts",
-    "!**/*.test.tsx",
-    "dist"
+    "dist",
+    "generated"
   ],
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/volter-ai/twin.git",
-    "directory": "packages/twin/sentry"
+    "url": "git+https://github.com/volter-ai/twin-packs-open.git",
+    "directory": "sentry"
   },
-  "homepage": "https://world.volter.ai/twins/sentry",
+  "homepage": "https://github.com/volter-ai/twin-packs-open/tree/main/sentry#readme",
   "type": "module",
   "exports": {
-    ".": {
-      "types": "./dist/src/index.d.ts",
-      "default": "./dist/src/index.js"
-    }
+    ".": "./dist/src/index.js"
   },
   "bin": {
-    "world-sentry": "dist/src/cli.js"
-  },
-  "scripts": {
-    "test": "bun test src/*.test.ts",
-    "typecheck": "tsc --noEmit",
-    "build": "node ../../../scripts/publish/build.mjs",
-    "prepack": "node ../../../scripts/publish/prepare-publish.mjs prepack",
-    "postpack": "node ../../../scripts/publish/prepare-publish.mjs postpack"
-  },
-  "dependencies": {
-    "react": "^19.2.7",
-    "react-dom": "^19.2.7"
+    "world-sentry": "./dist/src/cli.js"
   },
   "peerDependencies": {
-    "@volter/world-core": "2.0.37"
-  },
-  "devDependencies": {
-    "@volter/world-core": "2.0.37",
-    "@volter/world-tooling": "0.1.0",
-    "@sentry/node": "^10.64.0",
-    "@types/bun": "^1.2.20",
-    "@types/node": "^24.0.0",
-    "@types/react": "^19.2.17",
-    "@types/react-dom": "^19.2.3",
-    "typescript": "^5.9.0"
+    "@volter/world-core": ">=3.0.163",
+    "@volter/world-runtime": ">=3.0.184"
   },
   "engines": {
     "node": ">=22.3"
+  },
+  "bugs": {
+    "url": "https://github.com/volter-ai/twin-packs-open/issues"
   }
 }

package/spec/sources.json

@@ -0,0 +1,76 @@
+{
+  "https://raw.githubusercontent.com/getsentry/sentry/2efdd4760a75a3d395e3534b7f66a7fbb0c3f22e/src/sentry/api/serializers/models/project_key.py": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "ProjectKeySerializerResponse": true
+    }
+  },
+  "https://raw.githubusercontent.com/getsentry/sentry/2efdd4760a75a3d395e3534b7f66a7fbb0c3f22e/src/sentry/features/permanent.py": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "organizations:advanced-search": true,
+      "organizations:change-alerts": true,
+      "organizations:crash-rate-alerts": true,
+      "organizations:custom-symbol-sources": true,
+      "organizations:data-forwarding": true,
+      "organizations:discover-basic": true,
+      "organizations:discover-query": true,
+      "organizations:event-attachments": true,
+      "organizations:integrations-alert-rule": true,
+      "organizations:integrations-chat-unfurl": true,
+      "organizations:integrations-codeowners": true,
+      "organizations:integrations-enterprise-alert-rule": true,
+      "organizations:integrations-enterprise-incident-management": true,
+      "organizations:integrations-event-hooks": true,
+      "organizations:integrations-incident-management": true,
+      "organizations:integrations-issue-basic": true,
+      "organizations:integrations-issue-sync": true,
+      "organizations:integrations-scm-multi-org": true,
+      "organizations:integrations-stacktrace-link": true,
+      "organizations:integrations-ticket-rules": true,
+      "organizations:integrations-vercel": true,
+      "organizations:performance-view": true,
+      "organizations:relay": true,
+      "organizations:sso-basic": true,
+      "organizations:sso-saml2": true,
+      "organizations:team-insights": true,
+      "organizations:team-roles": true,
+      "organizations:uptime": true
+    }
+  },
+  "https://raw.githubusercontent.com/getsentry/sentry/2efdd4760a75a3d395e3534b7f66a7fbb0c3f22e/src/sentry/features/temporary.py": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "organizations:dashboards-basic": true,
+      "organizations:dashboards-edit": true,
+      "organizations:insight-modules": true,
+      "organizations:invite-members": true,
+      "organizations:sentry-app-schema-form-migration": true,
+      "organizations:session-replay-ui": true
+    }
+  },
+  "https://raw.githubusercontent.com/getsentry/sentry/2efdd4760a75a3d395e3534b7f66a7fbb0c3f22e/src/sentry/models/projectkey.py": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "secret_key = ProjectKey.generate_api_key()": true
+    }
+  },
+  "https://raw.githubusercontent.com/getsentry/sentry/2efdd4760a75a3d395e3534b7f66a7fbb0c3f22e/src/sentry/projectoptions/defaults.py": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "sentry:default_loader_version": true
+    }
+  },
+  "https://raw.githubusercontent.com/getsentry/sentry/2efdd4760a75a3d395e3534b7f66a7fbb0c3f22e/src/sentry/utils/numbers.py": {
+    "status": 200,
+    "checked": "2026-10-03",
+    "quotes": {
+      "0123456789ABCDEFGHJKMNPQRSTVWXYZ": true
+    }
+  }
+}

package/src/cli.ts

@@ -1,34 +1,22 @@
 #!/usr/bin/env node
-import { keepProcessAlive } from '@volter/world-core/lifecycle';
-// world-sentry CLI: serve the Sentry API twin (ingestion + Web API), the dashboard mirror
-// UI, or run conformance. (Conformance lives in dev-tooling; cli.ts must not import it, so
-// it's loaded lazily only when the `conformance` command is invoked.)
+// world-sentry: serve the sentry twin.
 import { hasFlag, optionValue } from '@volter/world-core/args';
-import { createSentryTwinServer } from './sentry-server.ts';
-import { createSentryMirrorServer } from './sentry-mirror-ui.ts';
-import { defaultDsn } from './sentry-ingest.ts';
+import { keepProcessAlive } from '@volter/world-core/lifecycle';
+import { createSentryTwinServer } from './server.ts';
 
 const [cmd, ...rest] = process.argv.slice(2);
 const port = Number(optionValue(rest, '--port', '0')) || undefined;
 const root = optionValue(rest, '--root') || undefined;
-const readOnly = hasFlag(rest, '--read-only'); // a twin accepts writes/events unless read-only
+const readOnly = hasFlag(rest, '--read-only');
+// the selected twin's private Postgres, which the runtime binds a pack declaring managedDatabase to
+const database = optionValue(rest, '--database') || undefined;
+// the World's scenario file, for a model vendor's turns
+const scenarioPath = optionValue(rest, '--scenario') || undefined;
 
-if (cmd === 'serve') {
-  const s = await createSentryTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}) });
-  const origin = `http://127.0.0.1:${s.port}`;
-  process.stdout.write(`sentry twin (ingest + Web API)${readOnly ? ' [read-only]' : ''} at ${origin}\n`);
-  process.stdout.write(`  point @sentry/node at DSN: ${defaultDsn(origin)}\n`);
-  await keepProcessAlive();
-} else if (cmd === 'mirror') {
-  const s = await createSentryMirrorServer({ ...(root ? { root } : {}), ...(port ? { port } : {}) });
-  process.stdout.write(`sentry mirror UI (dashboard) at http://127.0.0.1:${s.port}\n`);
+if (cmd === 'serve' || cmd === undefined) {
+  const s = await createSentryTwinServer({ readOnly, ...(root ? { root } : {}), ...(port ? { port } : {}), ...(database ? { database } : {}), ...(scenarioPath ? { scenarioPath } : {}) });
+  process.stdout.write(`sentry twin${readOnly ? ' [read-only]' : ''} at http://127.0.0.1:${s.port}\n`);
   await keepProcessAlive();
-} else if (cmd === 'conformance') {
-  // dev-only: dynamic import so the conformance module never enters the runtime entrypoints.
-  const { checkSentryConformance } = await import('./sentry-conformance.ts');
-  const report = await checkSentryConformance({ ...(root ? { root } : {}) });
-  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
-  if (!report.ok) process.exitCode = 1;
 } else {
-  process.stdout.write('Usage: world-sentry serve|mirror|conformance [--port N] [--root DIR] [--read-only]\n');
+  process.stdout.write('Usage: world-sentry serve [--port N] [--root DIR] [--read-only] [--database URL] [--scenario FILE]\n');
 }

package/src/fetch.ts

@@ -0,0 +1,10 @@
+// GENERATED by scripts/create-pack.ts (--init, --index): a fixed file. The kernel serves the vendor's discovery door and
+// sends each request to the lane its manifest's routes name (architecture, "Other wires: lanes").
+import { createVendorFetch, type DerivedFetch, type PackFetchOptions } from '@volter/world-core';
+import { manifest } from './manifest.ts';
+import { createApiLaneFetch, manifest as api_manifest } from '../api/src/index.ts';
+import { createIngestLaneFetch, manifest as ingest_manifest } from '../ingest/src/index.ts';
+
+export function createSentryFetch(options: PackFetchOptions = {}): DerivedFetch {
+  return createVendorFetch(manifest, { "api": { fetch: createApiLaneFetch(options), manifest: api_manifest }, "ingest": { fetch: createIngestLaneFetch(options), manifest: ingest_manifest } });
+}

package/src/index.ts

@@ -1,145 +1,15 @@
-// @volter/twin-sentry — the Sentry twin (one vendor, one package), built on the shared
-// @volter/world-core kernel. Two API families over local event-sourced state: INGESTION (the
-// `@sentry/node` store/envelope endpoints → grouped issues) and the WEB API (/api/0/...:
-// issues, events, projects, keys/DSN, releases, deploys, orgs, teams, alert rules), plus
-// signed alert webhooks and a React dashboard mirror. No real Sentry is ever contacted.
-// (Conformance tooling lives in @volter/world-tooling, a dev dependency — not shipped here.)
-export { handleSentryTwinRequest } from './sentry-twin.ts';
-export type { SentryRequest, SentryResponse } from './sentry-twin.ts';
-export { createSentryTwinFetch, createSentryTwinServer, type SentryTwinFetchOptions } from './sentry-server.ts';
-export {
-  defaultDsn,
-  DEFAULT_ORG,
-  DEFAULT_PROJECT,
-  DEFAULT_PROJECT_ID,
-  DEFAULT_PUBLIC_KEY,
-  ensureDefaultProject,
-  envelopeEvents,
-  eventCulprit,
-  eventTitle,
-  fingerprintText,
-  hashFingerprint,
-  ingestEvent,
-  issueIdFor,
-  normalizeFingerprintText,
-  parseEnvelope,
-  publicKeyFromAuthHeader,
-  publicKeyFromDsn,
-  resolveProjectKey,
-  resolvePublicKey,
-} from './sentry-ingest.ts';
-export type { IngestOutcome, ParsedEnvelope, ResolvedKey, SentryEventPayload, SentryExceptionValue, SentryFrame } from './sentry-ingest.ts';
-export {
-  computeSentrySignature,
-  constructSentryWebhook,
-  emitIssueAlert,
-  listAlertRules,
-  registerAlertRule,
-  SentrySignatureVerificationError,
-  verifySentrySignature,
-} from './sentry-events.ts';
-export type { AlertTrigger, SentryWebhook, SentryWebhookAction, SentryWebhookDelivery } from './sentry-events.ts';
-export {
-  liveSentryExecute,
-  mapIssue,
-  mapProject,
-  mapRelease,
-  pullSentryIssues,
-  pullSentryProjects,
-  pullSentryReleases,
-  pushSentryAction,
-  sentryRequestForAction,
-  syncSentryFromReal,
-} from './sentry-connector.ts';
-export type { SentryExecute, LiveSentryOptions } from './sentry-connector.ts';
-// The client-side rate budget — the fail-closed backstop `liveSentryExecute` routes every live
-// request through. The MECHANISM is the kernel's shared, vendor-agnostic `RateBudget`; what lives
-// here is Sentry's DECLARATION (window/ceiling/per-endpoint weights) plus the vendor-bound
-// bindings. Exported so an operator can inspect spend (`snapshot`) and so a caller can catch
-// `SentryBudgetError` by type; there is deliberately no export that disables the guard.
-export {
-  SENTRY_BUDGET_CEILING,
-  SENTRY_BUDGET_MAX_RETRY_AFTER_S,
-  SENTRY_BUDGET_WINDOW_MS,
-  SENTRY_CALL_WEIGHTS,
-  SENTRY_RATE_BUDGET,
-  SentryBudget,
-  SentryBudgetError,
-  sentryBudgetPath,
-  sentryCallWeight,
-} from './sentry-budget.ts';
-export type { SentryBudgetErrorKind, SentryBudgetOptions, SentryBudgetReservation, SentryBudgetSnapshot } from './sentry-budget.ts';
-export {
-  buildSentryMirrorClient,
-  createSentryMirrorServer,
-  eventTags,
-  formatCount,
-  latestStacktrace,
-  levelTone,
-  sentryMirrorHtml,
-  statusTone,
-  timeAgo,
-} from './sentry-mirror-ui.ts';
-export type { IssueRow, StackFrame } from './sentry-mirror-ui.ts';
+// @volter/twin-sentry — the sentry twin (Protocol 3). A fixed file (create-pack): the descriptor is the manifest's, and the
+// kernel derives the vendor-backed half from the generated surface, unless the manifest declares none (vendorBacked.none;
+// architecture, "The real-system adapters").
+import { packOf, registerPack, type DerivedSurface } from '@volter/world-core';
+import { manifest } from './manifest.ts';
+import { manifest as apiManifest } from '../api/src/manifest.ts';
+import apiSurface from '../api/src/generated/surface.gen.json' with { type: 'json' };
+import { manifest as ingestManifest } from '../ingest/src/manifest.ts';
+import ingestSurface from '../ingest/src/generated/surface.gen.json' with { type: 'json' };
 
-// Registry descriptor: the pack self-describes so tooling can discover it. A consumer does
-// `registerPack(pack)` after importing this package.
-import type { TwinPack } from '@volter/world-core';
-import { SENTRY_RATE_BUDGET as RATE_BUDGET } from './sentry-budget.ts';
-import { performSentryAction, syncSentryFromRemote } from './sentry-connector.ts';
+export { createSentryFetch } from './fetch.ts';
+export { createSentryTwinServer } from './server.ts';
+export { manifest };
 
-export const pack: TwinPack = {
-  // PROTOCOL 2 (docs/contributing/architecture.md#protocol-2-the-pack-is-a-plugin): the pack is a plugin — its wire, its tree, and its half of the real
-  // state system. Moved 2026-09-08. TRIAGE is what crosses to Sentry — an issue resolved, assigned, muted;
-  // everything else this twin holds is something Sentry told it.
-  protocol: '2',
-  refresh: { every: '2m', webhook: true, onDemand: { atMost: '30s' } },
-  stateSystem: { perform: performSentryAction, refresh: syncSentryFromRemote },
-  // the round trip: an organization, then a project in it — the two things a Sentry account is made of
-  // the round trip: an organization, a team in it, then a project under that team — Sentry's own create
-  // path for a project is /teams/:org/:team/projects/, not the organization
-  roundTrip: [
-    { method: 'POST', path: '/api/0/organizations/', body: { name: 'Round Trip', slug: 'round-trip' }, headers: { authorization: 'Bearer round-trip' } },
-    { method: 'POST', path: '/api/0/organizations/round-trip/teams/', body: { name: 'Round Trip', slug: 'round-trip' }, headers: { authorization: 'Bearer round-trip' } },
-    { method: 'POST', path: '/api/0/teams/round-trip/round-trip/projects/', body: { name: 'Round Trip', platform: 'node' }, headers: { authorization: 'Bearer round-trip' } },
-    // a project's slug is unique inside its org, so the create above rightly refuses a second one on a
-    // branch that already has it — the vendor's own truth. The last write is therefore the one a world
-    // repeats freely: triage on the project's own issue stream.
-    { method: 'PUT', path: '/api/0/projects/round-trip/round-trip/', body: { platform: 'node', digestsMinDelay: 60 }, headers: { authorization: 'Bearer round-trip' } },
-  ],
-  parityOrigin: 'http://twin',
-  vendor: 'sentry',
-  // The SAME object sentry-budget.ts declares at module load — one source of truth, so registering
-  // the pack and importing the connector can never arm two different ceilings.
-  rateBudget: RATE_BUDGET,
-  transport: 'rest',
-  archetype: 'crud',
-  bin: 'world-sentry',
-  resources: ['organization', 'team', 'project', 'project_key', 'issue', 'event', 'event_attachment', 'session', 'project_ownership', 'codeowners', 'project_filter', 'release', 'release_file', 'deploy', 'alert_rule', 'metric_alert', 'org_integration'],
-  specSource: 'Sentry API reference (https://docs.sentry.io/api/) — ingest store/envelope + Web API /api/0/',
-  description: 'Sentry REST twin — SDK ingestion → grouped issues, Web API, signed alert webhooks, dashboard mirror.',
-  // Adoption + interception, moved off the central maps unchanged (descriptor-first back-migration, adding-a-twin.md §3,
-  // 2026-08-31). The four canonical clients plus the further first-party @sentry
-  // framework SDKs of the same ingest surface — battery-observed: sentry was the single
-  // most-missed vendor, 13 repos, largely via these — and the whole `@sentry/` scope so a
-  // satellite package like `@sentry/cli` still detects.
-  adoption: {
-    // Sentry's official Python SDK - the one distribution behind every Python integration.
-    pypi: ['sentry-sdk'],
-    sdks: [
-      '@sentry/node', '@sentry/browser', '@sentry/react', '@sentry/nextjs',
-      '@sentry/vue', '@sentry/sveltekit', '@sentry/astro', '@sentry/remix',
-      '@sentry/electron', '@sentry/react-native',
-    ],
-    scopes: ['@sentry/'],
-    // 'APPSMITHSENTRY' — appsmith names its DSN APPSMITH_SENTRY_DSN, an app-prefixed Sentry
-    // credential for the same ingest surface (ladder classification 2026-09-02).
-    envStems: ['SENTRY', 'APPSMITHSENTRY'],
-  },
-  // sentry.io (the web/REST API) plus the per-organization DSN ingest hosts
-  // (`o<org-id>.ingest.sentry.io`), which need the suffix form.
-  hosts: [{ host: 'sentry.io' }, { suffix: '.ingest.sentry.io' }],
-  // The @sentry/node SDK POSTs to <dsn-host>/api/:projectId/envelope/; the dashboard hits
-  // /api/0/. The dev proxy forwards both prefixes to the twin and strips the sentry.io host.
-  browserRouting: { apiPathPrefix: '/api/', loaderHost: 'https://sentry.io' },
-};
+export const pack = registerPack(packOf(manifest, { "api": { manifest: apiManifest, surface: apiSurface as unknown as DerivedSurface }, "ingest": { manifest: ingestManifest, surface: ingestSurface as unknown as DerivedSurface } }));

package/src/manifest.ts

@@ -0,0 +1,41 @@
+// Sentry's manifest: a vendor of two APIs, each a lane (architecture, "Other wires: lanes"): the web API that sentry-cli
+// and integrations call (`api`, from Sentry's OpenAPI document), and the ingestion endpoint every SDK sends its envelopes
+// to (`ingest`, written from Sentry's SDK developer documentation). A DSN names its organization's ingest host
+// (`o<id>.ingest[.<region>].sentry.io`); the API is sentry.io's, and a region's (us.sentry.io, de.sentry.io).
+import type { VendorManifest } from '@volter/world-core';
+
+export const manifest: VendorManifest = {
+  vendor: 'sentry',
+  discovery: {
+    twinOf: 'Sentry: the envelopes its SDKs send (errors, transactions, sessions, replays, profiles, cron check-ins, feedback, logs, metrics), and its web API for events, issues, releases and source maps',
+    stores: 'organizations, projects and client keys, auth tokens (by their SHA-256), events and issues, and every other envelope item; releases and artifact bundles',
+  },
+  lanes: {
+    routes: [
+      { lane: 'ingest', host: '(^|\\.)ingest(\\.[a-z]+)?\\.sentry\\.io$' },
+      { lane: 'api', host: '^([a-z]+\\.)?sentry\\.io$' },
+    ],
+    default: 'api',
+  },
+  descriptor: {
+    protocol: '3',
+    transport: 'rest',
+    archetype: 'crud',
+    bin: 'world-sentry',
+    resources: ['organization', 'project', 'project_key', 'event', 'issue', 'release', 'monitor', 'check_in'],
+    specSource: "Sentry's OpenAPI document (api/spec, sentry-api-schema 98ec014, patched with evidence) and its SDK developer documentation's envelope endpoint (ingest/spec)",
+    description: 'Sentry twin — the envelope endpoint every SDK sends to (events grouped into issues, transactions, sessions, replays, profiles, check-ins, feedback, logs, metrics), and release and source-map APIs used by Cal.com and Rallly, account project/key setup, and core vendor-backed reads.',
+    adoption: { sdks: ['@sentry/astro', '@sentry/browser', '@sentry/electron', '@sentry/nextjs', '@sentry/node', '@sentry/nestjs', '@sentry/react', '@sentry/react-native', '@sentry/remix', '@sentry/sveltekit', '@sentry/vue', '@sentry/cli'], pypi: ['sentry-sdk'], envStems: ['APPSMITHSENTRY', 'SENTRY'] },
+    hosts: [{ host: 'sentry.io' }, { host: 'us.sentry.io' }, { host: 'de.sentry.io' }, { suffix: '.ingest.sentry.io' }, { suffix: '.ingest.us.sentry.io' }, { suffix: '.ingest.de.sentry.io' }],
+    endpointEnvNone: "an SDK sends to its DSN's host and sentry-cli to SENTRY_URL (sentry.io by default); the DSN the World issues names the World's ingest host, claimed by the host rules",
+    // Bootstrap: account sign-up, first credential and the project/key named by this env, stable at every boot.
+    credentialDoor: { account: { field: 'account', tenancy: 'organization', source: 'https://docs.sentry.io/api/permissions/' },
+      deployment: { field: 'deployment', object: 'project and client key', source: 'https://docs.sentry.io/product/sentry-basics/environments/', organizationOutputs: ['SENTRY_ORG', 'SENTRY_ORGANIZATION'] },
+      path: '/_twin/app-credentials', body: {},
+      fill: {
+        SENTRY_DSN: 'dsn', NEXT_PUBLIC_SENTRY_DSN: 'dsn', NEXT_PUBLIC_SENTRY_DSN_CLIENT: 'dsn', SENTRY_FRONT_DSN: 'dsn', SENTRY_DSN_API: 'dsn', VITE_SENTRY_DSN: 'dsn', EXPO_PUBLIC_SENTRY_DSN: 'dsn',
+        SENTRY_AUTH_TOKEN: 'auth_token', SENTRY_ORG: 'org', SENTRY_ORGANIZATION: 'org', SENTRY_PROJECT: 'project',
+      },
+    },
+  },
+};