@volter/twin-sentry 0.1.37 → 1.0.1

package/api/src/generated/ui.gen.json

@@ -0,0 +1 @@
+{"generatedBy":"scripts/derive-pack.ts","resources":{"organization":{"actions":[],"states":{},"embeds":{}},"project":{"list":"/api/0/organizations/{organization_id_or_slug}/projects/","actions":[],"states":{},"embeds":{}},"project_key":{"actions":[],"states":{},"embeds":{}},"event":{"retrieve":"/api/0/projects/{organization_id_or_slug}/{project_id_or_slug}/events/{event_id}/","actions":[],"states":{},"embeds":{}},"issue":{"retrieve":"/api/0/organizations/{organization_id_or_slug}/issues/{issue_id}/","actions":[],"states":{},"embeds":{}},"release":{"actions":[],"states":{},"embeds":{}},"monitor":{"list":"/api/0/organizations/{organization_id_or_slug}/monitors/","actions":[],"states":{},"embeds":{}},"check_in":{"list":"/api/0/projects/{organization_id_or_slug}/{project_id_or_slug}/monitors/{monitor_id_or_slug}/checkins/","actions":[],"states":{"status":["error","in_progress","ok"]},"embeds":{}},"_seq_token":{"actions":[],"states":{},"embeds":{}},"_seq_event":{"actions":[],"states":{},"embeds":{}},"_seq_envelope":{"actions":[],"states":{},"embeds":{}},"_seq_project_key":{"actions":[],"states":{},"embeds":{}}}}

package/api/src/index.ts

@@ -0,0 +1,3 @@
+// The api lane of the sentry pack: the vendor's manifest routes its requests here.
+export { createApiLaneFetch } from './fetch.ts';
+export { manifest } from './manifest.ts';

package/api/src/manifest.ts

