@volter/twin-sentry 0.1.36 → 1.0.0

package/README.md

@@ -1,142 +1,29 @@
 # @volter/twin-sentry
 
-A local **Sentry** twin — a faithful, stateful local Sentry error-monitoring API your real
-`@sentry/node` SDK talks to **unmodified**. Point your SDK's DSN at the twin and a normal
-`Sentry.captureException()` lands an event that the twin **groups into an issue**; browse the
-issues/events/releases through the real Web API (`/api/0/...`) or the dashboard mirror.
-Mirror real Sentry, simulate, and fork. Built on `@volter/world-core`.
+Sentry's Protocol 3 twin serves the demanded applications in [journeys/demand.json](./journeys/demand.json).
+The API and ingest share one vendor store.
 
-It is **two API families over one local event-sourced state** (the `@volter/world-core` kernel):
+| Wire | Behavior | Evidence |
+|---|---|---|
+| DSN hosts, `POST /api/<project>/envelope/` | Error/message events and issues, transactions, sessions, client reports, attachments, replay, profiles, cron check-ins and monitor configuration, feedback, logs and metrics. Receipt bytes and unknown items are retained in blobs. Plain, gzip, deflate, brotli and zstd requests; browser CORS. | [ingest/spec](./ingest/spec/SOURCE.md), with retained reference bytes and an offline writer |
+| `sentry.io`, `us.sentry.io`, `de.sentry.io` | sentry-cli release creation, finalization, commits and previous-release lookup, repository listing and source-map chunk/artifact uploads; account project creation and client-key reads; declared vendor refresh reads. | [api/spec](./api/spec/SOURCE.md), Sentry's pinned OpenAPI document and evidenced patches |
 
-1. **Ingestion (the SDK side)** — `POST /api/:projectId/store/` and `/api/:projectId/envelope/`,
-   authenticated by the DSN public key (`X-Sentry-Auth` / `?sentry_key=` / envelope `dsn`). The
-   twin derives a **deterministic fingerprint**, **groups** events into issues, increments
-   `count` + `firstSeen`/`lastSeen`, persists the event, and returns the event id. A new event on
-   a resolved/ignored issue **reopens** it (regression).
-2. **Web API (the dashboard side, `/api/0/...`)** — issues (list with `query`/`sort`, retrieve,
-   resolve/ignore/unresolve/assign, delete, events), events, projects + keys/DSN, releases +
-   deploys + commits, organizations + teams, and alert rules + **signed webhooks**.
+The application's SDK authenticates ingestion with its public DSN key. API calls use scoped personal tokens or
+organization CI tokens, stored by their hash. The credential door is bootstrap signup: it creates the account,
+first token, project and client key named by the environment, returning the same credentials at every boot.
+Additional projects are created through `createOrganizationProject`; their DSNs are read through `listProjectKeys`.
 
-No real Sentry is ever contacted on the serve path — it's fully local and offline. Real vendor
-I/O happens **only in the connector**, over an **injected client** (a fake in tests, a real
-token-authed client in prod). `readOnly` rejects writes (vendor-shaped 405). An unmodeled
-operation **fails like Sentry** (4xx JSON `{ detail }`) — never a fabricated success.
+World account doors:
 
-## Quick start
+- `POST /_twin/app-credentials`: bootstrap account, first token and env-named project/DSN.
+- `POST /_twin/organizations {slug, name?}`: additional account signup.
+- `POST /_twin/auth-tokens {organization, name, kind?, scopes?}`: organization CI or scoped personal token issuance.
 
