@volter/twin-planetscale 0.1.0

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

@@ -0,0 +1 @@
+{"generatedBy":"scripts/derive-pack.ts","resources":{"Database":{"retrieve":"/v1/organizations/{organization}/databases/{database}","create":{"path":"/v1/organizations/{organization}/databases","encoding":"json","body":[{"name":"cluster_size","type":"string","required":true},{"name":"kind","type":"string","required":false},{"name":"major_version","type":"string","required":false},{"name":"name","type":"string","required":true},{"name":"region","type":"string","required":false},{"name":"replicas","type":"integer","required":false},{"name":"storage","type":"object","required":false}]},"actions":[],"states":{"state":["pending","ready"]},"embeds":{}},"Backup":{"retrieve":"/v1/organizations/{organization}/databases/{database}/branches/{branch}/backups/{id}","create":{"path":"/v1/organizations/{organization}/databases/{database}/branches/{branch}/backups","encoding":"json","body":[{"name":"emergency","type":"boolean","required":false},{"name":"name","type":"string","required":false},{"name":"retention_unit","type":"string","required":false},{"name":"retention_value","type":"integer","required":false}]},"actions":[],"states":{"state":["pending","running","success"]},"embeds":{}},"DatabaseBranchPassword":{"retrieve":"/v1/organizations/{organization}/databases/{database}/branches/{branch}/passwords/{id}","actions":[],"states":{},"embeds":{}},"ServiceToken":{"create":{"path":"/v1/organizations/{organization}/service-tokens","encoding":"json","body":[{"name":"name","type":"string","required":false},{"name":"ttl","type":"integer","required":false}]},"actions":[],"states":{},"embeds":{}}}}

package/dist/api/src/index.ts

@@ -0,0 +1,19 @@
+// The management API lane of the planetscale pack (`api.planetscale.com/v1`), as a plain fetch: the whole pack's fetch
+// (the psdb data plane, the management API and app.planetscale.com's pages), whose owners are the operations this lane
+// serves. Its life walks through all of them: a customer of the management API makes its tokens on the settings page,
+// approves deploy requests on their page, and runs its migrations and queries through psdb on the branches the API makes
+// (journeys/customer-life.outline.md).
+import type { DerivedFetch } from '@volter/world-core';
+import { createPlanetscaleTwinFetch } from '../../src/planetscale-server.ts';
+import { createPlanetscaleApiLaneFetch } from './fetch.ts';
+
+export { manifest } from './manifest.ts';
+export { createPlanetscaleApiLaneFetch } from './fetch.ts';
+// how a journey reads a psdb answer: the pack's own view (../../src/index.ts)
+export { answerViews } from '../../src/index.ts';
+
+export function createPlanetscaleApiTwinFetch(options: { root?: string; readOnly?: boolean } = {}): DerivedFetch {
+  const lane = createPlanetscaleApiLaneFetch(options);
+  const pack = createPlanetscaleTwinFetch({ ...(options.root !== undefined ? { root: options.root } : {}), ...(options.readOnly !== undefined ? { readOnly: options.readOnly } : {}) });
+  return Object.assign((request: Request) => pack(request), { owners: () => lane.owners() });
+}

package/dist/api/src/manifest.d.ts

@@ -0,0 +1,2 @@
+import type { DerivedManifest } from '@volter/world-core';
+export declare const manifest: DerivedManifest;

package/dist/api/src/manifest.js