@@ -0,0 +1,137 @@
+// Sentry web API: application release/source-map calls, account setup, and core resource refresh reads.
+// Every API path needs a scoped account token (./semantics/around.ts).
+import { states } from './semantics/states.ts';
+import type { DerivedManifest } from '@volter/world-core';
+
+export const manifest: DerivedManifest = {
+  vendor: 'sentry',
+  // both lanes are one service, so one store: the ingest lane writes events the API lane reads, and the doors' accounts
+  // are the ingest lane's too (aws's lanes likewise)
+  service: 'sentry',
+  hosts: [{ host: 'sentry.io' }, { host: 'us.sentry.io' }, { host: 'de.sentry.io' }],
+  body: { json: 'always' },
+  ids: { template: '{uuid}' },
+  time: 'iso',
+  // Django REST framework's error body, which Sentry's API answers with: `{"detail": ...}`
+  error: { detail: '{message}' },
+  readOnly: { status: 403, message: 'This twin was started read-only; writes are refused.' },
+  malformedBody: { status: 400, message: 'Malformed request.' },
+  notFound: { status: 404, message: 'The requested resource does not exist' },
+  gap: { status: 404, message: 'The requested resource does not exist' },
+  // source: https://docs.sentry.io/api/pagination/ "row offset"
+  list: { style: 'envelope', envelope: '{data}', limit: { param: 'per_page', default: 100, max: 100 }, cursor: { param: 'cursor', encoding: 'offset-template', template: '0:{offset}:{reverse}', link: { previous: 'previous', next: 'next', results: 'results', cursor: 'cursor' } } },
+  deleted: {},
+  // the sequences the vendor numbers by (ctx.issue over each, src/semantics/shared.ts next)
+  // source: spec:listOrganizations "List Your Organizations"
+  // source: https://docs.sentry.io/api/pagination/ "Pagination in the API is handled via the Link header standard:"
+  resources: {
+    // source: https://docs.sentry.io/api/projects/create-a-new-project/ "6758470122493650"
+    organization: { idPrefix: '', unique: [{ fields: ['slug'], refusal: { status: 409, message: 'An organization with this slug already exists.' } }], alternateKeys: ['slug'], ids: '{digits:16}', refresh: { list: 'listOrganizations', items: '$body', nextLink: { header: 'link', rel: 'next', query: 'cursor', when: { results: 'true' } } } },
+    // source: spec:listOrganizationProjects "Return a list of projects bound to a organization"
+    // source: https://docs.sentry.io/api/projects/create-a-new-project/ "6758470122493650"
+    project: { idPrefix: '', unique: [{ fields: ['_organization', 'slug'], refusal: { status: 409, message: 'A project with this slug already exists.' } }], alternateKeys: ['slug'], ids: '{digits:16}', parent: { param: 'organization_id_or_slug', field: '_organization', resource: 'organization' }, refresh: { list: 'listOrganizationProjects', items: '$body', nextLink: { header: 'link', rel: 'next', query: 'cursor', when: { results: 'true' } } } },
+    project_key: { idPrefix: '', ids: '{hex:32}', refresh: { none: 'Client keys contain credential secrets. Credential custody keeps their secret-bearing reads out of refresh.' } },
+    // source: spec:listProjectEvents "Return a list of events bound to a project."
+    event: { idPrefix: '', ids: '{hex:32}', key: '{project_id_or_slug}:{event_id}', vendorUnderscored: ['_meta'], ...states.event,
+      parent: { params: ['organization_id_or_slug', 'project_id_or_slug'], value: '{project_id_or_slug}', field: '_project', resource: 'project', where: { _organization: '{organization_id_or_slug}', id: '{project_id_or_slug}' }, keep: { _organization: '{organization_id_or_slug}' } },
+      refresh: { get: 'getProjectEvent', known: true, params: { organization_id_or_slug: '{_organization}', project_id_or_slug: '{projectID}', event_id: '{eventID}' }, idAs: '{projectID}:{eventID}' } },
+    // source: spec:getOrganizationIssue "Return details on an individual issue"
+    issue: { idPrefix: '', ids: '{n}', ...states.issue, parent: { param: 'organization_id_or_slug', field: '_organization', resource: 'organization' }, refresh: { get: 'getOrganizationIssue', known: true, params: { organization_id_or_slug: '{_organization}', issue_id: '{id}' } } },
+    // source: spec:listOrganizationReleases "List an Organization's Releases"
+    release: { idPrefix: '', ids: '{n}', parent: { param: 'organization_id_or_slug', field: '_organization', resource: 'organization' }, refresh: { list: 'listOrganizationReleases', items: '$body', nextLink: { header: 'link', rel: 'next', query: 'cursor', when: { results: 'true' } } } },
+    // source: spec:listOrganizationMonitors "Retrieve Monitors for an Organization"
+    monitor: { ...states.monitor, idPrefix: '', ids: '{uuid}', parent: { param: 'organization_id_or_slug', field: '_organization', resource: 'organization' }, refresh: { list: 'listOrganizationMonitors', items: '$body', nextLink: { header: 'link', rel: 'next', query: 'cursor', when: { results: 'true' } } } },
+    // source: spec:listProjectMonitorCheckins "Retrieve Check-Ins for a Monitor by Project"
+    // source: https://raw.githubusercontent.com/getsentry/sentry/2efdd4760a75a3d395e3534b7f66a7fbb0c3f22e/src/sentry/monitors/serializers.py "str(obj.guid)"
+    check_in: { ...states.check_in, idPrefix: '', ids: '{uuid}', parent: { params: ['organization_id_or_slug', 'project_id_or_slug', 'monitor_id_or_slug'], value: '{monitor_id_or_slug}', field: '_monitor', resource: 'monitor', where: { _organization: '{organization_id_or_slug}', 'project.id': '{project_id_or_slug}', id: '{monitor_id_or_slug}' } }, refresh: { list: 'listProjectMonitorCheckins', items: '$body', nextLink: { header: 'link', rel: 'next', query: 'cursor', when: { results: 'true' } } } },
+    _seq_token: { idPrefix: '', ids: '{n}' }, _seq_event: { idPrefix: '', ids: '{n}' }, _seq_envelope: { idPrefix: '', ids: '{n}' }, _seq_project_key: { idPrefix: '', ids: '{n}' },
+  },
+  unmodeled: [
+    'getOrganization', 'listProjectEvents', 'getProjectRelease', 'getProjectMonitor',
+    // served by no handler: called by no application here (../../journeys/demand.json)
+     'updateOrganization', 'listOrganizationAIConversations',
+    'retrieveOrganizationAIConversation', 'getOrganizationConfigIntegrations', 'listOrganizationDashboards',
+    'createOrganizationDashboard', 'getOrganizationDashboard', 'updateOrganizationDashboard',
+    'deleteOrganizationDashboard', 'listOrganizationDetectors', 'updateOrganizationDetectors',
+    'deleteOrganizationDetectors', 'getOrganizationDetector', 'updateOrganizationDetector',
+    'deleteOrganizationDetector', 'listOrganizationDiscoverSavedQueries', 'createOrganizationDiscoverSavedQuery',
+    'getOrganizationDiscoverSavedQuery', 'updateOrganizationDiscoverSavedQuery',
+    'deleteOrganizationDiscoverSavedQuery', 'listOrganizationEnvironments', 'resolveOrganizationEventId',
+    'listOrganizationEventsTimeseries', 'listOrganizationEvents', 'createOrganizationExternalUser',
+    'updateOrganizationExternalUser', 'deleteOrganizationExternalUser', 'listOrganizationForwarding',
+    'createOrganizationForwarding', 'updateOrganizationForwarding', 'deleteOrganizationForwarding',
+    'listOrganizationIssueViews', 'createOrganizationIssueView', 'listOrganizationIntegrations',
+    'getOrganizationIntegration', 'deleteOrganizationIntegration', 'listOrganizationIntegrationRepositories',
+    'listOrganizationIssues', 'updateOrganizationIssues', 'deleteOrganizationIssues',
+    'updateOrganizationIssue', 'deleteOrganizationIssue', 'getOrganizationIssueAutofixState',
+    'startOrganizationIssueAutofix', 'listOrganizationIssueEvents', 'getOrganizationIssueEvent',
+    'listOrganizationIssueExternalIssues', 'deleteOrganizationIssueExternalIssue', 'listOrganizationIssueHashes',
+    'listOrganizationIssueIntegrations', "Retrieve an Integration's Issue Config for an Issue",
+    'Create an External Issue and Link It to an Issue', 'Link an Existing External Issue to an Issue',
+    'Unlink an External Issue from an Issue', 'getOrganizationIssueTag', 'listOrganizationIssueTagValues',
+    'listOrganizationMembers', 'addOrganizationMember', 'getOrganizationMember', 'updateOrganizationMember',
+    'deleteOrganizationMember', 'addOrganizationMemberTeam', 'updateOrganizationMemberTeam',
+    'deleteOrganizationMemberTeam',  'createOrganizationMonitor', 'getOrganizationMonitor',
+    'updateOrganizationMonitor', 'deleteOrganizationMonitor', 'listOrganizationMonitorCheckins',
+    'listOrganizationNotificationsActions', 'createOrganizationNotificationsAction',
+    'getOrganizationNotificationsAction', 'updateOrganizationNotificationsAction',
+    'deleteOrganizationNotificationsAction', 'getOrganizationPreprodArtifactInstallDetails',
+    'getOrganizationPreprodArtifactSizeAnalysis', 'getOrganizationPreprodArtifactSnapshot',
+    'deleteOrganizationPreprodArtifactSnapshot', 'getOrganizationPreprodArtifactSnapshotImage',
+    'getOrganizationPreprodArtifactSnapshotLatestBase', 'listOrganizationProfilingChunks',
+    'getOrganizationProfilingFlamegraph', 'listOrganizationProjectKeys',
+    'createOrganizationProjectDetector', 'listOrganizationRelayUsage', 'listOrganizationReleaseThresholdStatuses',
+     'createOrganizationRelease', 'getOrganizationRelease', 'deleteOrganizationRelease',
+    "Retrieve Files Changed in a Release's Commits", 'listOrganizationReleaseCommits',
+    'listOrganizationReleaseDeploys', 'createOrganizationReleaseDeploy', 'listOrganizationReleaseFiles',
+    'uploadOrganizationReleaseFile', 'getOrganizationReleaseFile', 'updateOrganizationReleaseFile',
+    'deleteOrganizationReleaseFile', 'getOrganizationReplayCount', 'listOrganizationReplaySelectors',
+    'listOrganizationReplays', 'getOrganizationReplay', 'listOrganizationRepoCommits', 'listOrganizationScimV2Groups',
+    'provisionOrganizationScimV2Group', 'getOrganizationScimV2Group', 'updateOrganizationScimV2Group',
+    'deleteOrganizationScimV2Group', 'listOrganizationScimV2Users', 'provisionOrganizationScimV2User',
+    'getOrganizationScimV2User', 'updateOrganizationScimV2User', 'deleteOrganizationScimV2User',
+    'listOrganizationSentryAppComponents', "List an Organization's Integration Platform Installations",
+    'listOrganizationSentryApps', 'getOrganizationSessions', 'resolveOrganizationShortId', 'Enable Spike Protection',
+    'Disable Spike Protection', 'listOrganizationStatsV2', 'getOrganizationStatsSummary', 'listOrganizationTags',
+    'listOrganizationTeams', 'createOrganizationTeam', 'listOrganizationTraceItemAttributes',
+    'listOrganizationTraceMetrics', 'Retrieve Trace Item Statistics', 'getOrganizationTraceMeta',
+    'getOrganizationTrace', 'listOrganizationUserTeams', 'listOrganizationWorkflows', 'createOrganizationWorkflow',
+    'updateOrganizationWorkflows', 'deleteOrganizationWorkflows', 'getOrganizationWorkflow',
+    'updateOrganizationWorkflow', 'deleteOrganizationWorkflow', 'getProject', 'updateProject', 'deleteProject',
+    'listProjectCodeOwners', 'createProjectCodeOwners', 'retrieveProjectCodeOwners', 'updateProjectCodeOwners',
+    'deleteProjectCodeOwners', "List a Project's Custom Inbound Filters", 'Create a Custom Inbound Filter',
+    'Retrieve a Custom Inbound Filter', 'Update a Custom Inbound Filter', 'Delete a Custom Inbound Filter',
+    'listProjectEnvironments', 'Bulk Update Project Environments', 'getProjectEnvironment',
+    'updateProjectEnvironment', 'listProjectEventAttachments', 'getProjectEventAttachment',
+    'getProjectEventSourceMapDebug', 'listProjectDebugFiles', 'listProjectFilters', 'updateProjectFilter',
+    "List a Project's Service Hooks", 'Register a New Service Hook', 'Retrieve a Service Hook',
+    'Update a Service Hook', 'Remove a Service Hook', "List a Project's Issues", 'Bulk Mutate a List of Issues',
+    'Bulk Remove a List of Issues', 'createProjectKey', 'getProjectKey', 'updateProjectKey',
+    'deleteProjectKey', 'listProjectMembers',  'updateProjectMonitor', 'deleteProjectMonitor',
+     'getProjectOwnership', 'updateProjectOwnership',
+    'getProjectPreprodSizeAnalysisStatusCheckRules', 'createProjectPreprodSizeAnalysisSkippedStatusCheck',
+    'getProjectPreprodSnapshotStatusCheckRules', 'createProjectPreprodSnapshotSkippedStatusCheck',
+    'getProjectInstallableBuildLatest', 'uploadProjectPreprodArtifactSnapshot', 'getProjectProfilingProfile',
+    'listProjectReleases', 'listProjectReleaseCommits', 'listProjectReleaseFiles', 'uploadProjectReleaseFile',
+    'getProjectReleaseFile', 'updateProjectReleaseFile', 'deleteProjectReleaseFile', 'deleteProjectReplay',
+    'listProjectReplayClicks', 'listProjectReplayRecordingSegments', 'getProjectReplayRecordingSegment',
+    'listProjectReplayViewedBy', 'listProjectReplayDeletionJobs', 'createProjectReplayDeletionJob',
+    'getProjectReplayDeletionJob', 'listProjectRepositories', 'linkProjectRepository', 'listProjectStats',
+    'listProjectSymbolSources', 'addProjectSymbolSource', 'updateProjectSymbolSource', 'deleteProjectSymbolSource',
+    "List a Tag's Values", 'listProjectTeams', 'addProjectTeam', 'deleteProjectTeam',
+    "List a Project's User Feedback", 'Submit User Feedback', 'listProjectUsers', 'listSeerModels',
+    'executeSentryAppInstallationExternalIssueAction', 'Create or update an External Issue',
+    'Delete an External Issue', 'getSentryAppInstallationExternalRequestOptions', 'getSentryApp', 'updateSentryApp',
+    'deleteSentryApp', 'getTeam', 'updateTeam', 'deleteTeam', 'createTeamExternalTeam', 'updateTeamExternalTeam',
+    'deleteTeamExternalTeam', 'listTeamMembers', 'listTeamProjects', 'createTeamProject'],
+  // the World's doors (./semantics/doors.ts): what sentry.io's pages do that its API does not
+  doors: [
+    { id: 'appCredentials', method: 'POST', path: '/_twin/app-credentials', note: "the World application's DSN, auth token, organization and project, as the runtime issues them" },
+    { id: 'organizations', method: 'POST', path: '/_twin/organizations', note: "an organization (sentry.io's sign-up)" },
+    { id: 'authTokens', method: 'POST', path: '/_twin/auth-tokens', note: 'an organization CI token or scoped personal auth token, shown once (Settings > Auth Tokens)' },
+  ],
+  // source: https://docs.sentry.io/api/ratelimits/ "Each endpoint has its own maximum number of requests and window size."
+  // The page supplies response headers rather than fixed numerical limits; no global allowance is inferred.
+  accountSetup: [{ operation: 'createOrganizationProject', why: 'The operator creates additional account projects; application calls do not deploy account setup.' }],
+  discovery: { twinOf: "Sentry's web API (sentry.io/api/0): release and source-map operations, account project/key operations, and declared resource read-back", stores: 'organizations, projects and their client keys, auth tokens (by their SHA-256), releases, uploaded chunks and artifact bundles' },
+};