-```bash
-# serve the twin (ingestion + Web API); prints the DSN to point @sentry/node at
-bunx world-sentry serve --port 9000
-#   point @sentry/node at DSN: http://twinpublickey...@127.0.0.1:9000/1
+Vendor refresh lists organizations, projects, releases, monitors and check-ins to the end of their declared Link continuation. Events and issues are refreshed by their known subject ids, through the core's declared path mappings. Client keys stay under credential custody. Telemetry receipt is not deployed as an account change.
+Sentry's API rate-limit page gives endpoint-specific response headers, without a numerical global allowance.
 
-# the dashboard mirror (React)
-bunx world-sentry mirror --port 9001
-
-# offline shape conformance
-bunx world-sentry conformance
-```
-
-```ts
-import * as Sentry from '@sentry/node';
-Sentry.init({ dsn: 'http://twinpublickey00000000000000000000@127.0.0.1:9000/1' });
-Sentry.captureException(new Error('boom')); // → a grouped issue in the twin
-```
-
-## Coverage
-
-The honest denominator is the **capability manifest** (`src/sentry-capabilities.ts`): the real
-Sentry surface, ranked core → common → niche, where every `done` capability is proven by an
-**offline** `verify()` that drives real ingest/create → read → assert against the twin. The
-baseline test (`src/sentry-capabilities.test.ts`) asserts via `assertManifestBaseline`: total
-≥ 50, done > 0, **0 regressions**. Every capability is either `done` or `todo`.
-
-**Modeled (core → niche):**
-
-- **Ingestion** — store + envelope endpoints, DSN public-key auth (header/query/envelope),
-  message + exception events, deterministic grouping (incl. number normalization), distinct
-  grouping, regression reopen, culprit from the top in-app frame.
-- **Issues** — list (`query` DSL: `is:`, `level:`, free text; `sort=date|freq|new`), retrieve,
-  resolve/ignore/unresolve/assign, delete, events + latest event, shortId/permalink/metadata,
-  **bulk** resolve/ignore (`?query`/`?id`), **merge** groups, **tag value distributions**
-  (`/tags/`, `/tags/:key/`), **grouping hashes** (`/hashes/`), **activity feed** (`/activity/`),
-  **user feedback** (`/user-feedback/`: submit + list crash-report comments, linked to the event's issue).
-- **Events** — list, retrieve, tags/level/platform, exception stacktrace entries,
-  **attachments listing** (envelope `attachment` items → per-event metadata), **org event facets**
-  (`/events-facets/`: tag-value `topValues` distributions across the org's persisted events).
-- **Projects** — list/retrieve/create/update/delete, project **keys/DSN** (list + create +
-  toggle/revoke/**delete** + **per-key rate-limit** config), **environments** (distinct envs),
-  **ownership rules + CODEOWNERS** (path/url/module → owners, schema-parsed), **inbound data
-  filters** (browser-extensions / legacy-browsers / localhost / web-crawlers toggles), **spike
-  protection** (org-level enable/disable per project — `/spike-protections/`).
-- **Releases** — create/list/retrieve/update/delete, associate commits, **deploys**, **release
-  files / artifact registry** (source-map upload metadata), **commit files** (`/commitfiles/`:
-  files changed across a release's commits, flattened from each commit's patch set), **release
-  health** (crash-free session tallies over real persisted session envelopes — `/organizations/:org/sessions/`).
-- **Organizations + teams** — list/retrieve/create/update/delete (org), list/create (teams),
-  **org members** (invite / list / role change / remove), **team membership** add/remove,
-  **SCIM 2.0 provisioning** (Users + Groups CRUD under `/scim/v2/` with faithful SCIM
-  envelopes / ListResponse / 409-on-duplicate), **org stats** (`stats_v2` totals over real
-  events), **integrations** (GitHub/Slack/PagerDuty install + config CRUD), **custom dashboards
-  + widgets**, **Discover saved queries**.
-- **Alerts + webhooks** — issue alert rules with **actions** (email/Slack/PagerDuty/MS Teams,
-  validated per-type), **metric alert rules** (`/alert-rules/`: aggregate + dataset + thresholds
-  with critical/warning triggers), **signed** (HMAC-SHA256 `Sentry-Hook-Signature`) webhooks on
-  **new-issue** + **regression** via an **injected deliverer** (offline `verify()`).
-- **Mirror UI** — Issues stream (grouped errors: count / last-seen / level / status), Issue
-  detail (latest-event stacktrace + tags), **Dashboards** (custom widgets), **Discover** (query
-  builder scaffold + saved queries), Releases, Projects, **Alerts** (issue alert rules),
-  **Settings** (general / client keys-DSN / environments) — all backed by real twin state.
-- **Connector** — pull (issues/projects/releases) + push (issue triage: resolve/ignore/assign)
-  over an injected executor, with confirm + idempotent re-push.
-
-**Planned (`todo`) — the deeper engines Sentry runs that this twin has not built yet:**
-
-- **Symbolication** (`sentry.events.symbolication`) — de-minify stacktrace frames against uploaded
-  source maps and debug files. Raw frames and the artifact registry are already faithful.
-- **Span percentile aggregation** (`sentry.performance.span_aggregation`) — p50/p75/p95 computed
-  over the transaction and span events the twin already stores, plus the trace and time-series read
-  endpoints that serve it.
-- **Session Replay segment ingest** (`sentry.replay.segment_ingest`) — accept and persist the
-  recorded rrweb/DOM segment uploads and serve the replay list, detail and segment reads.
-- **Continuous profiling** (`sentry.performance.profiling`) — accept sampled stack-profile envelopes
-  and serve the flamegraph aggregation computed over them.
-- **Grouping enhancements** (`sentry.ingest.grouping_enhancements`) — stack-aware
-  grouping-enhancement rules, fingerprint rules and frame heuristics on top of the deterministic
-  base fingerprint (exception type + value + culprit, or message, numbers normalized), which is
-  documented and already faithful-but-simple.
-- **Cron monitors** (`sentry.crons.monitors`) — check-in endpoints plus a deterministic
-  heartbeat-miss detection engine over stored check-ins.
-
-Several config-modeled surfaces persist and round-trip their CONFIG faithfully while their live
-EXECUTION is likewise unbuilt: metric-alert threshold evaluation/firing, Discover arbitrary query
-execution (the builder and saved queries are real), and attachment binary download (the metadata
-listing is real; the bytes need a blob store). Alert-action config persists and round-trips, and no
-notification is sent. Release-health crash-free counts ARE real exact tallies over persisted
-sessions; only the time-series rollup is absent.
-
-## Architecture
-
-State and execution follow the shared [model](../../../docs/concepts/the-model.md) and
-[architecture](../../../docs/contributing/architecture.md). The kernel owns storage and execution
-mechanics; this package owns vendor semantics. Conformance tooling is a development dependency.
-The [generated index](../../../generated/INDEX.md) records this package's protocol standing.
-
-## Rate budget — the fail-closed backstop on live calls
-
-`liveSentryExecute` is the **one place** this pack issues a live request, so every call it makes is charged
-against a persistent, fail-closed spend ledger **before** the request goes out. Past the ceiling, or
-while a `Retry-After`/429 cooldown is armed, it **throws instead of calling**. The ledger is keyed by
-vendor and a hash of the credential (limits are per credential, so it is deliberately *not*
-cwd-scoped) and persists across processes, so a fresh process does not get a fresh allowance; a
-corrupt ledger counts as a **full** window rather than zero spend. There is no option to disable it,
-and no value you can pass for `budget` that yields an unguarded client — an injected budget is
-validated by *method identity*, so a subclass or a `Proxy` that replaces `checkBudget` is refused.
-
-The declared numbers: **60 weighted units / 60s at weight 2 = 30 calls/minute — exactly the kernel's austere fallback**, because Sentry publishes *no* figure at all (per-endpoint windows, unstated). What the guard buys for an unknowable limit is the **cooldown**: `X-Sentry-Rate-Limit-Remaining: 0` and `Retry-After` become a persisted client-side stop instead of a retry storm. Issue/event list reads cost 4 — the paginated firehose the docs tell you not to poll.
-
-The mechanism is **shared and vendor-agnostic** — it lives in the kernel (`@volter/world-core` →
-`packages/world-core/src/rateBudget.ts`); what lives here in [`src/sentry-budget.ts`](src/sentry-budget.ts) is this vendor's
-**declaration** (window, ceiling, per-endpoint weights, and a `reason` citing the limits above) plus
-the vendor-bound `SentryBudget`. The rule is ratified as
-[../../../docs/contributing/architecture.md](../../../docs/contributing/architecture.md) **D8**, and the kernel module's header documents what the
-guard does *not* guarantee — read that before trusting it.
+Every other API operation is the declared gap. Source maps are retained and assembled, without server symbolication.
+Grouping follows explicit fingerprints, stack frames, exception or message; Sentry's configurable grouping engine is
+not reproduced. Repository integrations, release deploys, team membership and additional client-key creation are
+outside the demanded calls. Cron outcomes come from received check-ins; scheduled missed/timeout outcomes are not
+synthesized. [STANDING.md](../STANDING.md) owns the procedure's form.

package/api/spec/SOURCE.md

@@ -0,0 +1,15 @@
+# Sentry's API
+
+- **Why this document:** Sentry's own OpenAPI document for its web API, as it publishes it for its API reference:
+  getsentry/sentry-api-schema at `98ec014705fbecf18c2650097e4630afe51ffd85` (2026-09-29), `openapi-derefed.json`,
+  vendored gzipped and unchanged (`openapi.json.gz`).
+- **Servers:** `https://{region}.sentry.io` (us, de); sentry-cli and the applications call `https://sentry.io/api/0/`.
+- **Corrections** (`patches.json`, each with its evidence): the chunk upload (`/chunk-upload/`) and artifact bundle assembly
+  (`/artifactbundle/assemble/`) that sentry-cli uploads source maps through; and a single project's release paths
+  sentry-cli uses; and its previous-release-with-commits lookup during local git fallback. Their evidence is getsentry/sentry at `2efdd4760a75a3d395e3534b7f66a7fbb0c3f22e` and
+  getsentry/sentry-cli 2.58.4 and 2.58.5 (the versions the applications lock).
+
+- **Resource normalization:** the five refresh reads reference named copies of their unchanged inline response schemas. The patches cite each operation in the pinned upstream document; no wire field is added or removed.
+
+- **Vendored document SHA-256** (openapi.json.gz, decompressed bytes where gzipped): `bb07d2bb747b10b31c14722066cd1d11bd0bb76eea8dcfb5f341b4c421c1c1f9`.
+- **Read by:** Codex contributor.

package/api/spec/doc-examples.json

@@ -0,0 +1,12 @@
+[
+    {
+        "title": "Event read requires the project scope",
+        "operation": "getProjectEvent",
+        "source": "https://raw.githubusercontent.com/getsentry/sentry-api-schema/98ec014705fbecf18c2650097e4630afe51ffd85/openapi-derefed.json",
+        "means": "getProjectEvent",
+        "status": 403,
+        "output": {
+            "detail": "You do not have permission to perform this action."
+        }
+    }
+]