@@ -0,0 +1,113 @@
+/** A database's `state`. A new database is `pending` and not `ready`; PlanetScale provisions it, and a caller polls:
+ *  "After creation, poll `get_database` until `ready` is `true` before creating branches or backups"
+ *  (https://planetscale.com/docs/api/reference/create_database). The twin's database turns ready one minute after it was
+ *  created, on the World clock (semantics/time.ts): how long provisioning takes is the twin's decision, the reference
+ *  gives none. Not made by the twin: importing, import_ready, sleep_in_progress, sleeping, awakening. */
+const databaseState = {
+    initial: 'pending',
+    transitions: [
+        { actor: 'time', from: ['pending'], to: 'ready', source: 'spec:/definitions/Database/properties/ready "If the database is ready to be used"' },
+    ],
+};
+/** A backup's `state`. A new backup is `pending`; it starts `running` and ends `success`, and a caller polls: "Use
+ *  `get_backup` to poll the current state of a backup" (https://planetscale.com/docs/api/reference/create_backup). The
+ *  twin's backup starts 30 seconds after it was asked for and completes two minutes after (semantics/time.ts), its size
+ *  the branch's stored rows at completion: the timing is the twin's decision, the reference gives none. Not made by the
+ *  twin: failed, canceled, ignored. */
+const backupState = {
+    initial: 'pending',
+    transitions: [
+        { actor: 'time', from: ['pending'], to: 'running', source: 'spec:/definitions/Backup/properties/state "The current state of the backup"' },
+        { actor: 'time', from: ['running'], to: 'success', source: 'spec:/definitions/Backup/properties/state "The current state of the backup"' },
+    ],
+};
+/** A branch's `state`. A new branch is `pending` and not `ready`; PlanetScale's CI example waits for it before using it
+ *  (https://planetscale.com/docs/vitess/integrations/github-actions: "we create it and pass the `--wait` flag"). The twin's
+ *  branch turns ready one minute after it was made, on the World clock (semantics/time.ts): the delay is the twin's
+ *  decision. Not made by the twin: sleep_in_progress, sleeping, awakening. */
+const branchState = {
+    initial: 'pending',
+    transitions: [
+        { actor: 'time', from: ['pending'], to: 'ready', source: 'spec:/definitions/DatabaseBranch/properties/state "The current state of the branch"' },
+    ],
+};
+const DR_PAGE = 'https://planetscale.com/docs/vitess/schema-changes/deploy-requests';
+/** A deploy request's `state`: open until it is closed, by `close_deploy_request`, by a revert ("The deploy request will
+ *  be closed", the deploy-requests page), or when its deployment completes (the twin's reading: the request stays open
+ *  through its revert window). */
+const deployRequestState = {
+    initial: 'open',
+    transitions: [
+        { operation: 'close_deploy_request', from: ['open'], to: 'closed', source: 'spec:/paths/~1organizations~1{organization}~1databases~1{database}~1deploy-requests~1{number}/patch "The deploy request will be updated to this state"' },
+        { operation: 'complete_revert', from: ['open'], to: 'closed', source: `${DR_PAGE} "The deploy request will be closed, but the branch will remain"` },
+        { actor: 'time', from: ['open'], to: 'closed', source: `${DR_PAGE} "After the 30 minute period is up, the deployment becomes permanent"` },
+    ],
+};
+/** A deploy request's `deployment_state` (semantics/deploy-requests.ts): checked, queued, deployed into its revert window,
+ *  then permanent or reverted. The durations are the twin's. Not made by the twin: submitting, pending_cutover,
+ *  in_progress_vschema, in_progress_cancel, in_progress_cutover, complete_cancel, complete_error, in_progress_revert,
+ *  in_progress_revert_vschema, complete_revert_error, cancelled, error. */
+const deploymentState = {
+    initial: 'pending',
+    transitions: [
+        { actor: 'time', from: ['pending'], to: 'ready', source: `${DR_PAGE} "PlanetScale will check if the request is deployable"` },
+        { actor: 'time', from: ['pending'], to: 'no_changes', source: 'spec:/definitions/DatabaseDeployRequest/properties/deployment_state "The deployment state of the deploy request"' },
+        { operation: 'queue_deploy_request', from: ['ready'], to: 'queued', source: `${DR_PAGE} "The deployment will begin immediately, or join the serial deploy queue if other deployments are already pending"` },
+        { actor: 'time', from: ['queued'], to: 'in_progress', source: `${DR_PAGE} "only one deploy runs at a time, and later requests wait until earlier ones finish"` },
+        { actor: 'time', from: ['in_progress'], to: 'complete_pending_revert', source: `${DR_PAGE} "After you deploy, you have 30 minutes to \"undo\" it"` },
+        { actor: 'time', from: ['complete_pending_revert'], to: 'complete', source: `${DR_PAGE} "After the 30 minute period is up, the deployment becomes permanent"` },
+        { actor: 'time', from: ['in_progress'], to: 'complete', source: `${DR_PAGE} "these schema changes must be auto-applied and cannot be reverted"` },
+        { operation: 'complete_revert', from: ['complete_pending_revert'], to: 'complete_revert', source: `${DR_PAGE} "You can revert a deployment for up to 30 minutes after the deploying"` },
+    ],
+};
+export const manifest = {
+    vendor: 'planetscale',
+    service: 'planetscale',
+    body: { json: 'always' },
+    // PlanetScale's ids are opaque strings; the handlers mint each from the instant, the name and the count
+    // (semantics/shared.ts, `mintId`), prefixed per resource, so a World mints the same ids every run. The core mints none.
+    ids: { template: '{prefix}{n}' },
+    time: 'iso',
+    // the management API's error body (the pack's backups have answered it since they were served)
+    error: { code: '{code}', message: '{message}' },
+    readOnly: { status: 403, code: 'forbidden', message: 'The twin is read-only' },
+    malformedBody: { status: 422, code: 'unprocessable_entity', message: 'The request body is not valid JSON' },
+    notFound: { status: 404, code: 'not_found', message: 'Not Found' },
+    // the spec's Paginated* envelope; the lists are handlers (semantics/shared.ts, `page`)
+    list: {
+        style: 'envelope',
+        envelope: { type: 'list', data: '{data}' },
+        limit: { param: 'per_page', default: 25, max: 100 },
+        page: { param: 'page', link: false },
+    },
+    deleted: {},
+    // operations of the declared resources the lane does not serve: the gap
+    unmodeled: ['update_branch', 'update_backup_policy', 'delete_backup_policy', 'update_backup', 'update_password', 'get_service_token', 'get_oauth_token', 'delete_oauth_token'],
+    // the page where a service token is made and granted its accesses (no API operation grants an access)
+    screens: [{
+            id: 'sign-in', kind: 'flow', host: 'app.planetscale.com', path: '/sign-in',
+            demand: 'every app.planetscale.com page a person reaches: each asks who is signed in', status: 'done',
+            controls: ['Email', 'Password', 'Sign in'], source: 'https://planetscale.com/docs/api/reference/service-tokens',
+        }, {
+            id: 'service-tokens', kind: 'flow', host: 'app.planetscale.com', path: '/{organization}/settings/service-tokens',
+            demand: 'the first service token of an organization, and the accesses of every token, are made here',
+            status: 'done', controls: ['New service token', 'Name', 'Create service token', 'Service token', 'Database', 'Access', 'Save permissions', 'Delete service token'],
+            source: 'https://planetscale.com/docs/api/reference/service-tokens',
+        }, {
+            id: 'deploy-request', kind: 'flow', host: 'app.planetscale.com', path: '/{organization}/{database}/deploy-requests/{number}',
+            demand: 'a deploy request is approved by an administrator other than its creator here', status: 'done',
+            controls: ['Summary', 'Schema changes', 'Approve changes'],
+            source: 'https://planetscale.com/docs/vitess/schema-changes/deploy-requests',
+        }],
+    resources: {
+        Database: { storedAs: '_database', idPrefix: 'db', notFound: 'Not Found', notState: ['kind'], state: { state: databaseState } },
+        DatabaseBranch: { storedAs: '_branch', idPrefix: 'br', notFound: 'Not Found', notState: ['kind'], state: { state: branchState } },
+        DatabaseDeployRequest: { storedAs: '_deploy_request', idPrefix: 'dr', notFound: 'Not Found', state: { state: deployRequestState, deployment_state: deploymentState } },
+        BackupPolicy: { storedAs: '_backup_policy', idPrefix: 'bp', notFound: 'Not Found' },
+        Backup: { storedAs: '_backup', idPrefix: 'bk', notFound: 'Not Found', state: { state: backupState } },
+        // a password's role is set when it is made: "once a password is created, its role assignment cannot be changed"
+        // (planetscale.com/docs/vitess/connecting/password-roles)
+        DatabaseBranchPassword: { storedAs: '_password', idPrefix: 'pw', notFound: 'Not Found', notState: ['role'] },
+        ServiceToken: { storedAs: '_service_token', idPrefix: 'tk', notFound: 'Not Found' },
+    },
+};