package/api/src/semantics/api.ts

@@ -0,0 +1,247 @@
+import { gunzip, type HandlerContext } from '@volter/world-core';
+import { bearerToken, detail, EVENT, forbidden, grants, keyOf, makeProject, notFound, orgFor, PROJECT, projectFor, projectOf, type Row, wire } from './shared.ts';
+
+// Releases, as sentry-cli makes, finalizes and associates commits with them (`releases new`, `releases finalize`,
+// `releases set-commits`), for one project at its path or for the organization; and the organization's repositories the
+// commits are read against. A release is the organization's, by its version, linked to the projects it was made for.
+
+const RELEASE = 'release';
+const releaseBody = (ctx: HandlerContext): Row => (ctx.body && typeof ctx.body === 'object' ? ctx.body as Row : {});
+const releaseOf = (ctx: HandlerContext, org: Row, version: string): Row | undefined =>
+  ctx.rowsRaw(RELEASE).find((r) => r.deleted !== true && r._organization === org.id && r.version === version);
+
+/** A release as the API answers it (the spec's release schema). */
+function view(ctx: HandlerContext, r: Row): Row {
+  const projects = (r._projects as string[]).map((id) => ctx.row(PROJECT, id)).filter((p): p is Row => !!p);
+  const events = ctx.rowsRaw(EVENT).filter((e) => e.release === r.version && (r._projects as string[]).includes(String(e.project))).map((e) => String(e.dateCreated)).sort();
+  return {
+    id: Number(r.id), version: r.version, shortVersion: String(r.version).length > 12 && /^[0-9a-f]{40}$/.test(String(r.version)) ? String(r.version).slice(0, 12) : r.version,
+    status: 'open', ref: r.ref ?? null, url: r.url ?? null, dateReleased: r.dateReleased ?? null, dateCreated: r.dateCreated, data: {}, newGroups: 0, owner: null,
+    commitCount: Number(r.commitCount ?? 0), lastCommit: r.lastCommit ?? null, deployCount: 0, lastDeploy: null, authors: [], userAgent: r.userAgent ?? null, currentProjectMeta: {},
+    firstEvent: events[0] ?? null, lastEvent: events.at(-1) ?? null, versionInfo: { package: null, version: { raw: r.version }, description: r.version, buildHash: null },
+    projects: projects.map((p) => ({ id: Number(p.id), slug: p.slug, name: p.name, newGroups: 0, platform: p.platform ?? null, platforms: p.platform ? [p.platform] : [], hasHealthData: false })),
+  };
+}
+
+/** A release made for projects of the organization, or the projects linked to one that exists: 201 when anything was
+ *  made or linked, else 208 (the release as it was). */
+async function makeRelease(ctx: HandlerContext, org: Row, projectIds: string[]): Promise<Response> {
+  const b = releaseBody(ctx);
+  const version = typeof b.version === 'string' ? b.version : '';
+  // the release's version: not empty, no "/", not "." or ".." or "latest" (the spec's version field)
+  if (!version || version.includes('/') || ['.', '..', 'latest'].includes(version) || version.length > 200) return Response.json({ version: ['Release with name "' + version + '" is not allowed.'] }, { status: 400 });
+  const held = releaseOf(ctx, org, version);
+  const fields = { ...(typeof b.ref === 'string' ? { ref: b.ref } : {}), ...(typeof b.url === 'string' ? { url: b.url } : {}), ...(typeof b.dateReleased === 'string' ? { dateReleased: b.dateReleased } : {}) };
+  if (held) {
+    const linked = [...new Set([...(held._projects as string[]), ...projectIds])];
+    if (linked.length === (held._projects as string[]).length) return Response.json(view(ctx, held), { status: 208 });
+    const kept = await ctx.write(RELEASE, String(held.id), { _projects: linked, ...fields }, 'release.update');
+    const answer = view(ctx, ctx.row(RELEASE, String(kept.id))!);
+    await ctx.write(RELEASE, String(kept.id), answer, 'release.update');
+    return Response.json(answer, { status: 201 });
+  }
+  const id = ctx.mint(RELEASE);
+  const made = await ctx.write(RELEASE, id, { id: Number(id), version, _organization: org.id, _projects: projectIds, projects: projectIds, dateCreated: ctx.occurredAt, userAgent: ctx.call.request.headers.get('user-agent'), ...fields }, 'release.create');
+  const answer = view(ctx, ctx.row(RELEASE, id)!);
+  await ctx.write(RELEASE, id, answer, 'release.update');
+  return Response.json(answer, { status: 201 });
+}
+
+/** A release's changes: when it was released, its ref and URL, and the commits named by `refs` (each a repository the
+ *  organization has). */
+async function changeRelease(ctx: HandlerContext, org: Row, r: Row): Promise<Response> {
+  const b = releaseBody(ctx);
+  const refs = Array.isArray(b.refs) ? b.refs as Row[] : [];
+  const repos = ctx.rowsRaw('repository').filter((x) => x.deleted !== true && x.organization === org.id).map((x) => String(x.name));
+  const unknown = refs.map((x) => String(x.repository ?? '')).filter((n) => !repos.includes(n));
+  if (unknown.length) return Response.json({ refs: [`Invalid repository names: ${unknown.join(',')}`] }, { status: 400 });
+  const kept = await ctx.write(RELEASE, String(r.id), {
+    ...(typeof b.dateReleased === 'string' || b.dateReleased === null ? { dateReleased: b.dateReleased } : {}),
+    ...(typeof b.ref === 'string' ? { ref: b.ref } : {}), ...(typeof b.url === 'string' ? { url: b.url } : {}), ...(refs.length ? { _refs: refs } : {}), ...(Array.isArray(b.commits) ? { _commits: b.commits, commitCount: b.commits.length, lastCommit: (b.commits as Row[]).at(-1) ?? null } : {}),
+  }, 'release.update');
+  const answer = view(ctx, ctx.row(RELEASE, String(kept.id))!);
+  await ctx.write(RELEASE, String(kept.id), answer, 'release.update');
+  return Response.json(answer);
+}
+
+// source: https://raw.githubusercontent.com/getsentry/sentry/2efdd4760a75a3d395e3534b7f66a7fbb0c3f22e/src/sentry/releases/endpoints/project_releases.py "Create a new release and/or associate a project with a release."
+export async function createProjectRelease(ctx: HandlerContext): Promise<Response> {
+  const at = projectFor(ctx, 'project:releases');
+  if (at instanceof Response) return at;
+  return makeRelease(ctx, at.org, [String(at.project.id)]);
+}
+
+
+
+// source: https://raw.githubusercontent.com/getsentry/sentry/2efdd4760a75a3d395e3534b7f66a7fbb0c3f22e/src/sentry/releases/endpoints/project_release_details.py "def put("
+export async function updateProjectRelease(ctx: HandlerContext): Promise<Response> {
+  const at = projectFor(ctx, 'project:releases');
+  if (at instanceof Response) return at;
+  const r = releaseOf(ctx, at.org, String(ctx.call.params.version ?? ''));
+  return r && (r._projects as string[]).includes(String(at.project.id)) ? changeRelease(ctx, at.org, r) : detail(404, 'The requested resource does not exist');
+}
+
+// source: spec:updateOrganizationRelease "Update a release. This can change some metadata associated with"
+export async function updateOrganizationRelease(ctx: HandlerContext): Promise<Response> {
+  const org = orgFor(ctx, 'project:releases');
+  if (org instanceof Response) return org;
+  const r = releaseOf(ctx, org, String(ctx.call.params.version ?? ''));
+  return r ? changeRelease(ctx, org, r) : detail(404, 'The requested resource does not exist');
+}
+
+// source: spec:listOrganizationRepos "Return a list of version control repositories for a given organization."
+export async function listOrganizationRepos(ctx: HandlerContext): Promise<Response> {
+  const org = orgFor(ctx, 'org:read');
+  if (org instanceof Response) return org;
+  // Where the evidence stops: a repository comes from a source-code integration (GitHub's app, installed on
+  // Settings > Integrations), which the World does not run yet; an organization has none
+  return Response.json(ctx.rowsRaw('repository').filter((x) => x.deleted !== true && x.organization === org.id).map((x) => wire(ctx, x)));
+}
+
+// Source maps as sentry-cli uploads them (`sourcemaps upload`, and the bundler plugins through it): the server's chunk
+// options, chunks of the artifact bundle posted by their SHA-1, and the bundle assembled from them for its projects and
+// release (getsentry/sentry: api/endpoints/chunk.py and organization_artifactbundle_assemble.py).
+
+const CHUNK = '_chunk';
+const BUNDLE = '_artifact_bundle';
+const error = (message: string): Response => Response.json({ error: message }, { status: 400 });
+// source: https://raw.githubusercontent.com/getsentry/sentry/2efdd4760a75a3d395e3534b7f66a7fbb0c3f22e/src/sentry/api/endpoints/chunk.py "MAX_CHUNKS_PER_REQUEST = 64"
+const MAX_CHUNKS_PER_REQUEST = 64;
+// source: https://raw.githubusercontent.com/getsentry/sentry/2efdd4760a75a3d395e3534b7f66a7fbb0c3f22e/src/sentry/api/endpoints/chunk.py "MAX_REQUEST_SIZE = 32 * 1024 * 1024"
+const MAX_REQUEST_SIZE = 32 * 1024 * 1024;
+// Where the documentation stops: the chunk size is the server's setting (SENTRY_CHUNK_UPLOAD_BLOB_SIZE), a power of two
+// for sentry-cli 2.39 and older; the twin's is 8 MiB. The largest file is the file store's limit, 2 GiB here.
+const CHUNK_SIZE = 8 * 1024 * 1024;
+const MAX_FILE_SIZE = 2 * 1024 * 1024 * 1024;
+// source: https://raw.githubusercontent.com/getsentry/sentry/2efdd4760a75a3d395e3534b7f66a7fbb0c3f22e/src/sentry/api/endpoints/chunk.py "# The `assemble` endpoint will check for missing chunks"
+const ACCEPT = ['debug_files', 'release_files', 'pdbs', 'sources', 'bcsymbolmaps', 'il2cpp', 'portablepdbs', 'artifact_bundles', 'artifact_bundles_v2', 'proguard', 'preprod_artifacts', 'dartsymbolmap'];
+const SHA1 = /^[0-9a-f]{40}$/;
+
+// source: https://raw.githubusercontent.com/getsentry/sentry/2efdd4760a75a3d395e3534b7f66a7fbb0c3f22e/src/sentry/api/endpoints/chunk.py "Return chunk upload parameters"
+export async function getChunkUploadOptions(ctx: HandlerContext): Promise<Response> {
+  const org = orgFor(ctx, 'project:releases');
+  if (org instanceof Response) return org;
+  // sentry-cli 2.30 and later are sent an absolute URL at the region's host (chunk.py `requires_region_url`); the
+  // compression offered is gzip alone, as the server may answer a narrower list than its own (an organization with
+  // compression turned off is answered none)
+  return Response.json({
+    url: `https://us.sentry.io/api/0/organizations/${String(org.slug)}/chunk-upload/`, chunkSize: CHUNK_SIZE, chunksPerRequest: MAX_CHUNKS_PER_REQUEST,
+    maxFileSize: MAX_FILE_SIZE, maxRequestSize: MAX_REQUEST_SIZE, concurrency: 8, hashAlgorithm: 'sha1', compression: ['gzip'], accept: ACCEPT,
+  });
+}
+
+// source: https://raw.githubusercontent.com/getsentry/sentry/2efdd4760a75a3d395e3534b7f66a7fbb0c3f22e/src/sentry/api/endpoints/chunk.py "files_gzip_legacy = request.FILES.getlist("
+export async function uploadChunks(ctx: HandlerContext): Promise<Response> {
+  const org = orgFor(ctx, 'project:releases');
+  if (org instanceof Response) return org;
+  const encoding = (ctx.call.request.headers.get('content-encoding') ?? '').toLowerCase();
+  const parts = (await ctx.parts()).filter((p) => p.name === 'file' || p.name === 'file_gzip');
+  if (encoding && parts.some((p) => p.name === 'file_gzip')) return error('Cannot combine Content-Encoding with file_gzip field');
+  if (encoding && encoding !== 'gzip') return error('Unsupported Content-Encoding');
+  if (parts.length > MAX_CHUNKS_PER_REQUEST) return error('Too many chunks');
+  let total = 0;
+  for (const part of parts) {
+    let data: Uint8Array;
+    try { data = part.name === 'file_gzip' || encoding === 'gzip' ? await gunzip(part.body) : part.body; } catch { return error('Invalid gzip payload'); }
+    if (data.length > CHUNK_SIZE) return error('Chunk size too large');
+    total += data.length;
+    if (total > MAX_REQUEST_SIZE) return error('Request too large');
+    const checksum = ctx.crypto.digest('sha1', data, 'hex');
+    // Where the documentation stops: a part is named by its checksum; one whose content has another is refused
+    if (String(part.filename ?? '') !== checksum) return error(`Checksum mismatch: ${String(part.filename)}`);
+    await ctx.blobs.put(`chunk/${checksum}`, data);
+    await ctx.record(CHUNK, { organization: org.id, size: data.length }, `${String(org.id)}:${checksum}`);
+  }
+  return new Response(null, { status: 200 });
+}
+
+// source: https://raw.githubusercontent.com/getsentry/sentry/2efdd4760a75a3d395e3534b7f66a7fbb0c3f22e/src/sentry/api/endpoints/organization_artifactbundle_assemble.py "AssembleTask.ARTIFACT_BUNDLE, organization.id, checksum, ChunkFileState.CREATED"
+export async function assembleArtifactBundle(ctx: HandlerContext): Promise<Response> {
+  const org = orgFor(ctx, 'project:releases');
+  if (org instanceof Response) return org;
+  const b = (ctx.body && typeof ctx.body === 'object' ? ctx.body : {}) as Row;
+  if (typeof b.checksum !== 'string' || !SHA1.test(b.checksum)) return error('The checksum field is required and must be a 40-character hexadecimal string.');
+  if (!Array.isArray(b.chunks) || b.chunks.some((c) => typeof c !== 'string' || !SHA1.test(c))) return error('The chunks field is required and must be provided as an array of 40-character hexadecimal strings.');
+  if (!Array.isArray(b.projects)) return error('The projects field is required and must be provided as an array of strings.');
+  if (b.version !== undefined && (typeof b.version !== 'string' || !b.version || b.version.includes('/'))) return error('The version field cannot be empty and cannot contain any "/" characters.');
+  if (b.projects.length === 0) return error('You need to specify at least one project');
+  const projects = (b.projects as unknown[]).map((p) => projectOf(ctx, org, String(p)));
+  if (projects.some((p) => !p)) return error('One or more projects are invalid');
+  const held = ctx.row(BUNDLE, `${String(org.id)}:${b.checksum}`);
+  if (held && held.deleted !== true) return Response.json({ state: held.state, detail: held.detail ?? null, missingChunks: [] });
+  const chunks = b.chunks as string[];
+  const missing = chunks.filter((c) => !ctx.row(CHUNK, `${String(org.id)}:${c}`));
+  if (missing.length) return Response.json({ state: 'not_found', missingChunks: missing });
+  // the bundle is assembled from its chunks in order; its checksum must be theirs together
+  const pieces = await Promise.all(chunks.map((c) => ctx.blobs.get(`chunk/${c}`)));
+  const whole = new Uint8Array(pieces.reduce((n, p) => n + (p?.length ?? 0), 0));
+  let at = 0;
+  for (const p of pieces) { if (p) { whole.set(p, at); at += p.length; } }
+  const ok = ctx.crypto.digest('sha1', whole, 'hex') === b.checksum;
+  if (ok) await ctx.blobs.put(`bundle/${String(org.id)}/${b.checksum}`, whole);
+  // the assembly is scheduled on the first request that names every chunk (answered `created`); later requests read
+  // its outcome: `ok`, or `error` with why
+  await ctx.record(BUNDLE, {
+    organization: org.id, checksum: b.checksum, projects: projects.map((p) => p!.id), release: b.version ?? null, dist: b.dist ?? null, size: whole.length,
+    state: ok ? 'ok' : 'error', detail: ok ? null : 'Reported checksum mismatch', dateCreated: ctx.occurredAt,
+  }, `${String(org.id)}:${b.checksum}`);
+  return Response.json({ state: 'created', missingChunks: [] });
+}
+
+// source: spec:createOrganizationProject "Create a new project for an organization."
+export async function createOrganizationProject(ctx: HandlerContext): Promise<Response> {
+  const org = orgFor(ctx, 'project:write');
+  if (org instanceof Response) return org;
+  const b = (ctx.body ?? {}) as Row;
+  if (typeof b.name !== 'string' || !b.name.trim()) return Response.json({ name: ['This field is required.'] }, { status: 400 });
+  const slug = typeof b.slug === 'string' ? b.slug : b.name.toLowerCase().replace(/[^a-z0-9_-]+/g, '-');
+  // source: spec:/paths/~1api~10~1organizations~1{organization_id_or_slug}~1projects~1/post/requestBody "Uniquely identifies a project and is used for the interface."
+  if (!/^(?![0-9]+$)[a-z0-9_-]+$/.test(slug)) return Response.json({ slug: ['Enter a valid slug.'] }, { status: 400 });
+  if (projectOf(ctx, org, slug)) return Response.json({ slug: ['A project with this slug already exists.'] }, { status: 409 });
+  const project = await makeProject(ctx, org, slug, typeof b.platform === 'string' ? b.platform : null);
+  if (project instanceof Response) return project;
+  await ctx.write(PROJECT, String(project.id), { name: b.name }, 'project.update');
+  return Response.json(wire(ctx, ctx.row(PROJECT, String(project.id))!), { status: 201 });
+}
+
+// source: spec:listProjectKeys "Return a list of client keys bound to a project."
+export async function listProjectKeys(ctx: HandlerContext): Promise<Response> {
+  const at = projectFor(ctx, 'project:read');
+  if (at instanceof Response) return at;
+  const key = keyOf(ctx, at.project);
+  return Response.json(key ? [wire(ctx, key)] : []);
+}
+
+// source: spec:listOrganizations "List Your Organizations"
+export async function listOrganizations(ctx: HandlerContext): Promise<Response> {
+  const token = bearerToken(ctx)!;
+  if (!grants(token, 'org:read')) return forbidden();
+  return ctx.list('organization', ctx.rowsRaw('organization').filter((o) => o.deleted !== true && o.id === token.organization).map((o) => wire(ctx, o)));
+}
+
+// source: spec:listOrganizationReleases "List an Organization's Releases"
+export async function listOrganizationReleases(ctx: HandlerContext): Promise<Response> {
+  const org = orgFor(ctx, 'project:releases');
+  if (org instanceof Response) return org;
+  return ctx.list('release', ctx.rowsRaw('release').filter((r) => r.deleted !== true && r._organization === org.id).map((r) => wire(ctx, r)));
+}
+
+
+// source: https://raw.githubusercontent.com/getsentry/sentry/2efdd4760a75a3d395e3534b7f66a7fbb0c3f22e/src/sentry/issues/endpoints/organization_release_previous_commits.py "raise ResourceDoesNotExist"
+export async function getPreviousReleaseWithCommits(ctx: HandlerContext): Promise<Response> {
+  const org = orgFor(ctx, 'project:releases');
+  if (org instanceof Response) return org;
+  const current = releaseOf(ctx, org, String(ctx.call.params.version));
+  if (!current) return notFound();
+  // source: https://raw.githubusercontent.com/getsentry/sentry/2efdd4760a75a3d395e3534b7f66a7fbb0c3f22e/src/sentry/issues/endpoints/organization_release_previous_commits.py "start_date = release.date_released or release.date_added"
+  const start = String(current.dateReleased ?? current.dateCreated);
+  // source: https://raw.githubusercontent.com/getsentry/sentry/2efdd4760a75a3d395e3534b7f66a7fbb0c3f22e/src/sentry/issues/endpoints/organization_release_previous_commits.py "projects__id__in=project_ids"
+  // source: https://raw.githubusercontent.com/getsentry/sentry/2efdd4760a75a3d395e3534b7f66a7fbb0c3f22e/src/sentry/issues/endpoints/organization_release_previous_commits.py "last_commit_id__isnull=False"
+  // source: https://raw.githubusercontent.com/getsentry/sentry/2efdd4760a75a3d395e3534b7f66a7fbb0c3f22e/src/sentry/issues/endpoints/organization_release_previous_commits.py "COALESCE(date_released, date_added) <= %s"
+  const candidates = ctx.rowsRaw('release').filter((r) => r.deleted !== true && r._organization === org.id && r.lastCommit != null
+    && (r._projects as string[]).some((id) => (current._projects as string[]).includes(id)) && String(r.dateReleased ?? r.dateCreated) <= start);
+  // source: https://raw.githubusercontent.com/getsentry/sentry/2efdd4760a75a3d395e3534b7f66a7fbb0c3f22e/src/sentry/issues/endpoints/organization_release_previous_commits.py "order_by"
+  const previous = candidates.sort((a, b) => String(b.dateReleased ?? b.dateCreated).localeCompare(String(a.dateReleased ?? a.dateCreated)))[0];
+  // source: https://raw.githubusercontent.com/getsentry/sentry/2efdd4760a75a3d395e3534b7f66a7fbb0c3f22e/src/sentry/issues/endpoints/organization_release_previous_commits.py "return Response({})"
+  return Response.json(previous ? wire(ctx, previous) : {});
+}

package/api/src/semantics/around.ts

@@ -0,0 +1,36 @@
+// Scoped API authentication and the vendor's organization/project/monitor slug resolution.
+import type { HandlerContext } from '@volter/world-core';
+import { bearerToken, detail, forbidden, grants, orgFor, projectFor, MONITOR } from './shared.ts';
+
+export async function around(ctx: HandlerContext, next: (request?: Request) => Promise<Response>): Promise<Response> {
+  const request = ctx.call.request;
+  if (!new URL(request.url).pathname.startsWith('/api/0/')) return next();
+  if (!request.headers.get('authorization')) return detail(401, 'Authentication credentials were not provided.');
+  const token = bearerToken(ctx);
+  if (!token) return detail(401, 'Invalid token');
+  // Core refresh reads use the spec's scopes, with Sentry's inherited write/admin grants.
+  if (!ctx.call.operation.resource || !['list', 'retrieve'].includes(ctx.call.operation.class)) return next();
+  // source: https://docs.sentry.io/api/permissions/ "Scopes"
+  const scope = (ctx.call.operation.scopes ?? []).find((s) => grants(token, s));
+  if (!scope) return forbidden();
+  // source: spec:listOrganizationProjects "The ID or slug of the organization"
+  const org = orgFor(ctx, scope);
+  if (org instanceof Response) return org;
+  const params: Record<string, string> = { ...ctx.call.params, organization_id_or_slug: String(org.id) };
+  // source: spec:getProjectEvent "The ID or slug of the project"
+  if (ctx.call.params.project_id_or_slug !== undefined) {
+    const at = projectFor(ctx, scope);
+    if (at instanceof Response) return at;
+    params.project_id_or_slug = String(at.project.id);
+    // source: spec:listProjectMonitorCheckins "The ID or slug of the monitor"
+    if (ctx.call.params.monitor_id_or_slug !== undefined) {
+      const ref = ctx.call.params.monitor_id_or_slug;
+      const monitor = ctx.rowsRaw(MONITOR).find((m) => m.deleted !== true && m._project === at.project.id && (m.id === ref || m.slug === ref));
+      if (!monitor) return detail(404, 'The requested resource does not exist');
+      params.monitor_id_or_slug = String(monitor.id);
+    }
+  }
+  const url = new URL(request.url);
+  url.pathname = ctx.call.operation.path.replace(/\{([^}]+)\}/g, (_, name: string) => encodeURIComponent(params[name] ?? ''));
+  return next(new Request(url, request));
+}