package/dist/api/src/manifest.ts

@@ -0,0 +1,136 @@
+// PlanetScale's management API manifest (the pack's `api` lane; docs/contributing/architecture.md, "Other wires: lanes"):
+// the vendor facts its published Swagger document (../spec/openapi.json.gz) does not carry, and the resources whose state
+// the lane moves. The surface is generated (./generated/surface.gen.json, by `bun scripts/derive-pack.ts planetscale/api`).
+//
+// The lane serves the slice an application and the pack's customer lives reach: databases (create, read, delete), their
+// branches (create from a parent or a backup, read, list, delete; semantics/branches.ts), a branch's passwords (create,
+// list, read, delete), a branch's backups (create, list, read, delete) and service tokens (create, list). Every other
+// operation of the spec is the gap. The psdb data plane (the pack root) reads the passwords
+// this lane issues, so both write the one kernel service `planetscale`; the lane's records are control-plane records the
+// pack never pushes to a real branch, so each is stored under a `_` type, beside psdb's `_session`.
+//
+// NO `auth`: PlanetScale reads a service token as `Authorization: <SERVICE_TOKEN_ID>:<SERVICE_TOKEN>`, with no scheme
+// (planetscale.com/docs/api/reference, "Service tokens"), which the kernel's scheme-prefixed gate cannot state. The lane's
+// token gate (token-gate.ts) sits in front of the dispatch instead, and checks each operation's service token
+// accesses as the spec's own "Authorization" section for it lists them.
+import type { DerivedManifest, StateField } from '@volter/world-core';
+
+/** A database's `state`. A new database is `pending` and not `ready`; PlanetScale provisions it, and a caller polls:
+ *  "After creation, poll `get_database` until `ready` is `true` before creating branches or backups"
+ *  (https://planetscale.com/docs/api/reference/create_database). The twin's database turns ready one minute after it was
+ *  created, on the World clock (semantics/time.ts): how long provisioning takes is the twin's decision, the reference
+ *  gives none. Not made by the twin: importing, import_ready, sleep_in_progress, sleeping, awakening. */
+const databaseState: StateField = {
+  initial: 'pending',
+  transitions: [
+    { actor: 'time', from: ['pending'], to: 'ready', source: 'spec:/definitions/Database/properties/ready "If the database is ready to be used"' },
+  ],
+};
+
+/** A backup's `state`. A new backup is `pending`; it starts `running` and ends `success`, and a caller polls: "Use
+ *  `get_backup` to poll the current state of a backup" (https://planetscale.com/docs/api/reference/create_backup). The
+ *  twin's backup starts 30 seconds after it was asked for and completes two minutes after (semantics/time.ts), its size
+ *  the branch's stored rows at completion: the timing is the twin's decision, the reference gives none. Not made by the
+ *  twin: failed, canceled, ignored. */
+const backupState: StateField = {
+  initial: 'pending',
+  transitions: [
+    { actor: 'time', from: ['pending'], to: 'running', source: 'spec:/definitions/Backup/properties/state "The current state of the backup"' },
+    { actor: 'time', from: ['running'], to: 'success', source: 'spec:/definitions/Backup/properties/state "The current state of the backup"' },
+  ],
+};
+
+/** A branch's `state`. A new branch is `pending` and not `ready`; PlanetScale's CI example waits for it before using it
+ *  (https://planetscale.com/docs/vitess/integrations/github-actions: "we create it and pass the `--wait` flag"). The twin's
+ *  branch turns ready one minute after it was made, on the World clock (semantics/time.ts): the delay is the twin's
+ *  decision. Not made by the twin: sleep_in_progress, sleeping, awakening. */
+const branchState: StateField = {
+  initial: 'pending',
+  transitions: [
+    { actor: 'time', from: ['pending'], to: 'ready', source: 'spec:/definitions/DatabaseBranch/properties/state "The current state of the branch"' },
+  ],
+};
+
+const DR_PAGE = 'https://planetscale.com/docs/vitess/schema-changes/deploy-requests';
+
+/** A deploy request's `state`: open until it is closed, by `close_deploy_request`, by a revert ("The deploy request will
+ *  be closed", the deploy-requests page), or when its deployment completes (the twin's reading: the request stays open
+ *  through its revert window). */
+const deployRequestState: StateField = {
+  initial: 'open',
+  transitions: [
+    { operation: 'close_deploy_request', from: ['open'], to: 'closed', source: 'spec:/paths/~1organizations~1{organization}~1databases~1{database}~1deploy-requests~1{number}/patch "The deploy request will be updated to this state"' },
+    { operation: 'complete_revert', from: ['open'], to: 'closed', source: `${DR_PAGE} "The deploy request will be closed, but the branch will remain"` },
+    { actor: 'time', from: ['open'], to: 'closed', source: `${DR_PAGE} "After the 30 minute period is up, the deployment becomes permanent"` },
+  ],
+};
+
+/** A deploy request's `deployment_state` (semantics/deploy-requests.ts): checked, queued, deployed into its revert window,
+ *  then permanent or reverted. The durations are the twin's. Not made by the twin: submitting, pending_cutover,
+ *  in_progress_vschema, in_progress_cancel, in_progress_cutover, complete_cancel, complete_error, in_progress_revert,
+ *  in_progress_revert_vschema, complete_revert_error, cancelled, error. */
+const deploymentState: StateField = {
+  initial: 'pending',
+  transitions: [
+    { actor: 'time', from: ['pending'], to: 'ready', source: `${DR_PAGE} "PlanetScale will check if the request is deployable"` },
+    { actor: 'time', from: ['pending'], to: 'no_changes', source: 'spec:/definitions/DatabaseDeployRequest/properties/deployment_state "The deployment state of the deploy request"' },
+    { operation: 'queue_deploy_request', from: ['ready'], to: 'queued', source: `${DR_PAGE} "The deployment will begin immediately, or join the serial deploy queue if other deployments are already pending"` },
+    { actor: 'time', from: ['queued'], to: 'in_progress', source: `${DR_PAGE} "only one deploy runs at a time, and later requests wait until earlier ones finish"` },
+    { actor: 'time', from: ['in_progress'], to: 'complete_pending_revert', source: `${DR_PAGE} "After you deploy, you have 30 minutes to \"undo\" it"` },
+    { actor: 'time', from: ['complete_pending_revert'], to: 'complete', source: `${DR_PAGE} "After the 30 minute period is up, the deployment becomes permanent"` },
+    { actor: 'time', from: ['in_progress'], to: 'complete', source: `${DR_PAGE} "these schema changes must be auto-applied and cannot be reverted"` },
+    { operation: 'complete_revert', from: ['complete_pending_revert'], to: 'complete_revert', source: `${DR_PAGE} "You can revert a deployment for up to 30 minutes after the deploying"` },
+  ],
+};
+
+export const manifest: DerivedManifest = {
+  vendor: 'planetscale',
+  service: 'planetscale',
+  body: { json: 'always' },
+  // PlanetScale's ids are opaque strings; the handlers mint each from the instant, the name and the count
+  // (semantics/shared.ts, `mintId`), prefixed per resource, so a World mints the same ids every run. The core mints none.
+  ids: { template: '{prefix}{n}' },
+  time: 'iso',
+  // the management API's error body (the pack's backups have answered it since they were served)
+  error: { code: '{code}', message: '{message}' },
+  readOnly: { status: 403, code: 'forbidden', message: 'The twin is read-only' },
+  malformedBody: { status: 422, code: 'unprocessable_entity', message: 'The request body is not valid JSON' },
+  notFound: { status: 404, code: 'not_found', message: 'Not Found' },
+  // the spec's Paginated* envelope; the lists are handlers (semantics/shared.ts, `page`)
+  list: {
+    style: 'envelope',
+    envelope: { type: 'list', data: '{data}' },
+    limit: { param: 'per_page', default: 25, max: 100 },
+    page: { param: 'page', link: false },
+  },
+  deleted: {},
+  // operations of the declared resources the lane does not serve: the gap
+  unmodeled: ['update_branch', 'update_backup_policy', 'delete_backup_policy', 'update_backup', 'update_password', 'get_service_token', 'get_oauth_token', 'delete_oauth_token'],
+  // the page where a service token is made and granted its accesses (no API operation grants an access)
+  screens: [{
+    id: 'sign-in', kind: 'flow', host: 'app.planetscale.com', path: '/sign-in',
+    demand: 'every app.planetscale.com page a person reaches: each asks who is signed in', status: 'done',
+    controls: ['Email', 'Password', 'Sign in'], source: 'https://planetscale.com/docs/api/reference/service-tokens',
+  }, {
+    id: 'service-tokens', kind: 'flow', host: 'app.planetscale.com', path: '/{organization}/settings/service-tokens',
+    demand: 'the first service token of an organization, and the accesses of every token, are made here',
+    status: 'done', controls: ['New service token', 'Name', 'Create service token', 'Service token', 'Database', 'Access', 'Save permissions', 'Delete service token'],
+    source: 'https://planetscale.com/docs/api/reference/service-tokens',
+  }, {
+    id: 'deploy-request', kind: 'flow', host: 'app.planetscale.com', path: '/{organization}/{database}/deploy-requests/{number}',
+    demand: 'a deploy request is approved by an administrator other than its creator here', status: 'done',
+    controls: ['Summary', 'Schema changes', 'Approve changes'],
+    source: 'https://planetscale.com/docs/vitess/schema-changes/deploy-requests',
+  }],
+  resources: {
+    Database: { storedAs: '_database', idPrefix: 'db', notFound: 'Not Found', notState: ['kind'], state: { state: databaseState } },
+    DatabaseBranch: { storedAs: '_branch', idPrefix: 'br', notFound: 'Not Found', notState: ['kind'], state: { state: branchState } },
+    DatabaseDeployRequest: { storedAs: '_deploy_request', idPrefix: 'dr', notFound: 'Not Found', state: { state: deployRequestState, deployment_state: deploymentState } },
+    BackupPolicy: { storedAs: '_backup_policy', idPrefix: 'bp', notFound: 'Not Found' },
+    Backup: { storedAs: '_backup', idPrefix: 'bk', notFound: 'Not Found', state: { state: backupState } },
+    // a password's role is set when it is made: "once a password is created, its role assignment cannot be changed"
+    // (planetscale.com/docs/vitess/connecting/password-roles)
+    DatabaseBranchPassword: { storedAs: '_password', idPrefix: 'pw', notFound: 'Not Found', notState: ['role'] },
+    ServiceToken: { storedAs: '_service_token', idPrefix: 'tk', notFound: 'Not Found' },
+  },
+};