package/api/src/semantics/doors.ts

@@ -0,0 +1,76 @@
+// The World's doors (architecture, "Doors, screens and the gap"): what sentry.io's pages do that its API does not, each
+// declared in the manifest's `doors` and answered by the export its id names.
+//
+//   POST /_twin/app-credentials                     the application's DSN, auth token, organization and project (the
+//                                                   descriptor's credentialDoor), the same at every boot
+//   POST /_twin/organizations { slug, name? }       an organization (sentry.io's sign-up)
+//   POST /_twin/auth-tokens { organization, name, kind?, scopes? }
+//                                                   an organization auth token (Settings > Auth Tokens), or with kind
+//                                                   personal a personal token with its scopes, shown once
+import type { HandlerContext } from '@volter/world-core';
+import { CLIENT_KEY, dsnOf, keyOf, makeClientKey, makeOrg, makeOrgToken, makePersonalToken, makeProject, orgBySlug, ORG, PROJECT, readToken, TOKEN } from './shared.ts';
+
+const bad = (error: string): Response => Response.json({ error }, { status: 400 });
+const bodyOf = (ctx: HandlerContext): Record<string, unknown> => (ctx.body && typeof ctx.body === 'object' ? ctx.body : {}) as Record<string, unknown>;
+const SLUG = /^[a-z0-9][a-z0-9_-]{0,49}$/;
+
+/** The deployment's project client key and an independently issued auth token in its organization. */
+export async function appCredentials(ctx: HandlerContext): Promise<Response> {
+  try {
+    const b = bodyOf(ctx);
+    const organizationId = await ctx.account();
+    const org = await ctx.tenant(ORG, async (organization) => {
+      const label = typeof b.organization === 'string' ? b.organization : organization.id === 'default' ? 'world' : organization.id;
+      const rule = { max: 50, lower: true, allowed: /[a-z0-9_-]/, first: /[a-z0-9]/ };
+      const name = typeof b.name === 'string' ? b.name : organization.label;
+      let made = await makeOrg(ctx, ctx.vendorName(label, rule, { identity: organization.id }), name, organization.members[0]!);
+      if (made instanceof Response) made = await makeOrg(ctx, ctx.vendorName(label, rule, { suffixed: true, identity: organization.id }), name, organization.members[0]!);
+      if (made instanceof Response) throw await duplicate(made, organization.id);
+      return String(made.id);
+    });
+    const project = await ctx.deploymentObject(`project:${String(org.id)}`, PROJECT, async (deployment) => {
+      const label = typeof b.project === 'string' ? b.project : deployment || 'app';
+      const identity = deployment === '' ? organizationId : `${organizationId}/${deployment}`;
+      const rule = { max: Number.MAX_SAFE_INTEGER, lower: true, allowed: /[a-z0-9_-]/, first: /[a-z_-]/ };
+      const platform = typeof b.platform === 'string' ? b.platform : 'javascript';
+      let made = await makeProject(ctx, org, ctx.vendorName(label, rule, { identity }), platform);
+      if (made instanceof Response) made = await makeProject(ctx, org, ctx.vendorName(label, rule, { suffixed: true, identity }), platform);
+      if (made instanceof Response) throw await duplicate(made, identity);
+      return String(made.id);
+    });
+    const key = await ctx.accountKey('client-key', CLIENT_KEY, {
+      make: async () => String((keyOf(ctx, project) ?? await makeClientKey(ctx, org, project)).id),
+      read: async (row) => row._project === project.id && row.isActive !== false && typeof row.public === 'string' ? row.public : undefined,
+    });
+    const token = await ctx.accountKey('auth-token', TOKEN, {
+      make: async () => ctx.crypto.sha256(await makePersonalToken(ctx, org, ctx.deployment() || 'world-app', ['org:read', 'project:read', 'project:write', 'project:releases', 'event:read', 'alerts:read'])),
+      read: (row) => readToken(ctx, org, row),
+    });
+    return Response.json({ dsn: dsnOf(org, project, { public: key.secret }), auth_token: token.secret, authorization: `Bearer ${token.secret}`, url: 'https://sentry.io', org: org.slug, org_id: org.id, project: project.slug }, { status: 201 });
+  } catch (error) {
+    if (error instanceof Response) return error;
+    throw error;
+  }
+}
+
+async function duplicate(response: Response, identity: string): Promise<Response> {
+  const body = await response.json() as { slug: string[] };
+  return Response.json({ slug: body.slug.map((message) => `${message} (${identity})`) }, { status: response.status });
+}
+
+export async function organizations(ctx: HandlerContext): Promise<Response> {
+  const b = bodyOf(ctx);
+  if (typeof b.slug !== 'string' || !SLUG.test(b.slug)) return bad('a slug (lowercase letters, digits, - and _) is required');
+  const org = await makeOrg(ctx, b.slug, typeof b.name === 'string' ? b.name : b.slug, (await ctx.organization()).members[0]!);
+  if (org instanceof Response) return org;
+  return Response.json({ id: org.id, slug: org.slug }, { status: 201 });
+}
+
+export async function authTokens(ctx: HandlerContext): Promise<Response> {
+  const b = bodyOf(ctx);
+  const org = typeof b.organization === 'string' ? orgBySlug(ctx, b.organization) : undefined;
+  if (!org) return bad('organization must name an organization the World holds');
+  if (typeof b.name !== 'string' || !b.name) return bad('a name is required');
+  const scopes = Array.isArray(b.scopes) ? b.scopes.map(String) : ['org:read', 'project:read', 'event:read'];
+  return b.kind === 'personal' ? Response.json({ token: await makePersonalToken(ctx, org, String(b.name), scopes) }, { status: 201 }) : Response.json({ token: await makeOrgToken(ctx, org, String(b.name)) }, { status: 201 });
+}

package/api/src/semantics/index.ts

@@ -0,0 +1,19 @@
+// GENERATED by scripts/create-pack.ts --index: the handler map, by operationId, from the families' files (each
+// handler named as its operation). Do not edit; add a handler to its family's file and generate again.
+import type { Handler } from '@volter/world-core';
+import * as api from './api.ts';
+
+export const apiSemantics: Record<string, Handler> = {
+  assembleArtifactBundle: api.assembleArtifactBundle,
+  createOrganizationProject: api.createOrganizationProject,
+  createProjectRelease: api.createProjectRelease,
+  getChunkUploadOptions: api.getChunkUploadOptions,
+  getPreviousReleaseWithCommits: api.getPreviousReleaseWithCommits,
+  listOrganizationReleases: api.listOrganizationReleases,
+  listOrganizationRepos: api.listOrganizationRepos,
+  listOrganizations: api.listOrganizations,
+  listProjectKeys: api.listProjectKeys,
+  updateOrganizationRelease: api.updateOrganizationRelease,
+  updateProjectRelease: api.updateProjectRelease,
+  uploadChunks: api.uploadChunks,
+};

package/api/src/semantics/shared.ts

@@ -0,0 +1,31 @@
+// What every family of Sentry's API shares: who is calling (an auth token the World issued), the organization a request
+// names and whether the token may act on it, and the API's answers (Django REST framework's `{"detail": ...}`).
+import type { HandlerContext } from '@volter/world-core';
+import { bearerToken, grants, orgBySlug, projectOf, type Row } from '../../../src/semantics/shared.ts';
+
+export * from '../../../src/semantics/shared.ts';
+
+
+export const detail = (status: number, message: string): Response => Response.json({ detail: message }, { status });
+// Where the documentation stops: the spec names these answers' statuses (401, 403, 404) without their bodies; the
+// messages are Django REST framework's, which Sentry's API answers with
+export const notFound = (): Response => detail(404, 'The requested resource does not exist');
+export const forbidden = (): Response => detail(403, 'You do not have permission to perform this action.');
+
+/** The organization a request's path names, if the request's token is the organization's and its scopes grant the
+ *  operation's (the spec's security scopes for it); else the API's refusal. */
+export function orgFor(ctx: HandlerContext, scope: string): Row | Response {
+  const token = bearerToken(ctx);
+  if (!token) return detail(401, 'Invalid token');
+  const org = orgBySlug(ctx, String(ctx.call.params.organization_id_or_slug ?? ''));
+  if (!org) return notFound();
+  return token.organization === org.id && grants(token, scope) ? org : forbidden();
+}
+
+/** The organization and project a request's path names, or the API's refusal. */
+export function projectFor(ctx: HandlerContext, scope: string): { org: Row; project: Row } | Response {
+  const org = orgFor(ctx, scope);
+  if (org instanceof Response) return org;
+  const project = projectOf(ctx, org, String(ctx.call.params.project_id_or_slug ?? ''));
+  return project ? { org, project } : notFound();
+}