package/dist/api/src/screens/deploy-request.d.ts

@@ -0,0 +1,7 @@
+import type { SemanticsContext } from '@volter/world-core';
+type Row = Record<string, unknown>;
+/** The spec's actor object for a person on a page. */
+export declare const personActor: (email: string) => Row;
+/** The deploy request page, or undefined for any other request. `contextFor` gives the lane's semantics context. */
+export declare function deployRequestPage(request: Request, contextFor: (request: Request) => Promise<SemanticsContext>): Promise<Response | undefined>;
+export {};

package/dist/api/src/screens/deploy-request.js

@@ -0,0 +1,106 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// PLANETSCALE'S DEPLOY REQUEST PAGE — a flow (docs/contributing/architecture.md, "Screens"): the page at
+// app.planetscale.com/{organization}/{database}/deploy-requests/{number}, where a teammate reads a deploy request's schema
+// changes and approves it. https://planetscale.com/docs/vitess/schema-changes/deploy-requests, "Review a deploy request":
+// "Under "Summary", you'll see if the request is deployable. To review the schema changes, click the "Schema changes"
+// tab"; "If you have required deploy requests to be approved before deployment, other users in your Organization will
+// see the option to "Approve changes" or "Leave a comment" on the "Schema changes" tab." Built from @volter/world-ui's
+// settings layout (Portal) under PlanetScale's skin; nothing of PlanetScale's page is copied. Its controls are the ones
+// the lane's life needs: the Summary, the Schema changes, and "Approve changes".
+//
+// The person on the page is who signed in at /sign-in (screens/session.tsx); only a member of the organization reaches
+// it (another answers PlanetScale's 404). Where the documentation stops and the twin decides: approving takes an
+// administrator (the setting "Require administrator approval for deploy requests" names an administrator's approval),
+// the page posts the approval to `…/deploy-requests/{number}/review` and comes back to the page, and the approval is the
+// same review the API's review_deploy_request records (semantics/deploy-requests.ts), with the person as reviewer.
+import { flowPage, Portal, PORTAL_CSS } from '@volter/world-ui';
+import { deploymentOf, recordReview, reviewsOf } from "../semantics/deploy-requests.js";
+import { createdById, personActorOf } from "../semantics/audit.js";
+import { signedIn, toSignIn } from "./session.js";
+const PAGE = /^\/([^/]+)\/([^/]+)\/deploy-requests\/(\d+)(?:\/(review))?$/;
+const SKIN = `
+body { background: #ffffff; color: #111111; }
+.portal-side { background: #fafafa; border-right: 1px solid #e5e5e5; }
+.portal-section h2 { border-color: #e5e5e5; color: #525252; }
+.portal-notice { background: #f0f7ff; border: 1px solid #b6d4fe; }
+.portal-button { background: #ffffff; border: 1px solid #d4d4d4; border-radius: 6px; padding: 6px 12px; }
+.portal-primary { background: #1d4ed8; border-color: #1d4ed8; color: #ffffff; }
+`;
+/** The spec's actor object for a person on a page. */
+export const personActor = (email) => ({ id: createdById(email), display_name: email, avatar_url: 'https://app.planetscale.com/gravatar-fallback.png' });
+function page(ctx, org, database, dr, canApprove, notice, status = 200) {
+    const deployment = deploymentOf(dr);
+    const ops = deployment.deploy_operations;
+    const reviews = reviewsOf(ctx, dr);
+    const action = `/${org}/${database}/deploy-requests/${String(dr.number)}/review`;
+    const approvable = canApprove && dr.state === 'open' && dr.approved !== true;
+    return flowPage({
+        title: `Deploy request #${String(dr.number)} · ${database} · PlanetScale`,
+        css: [PORTAL_CSS, SKIN],
+        status,
+        body: (_jsx(Portal, { merchant: `${org} / ${database}`, back: { href: `/${org}/${database}`, label: 'Back to database' }, ...(notice ? { notice } : {}), sections: [
+                {
+                    heading: 'Summary',
+                    items: [{
+                            title: `#${String(dr.number)}: ${String(dr.branch)} → ${String(dr.into_branch)}`,
+                            detail: deployment.deployable === true ? 'Deployable' : 'Not deployable',
+                            note: `${String(dr.state)} · ${String(dr.deployment_state)}${dr.approved === true ? ' · Approved' : ''}${dr.notes ? ` · ${String(dr.notes)}` : ''}`,
+                            ...(approvable ? { actions: [{ label: 'Approve changes', action, fields: { state: 'approved' }, tone: 'primary', method: 'post' }] } : {}),
+                        }],
+                },
+                {
+                    heading: 'Schema changes',
+                    empty: 'No schema changes.',
+                    items: ops.map((o) => ({ title: String(o.table_name), detail: String(o.ddl_statement), ...(o.can_drop_data === true ? { badge: 'Drops data' } : {}) })),
+                },
+                {
+                    heading: 'Reviews',
+                    empty: 'No reviews yet.',
+                    items: reviews.map((r) => ({ title: String(r.actor.display_name), detail: String(r.state), note: String(r.created_at) })),
+                },
+            ] })),
+    });
+}
+/** The page again with the refusal an approval drew (a creator approving their own request, or a token's maker its
+ *  request), in the page's notice. */
+async function approvalRefused(out, again) {
+    return again((await out.json()).message ?? 'The approval was refused.', out.status);
+}
+async function formOf(request) {
+    return Object.fromEntries(new URLSearchParams(await request.text()));
+}
+/** The deploy request page, or undefined for any other request. `contextFor` gives the lane's semantics context. */
+export async function deployRequestPage(request, contextFor) {
+    const url = new URL(request.url);
+    const m = PAGE.exec(url.pathname.replace(/\/+$/, ''));
+    if (!m)
+        return undefined;
+    const [, org, database, number, review] = m.map((x) => (x === undefined ? x : decodeURIComponent(x)));
+    const ctx = await contextFor(new Request(request.url));
+    const person = signedIn(ctx, request);
+    if (!person)
+        return toSignIn(request);
+    const notFound = new Response('Not Found', { status: 404, headers: { 'content-type': 'text/plain' } });
+    if (!person.organizations.includes(org))
+        return notFound;
+    const db = ctx.rowsRaw('Database').find((d) => d.name === database && !d._deleted_at);
+    const find = (c) => c.rowsRaw('DatabaseDeployRequest').find((d) => d._database === database && String(d.number) === number);
+    const dr = db ? find(ctx) : undefined;
+    if (!db || !dr)
+        return notFound;
+    const admin = person.role === 'admin';
+    if (!review && request.method === 'GET')
+        return page(ctx, org, database, dr, admin);
+    if (!review || request.method !== 'POST')
+        return undefined;
+    const form = await formOf(request);
+    if (form.state !== 'approved')
+        return page(ctx, org, database, dr, admin, 'Choose Approve changes.', 422);
+    if (!admin)
+        return page(ctx, org, database, dr, admin, 'Only an organization administrator can approve a deploy request.', 403);
+    const out = await recordReview(ctx, db, dr, `person:${person.email}`, personActor(person.email), 'approved', '', personActorOf(person.email));
+    const after = await contextFor(new Request(request.url));
+    if (out instanceof Response)
+        return approvalRefused(out, (text, status) => page(after, org, database, find(after), admin, text, status));
+    return page(after, org, database, find(after), admin, `You approved deploy request #${number}.`);
+}