package/api/src/semantics/states.ts

@@ -0,0 +1,17 @@
+// A check-in records progress and its final outcome; classification fields are not lifecycle machines.
+export const states = {
+  // source: spec:listProjectEvents "Return a list of events bound to a project."
+  // Event type classifies the received payload; the reads do not move it between types.
+  event: { notState: ['type'] },
+  // source: spec:getOrganizationIssue "Return details on an individual issue"
+  // The issue read exposes classifications and account-relative flags; no served operation changes them.
+  issue: { notState: ['level', 'type', 'status', 'substatus', 'priority', 'isPublic', 'hasSeen', 'isBookmarked', 'isSubscribed', 'isUnhandled'] },
+  // source: spec:listOrganizationMonitors "Retrieve Monitors for an Organization"
+  // Monitor enablement is account configuration; received check-ins do not move that setting.
+  monitor: { notState: ['status'] },
+  check_in: { state: { status: { initial: 'in_progress', transitions: [
+    // source: https://raw.githubusercontent.com/getsentry/sentry-docs/3ec4e139711af82b38a3c2c17261f5f5cdb66dfc/develop-docs/sdk/foundations/envelopes/envelope-items.mdx "check-in payload encoded as JSON"
+    { actor: 'vendor' as const, from: ['in_progress'], to: 'ok', source: 'https://docs.sentry.io/platforms/javascript/guides/node/crons/ "ok"' },
+    { actor: 'vendor' as const, from: ['in_progress'], to: 'error', source: 'https://docs.sentry.io/platforms/javascript/guides/node/crons/ "error"' },
+  ] } } },
+};