package/dist/api/src/screens/deploy-request.tsx

@@ -0,0 +1,111 @@
+// PLANETSCALE'S DEPLOY REQUEST PAGE — a flow (docs/contributing/architecture.md, "Screens"): the page at
+// app.planetscale.com/{organization}/{database}/deploy-requests/{number}, where a teammate reads a deploy request's schema
+// changes and approves it. https://planetscale.com/docs/vitess/schema-changes/deploy-requests, "Review a deploy request":
+// "Under "Summary", you'll see if the request is deployable. To review the schema changes, click the "Schema changes"
+// tab"; "If you have required deploy requests to be approved before deployment, other users in your Organization will
+// see the option to "Approve changes" or "Leave a comment" on the "Schema changes" tab." Built from @volter/world-ui's
+// settings layout (Portal) under PlanetScale's skin; nothing of PlanetScale's page is copied. Its controls are the ones
+// the lane's life needs: the Summary, the Schema changes, and "Approve changes".
+//
+// The person on the page is who signed in at /sign-in (screens/session.tsx); only a member of the organization reaches
+// it (another answers PlanetScale's 404). Where the documentation stops and the twin decides: approving takes an
+// administrator (the setting "Require administrator approval for deploy requests" names an administrator's approval),
+// the page posts the approval to `…/deploy-requests/{number}/review` and comes back to the page, and the approval is the
+// same review the API's review_deploy_request records (semantics/deploy-requests.ts), with the person as reviewer.
+import { flowPage, Portal, PORTAL_CSS } from '@volter/world-ui';
+import type { SemanticsContext } from '@volter/world-core';
+import { deploymentOf, recordReview, reviewsOf } from '../semantics/deploy-requests.ts';
+import { createdById, personActorOf } from '../semantics/audit.ts';
+import { signedIn, toSignIn } from './session.tsx';
+
+type Row = Record<string, unknown>;
+const PAGE = /^\/([^/]+)\/([^/]+)\/deploy-requests\/(\d+)(?:\/(review))?$/;
+const SKIN = `
+body { background: #ffffff; color: #111111; }
+.portal-side { background: #fafafa; border-right: 1px solid #e5e5e5; }
+.portal-section h2 { border-color: #e5e5e5; color: #525252; }
+.portal-notice { background: #f0f7ff; border: 1px solid #b6d4fe; }
+.portal-button { background: #ffffff; border: 1px solid #d4d4d4; border-radius: 6px; padding: 6px 12px; }
+.portal-primary { background: #1d4ed8; border-color: #1d4ed8; color: #ffffff; }
+`;
+
+/** The spec's actor object for a person on a page. */
+export const personActor = (email: string): Row => ({ id: createdById(email), display_name: email, avatar_url: 'https://app.planetscale.com/gravatar-fallback.png' });
+
+function page(ctx: SemanticsContext, org: string, database: string, dr: Row, canApprove: boolean, notice?: string, status = 200): Response {
+  const deployment = deploymentOf(dr);
+  const ops = deployment.deploy_operations as Row[];
+  const reviews = reviewsOf(ctx, dr);
+  const action = `/${org}/${database}/deploy-requests/${String(dr.number)}/review`;
+  const approvable = canApprove && dr.state === 'open' && dr.approved !== true;
+  return flowPage({
+    title: `Deploy request #${String(dr.number)} · ${database} · PlanetScale`,
+    css: [PORTAL_CSS, SKIN],
+    status,
+    body: (
+      <Portal
+        merchant={`${org} / ${database}`}
+        back={{ href: `/${org}/${database}`, label: 'Back to database' }}
+        {...(notice ? { notice } : {})}
+        sections={[
+          {
+            heading: 'Summary',
+            items: [{
+              title: `#${String(dr.number)}: ${String(dr.branch)} → ${String(dr.into_branch)}`,
+              detail: deployment.deployable === true ? 'Deployable' : 'Not deployable',
+              note: `${String(dr.state)} · ${String(dr.deployment_state)}${dr.approved === true ? ' · Approved' : ''}${dr.notes ? ` · ${String(dr.notes)}` : ''}`,
+              ...(approvable ? { actions: [{ label: 'Approve changes', action, fields: { state: 'approved' }, tone: 'primary' as const, method: 'post' as const }] } : {}),
+            }],
+          },
+          {
+            heading: 'Schema changes',
+            empty: 'No schema changes.',
+            items: ops.map((o) => ({ title: String(o.table_name), detail: String(o.ddl_statement), ...(o.can_drop_data === true ? { badge: 'Drops data' } : {}) })),
+          },
+          {
+            heading: 'Reviews',
+            empty: 'No reviews yet.',
+            items: reviews.map((r) => ({ title: String((r.actor as Row).display_name), detail: String(r.state), note: String(r.created_at) })),
+          },
+        ]}
+      />
+    ),
+  });
+}
+
+/** The page again with the refusal an approval drew (a creator approving their own request, or a token's maker its
+ *  request), in the page's notice. */
+async function approvalRefused(out: Response, again: (text: string, status: number) => Response): Promise<Response> {
+  return again(((await out.json()) as { message?: string }).message ?? 'The approval was refused.', out.status);
+}
+
+async function formOf(request: Request): Promise<Record<string, string>> {
+  return Object.fromEntries(new URLSearchParams(await request.text()));
+}
+
+/** The deploy request page, or undefined for any other request. `contextFor` gives the lane's semantics context. */
+export async function deployRequestPage(request: Request, contextFor: (request: Request) => Promise<SemanticsContext>): Promise<Response | undefined> {
+  const url = new URL(request.url);
+  const m = PAGE.exec(url.pathname.replace(/\/+$/, ''));
+  if (!m) return undefined;
+  const [, org, database, number, review] = m.map((x) => (x === undefined ? x : decodeURIComponent(x))) as [string, string, string, string, string | undefined];
+  const ctx = await contextFor(new Request(request.url));
+  const person = signedIn(ctx, request);
+  if (!person) return toSignIn(request);
+  const notFound = new Response('Not Found', { status: 404, headers: { 'content-type': 'text/plain' } });
+  if (!person.organizations.includes(org)) return notFound;
+  const db = ctx.rowsRaw('Database').find((d) => d.name === database && !d._deleted_at);
+  const find = (c: SemanticsContext): Row | undefined => c.rowsRaw('DatabaseDeployRequest').find((d) => d._database === database && String(d.number) === number);
+  const dr = db ? find(ctx) : undefined;
+  if (!db || !dr) return notFound;
+  const admin = person.role === 'admin';
+  if (!review && request.method === 'GET') return page(ctx, org, database, dr, admin);
+  if (!review || request.method !== 'POST') return undefined;
+  const form = await formOf(request);
+  if (form.state !== 'approved') return page(ctx, org, database, dr, admin, 'Choose Approve changes.', 422);
+  if (!admin) return page(ctx, org, database, dr, admin, 'Only an organization administrator can approve a deploy request.', 403);
+  const out = await recordReview(ctx, db, dr, `person:${person.email}`, personActor(person.email), 'approved', '', personActorOf(person.email));
+  const after = await contextFor(new Request(request.url));
+  if (out instanceof Response) return approvalRefused(out, (text, status) => page(after, org, database, find(after)!, admin, text, status));
+  return page(after, org, database, find(after)!, admin, `You approved deploy request #${number}.`);
+}

package/dist/api/src/screens/service-tokens.d.ts

@@ -0,0 +1,3 @@
+import type { SemanticsContext } from '@volter/world-core';
+/** The service tokens page, or undefined for any other request. `contextFor` gives the lane's semantics context. */
+export declare function serviceTokensPage(request: Request, contextFor: (request: Request) => Promise<SemanticsContext>): Promise<Response | undefined>;