@volter/twin-upstash 0.1.0

package/api/src/semantics/backups.ts

@@ -0,0 +1,90 @@
+// A Redis database's backups (https://upstash.com/docs/redis/features/backup; the spec's create-backup, list-backup,
+// delete-backup, restore-backup and enable-dailybackup). A backup holds the database's keys as they stood when it was
+// made (the pack root's store, `keyspaceImage`), and a restore empties its target and writes them back: "All existing data
+// in the target database will be deleted before the restore operation begins". "You can restore your database from any
+// backup in your account or team": a backup of any database the caller reaches restores into any other it reaches.
+//
+// Where the pages stop and the twin decides: a backup is `pending` for two minutes and then `completed` (semantics/time.ts);
+// a manual backup is kept until it is deleted; a daily backup is made at 00:00 UTC each day after daily backup is enabled,
+// named `daily-backup-<date>`, and kept one day after it completes (the console offers "1 or 3 days", the API's
+// enable-dailybackup takes none, and the production checklist gives "Backup retention up to 3 days with Prod Pack",
+// https://upstash.com/docs/redis/help/production-checklist); a backup's size is the bytes of the keys it holds; an unknown
+// backup, or one not yet completed, answers 400 to a restore and 404 to a delete.
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { keyspaceImage, restoreKeyspace, type KeyImage } from '../../../src/upstash-store.ts';
+import { backingUp, badRequest, body, live, ownFields, uuidOf, type Row } from './shared.ts';
+
+export const COMPLETE_AFTER_MS = 2 * 60_000;
+export const DAILY_KEPT_MS = 86_400_000;
+
+const scope = (ctx: SemanticsContext, database: string) => ({ ...(ctx.root !== undefined ? { root: ctx.root } : {}), occurredAt: ctx.occurredAt, database });
+
+/** Make a backup of a database as it stands at `ctx.occurredAt`, `pending` until it completes. */
+export async function makeBackup(ctx: SemanticsContext, db: Row, name: string, daily: boolean): Promise<Row> {
+  const database = String(db.database_id);
+  const image = keyspaceImage(scope(ctx, database));
+  const id = uuidOf(`backup:${database}:${ctx.occurredAt}:${name}:${ctx.rowsRaw('Backup', { withDeleted: true }).length + 1}`);
+  const fields: Row = {
+    database_id: database, customer_id: db.customer_id, name, backup_id: id, creation_time: Math.floor(Date.parse(ctx.occurredAt) / 1000),
+    state: 'pending', backup_size: Buffer.byteLength(JSON.stringify(image)), daily_backup: String(daily), hourly_backup: 'false', internal_backup_tag: '',
+    _image: image, _owner: db._owner, _created_at: ctx.occurredAt,
+  };
+  await ctx.write('Backup', id, fields, daily ? 'backup.daily' : 'backup.create');
+  return fields;
+}
+
+/** The live backups of a database, oldest first. */
+const backupsOf = (ctx: SemanticsContext, database: string): Row[] =>
+  ctx.rowsRaw('Backup').filter((k) => k.database_id === database && !k._deleted_at).sort((a, b) => Number(a.creation_time) - Number(b.creation_time));
+
+/** createBackup {name}: a backup of the database now, answered "OK" (its 200 schema). */
+const createBackup: Semantics = async (ctx) => {
+  const id = String(ctx.call.params.id);
+  const db = live(ctx, id);
+  if (!db) return ctx.notFound('Database', id, 'id');
+  const name = typeof body(ctx).name === 'string' ? String(body(ctx).name).trim() : '';
+  if (!name) return badRequest(ctx, 'name is required');
+  const busy = backingUp(ctx, id);
+  if (busy) return busy;
+  await makeBackup(ctx, db, name, false);
+  return ctx.reply('OK', 200);
+};
+
+/** listBackup: the database's backups, as the Backup schema answers each. */
+const listBackup: Semantics = async (ctx) => {
+  const id = String(ctx.call.params.id);
+  if (!live(ctx, id)) return ctx.notFound('Database', id, 'id');
+  return ctx.reply(backupsOf(ctx, id).map((k) => ownFields(ctx.own(k))));
+};
+
+/** deleteBackup: the backup goes, answered "OK". */
+const deleteBackup: Semantics = async (ctx) => {
+  const id = String(ctx.call.params.id);
+  if (!live(ctx, id)) return ctx.notFound('Database', id, 'id');
+  const backup = backupsOf(ctx, id).find((k) => k.backup_id === ctx.call.params.backup_id);
+  if (!backup) return ctx.notFound('Backup', String(ctx.call.params.backup_id), 'backup_id');
+  await ctx.write('Backup', String(backup.backup_id), { ...ctx.own(backup), _deleted_at: ctx.occurredAt }, 'backup.delete');
+  return ctx.reply('OK', 200);
+};
+
+/** restoreBackup {backup_id}: the database's keys are replaced by the backup's, answered "OK". */
+const restoreBackup: Semantics = async (ctx) => {
+  const id = String(ctx.call.params.id);
+  if (!live(ctx, id)) return ctx.notFound('Database', id, 'id');
+  const wanted = String(body(ctx).backup_id ?? '');
+  const backup = ctx.rowsRaw('Backup').find((k) => k.backup_id === wanted && !k._deleted_at && k.state === 'completed' && live(ctx, String(k.database_id)));
+  if (!backup) return badRequest(ctx, `backup ${wanted} is not a completed backup of a database in your account`);
+  await restoreKeyspace(backup._image as KeyImage[], scope(ctx, id));
+  return ctx.reply('OK', 200);
+};
+
+/** enableDailyBackup: from now the database is backed up every day (semantics/time.ts), answered "OK". */
+const enableDailyBackup: Semantics = async (ctx) => {
+  const id = String(ctx.call.params.id);
+  const db = live(ctx, id);
+  if (!db) return ctx.notFound('Database', id, 'id');
+  await ctx.write('Database', id, { ...ctx.own(db), daily_backup_enabled: true, _daily_since: ctx.occurredAt }, 'database.enable-dailybackup');
+  return ctx.reply('OK', 200);
+};
+
+export const backupSemantics: Record<string, Semantics> = { createBackup, listBackup, deleteBackup, restoreBackup, enableDailyBackup };

package/api/src/semantics/index.ts

@@ -0,0 +1,191 @@
+// The Developer API lane's handlers, by operationId. Where Upstash's reference stops and the twin decides, the comment
+// beside the rule says so.
+import { createHash } from 'node:crypto';
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { execRedisRun } from '../../../src/upstash-store.ts';
+import { backupSemantics } from './backups.ts';
+import { teamSemantics } from './teams.ts';
+import { backingUp, badRequest, body, emailOf, hex, live, ownFields, uuidOf, type Row } from './shared.ts';
+
+// the CreateDatabaseRequest schema's enums
+const PLATFORMS = ['aws', 'gcp'];
+const REGIONS = ['us-east-1', 'us-east-2', 'us-west-1', 'us-west-2', 'ca-central-1', 'eu-central-1', 'eu-west-1', 'eu-west-2', 'sa-east-1', 'ap-south-1',
+  'ap-northeast-1', 'ap-southeast-1', 'ap-southeast-2', 'af-south-1', 'us-central1', 'us-east4', 'europe-west1', 'asia-northeast1'];
+const PLANS = ['free', 'payg', 'fixed_250mb', 'fixed_1gb', 'fixed_5gb', 'fixed_10gb', 'fixed_50gb', 'fixed_100gb', 'fixed_500gb'];
+
+// an endpoint slug in the shape the Database schema's example has ("beloved-stallion-58500"); the words are the twin's
+const ADJECTIVES = ['beloved', 'brave', 'calm', 'clever', 'eager', 'gentle', 'happy', 'lucky', 'merry', 'proud', 'quiet', 'striking'];
+const ANIMALS = ['stallion', 'osprey', 'cat', 'heron', 'otter', 'lynx', 'badger', 'falcon', 'marten', 'wren', 'bison', 'gecko'];
+
+const MB = 1024 * 1024;
+const GB = 1024 * MB;
+/** The pay-as-you-go and fixed plans' "Unlimited" monthly commands: no page says how the API writes it, so the twin
+ *  answers the Database schema's example `db_request_limit` (8024278031528737000), a paid database's. */
+const UNLIMITED = 8024278031528737000;
+/** A plan's limits as https://upstash.com/pricing/redis tables them: the plans table ("Max data size", "Monthly Commands",
+ *  "Max commands per second", "Max request size", "Max record size": Free 256 MB, 500K, 10,000, 10 MB, 100 MB; Pay as You
+ *  Go 100 GB, Unlimited, 10,000, 10 MB, 100 MB) and "Fixed plans — all tiers" ("Max data", "Max commands/sec", "Max
+ *  request size", "Max record size" per tier; their Monthly Commands "Unlimited"). */
+const limits = (disk: number, requests: number, perSecond: number, request: number, entry: number): Row =>
+  ({ db_disk_threshold: disk, db_request_limit: requests, db_max_commands_per_second: perSecond, db_max_request_size: request, db_max_entry_size: entry });
+const PLAN_LIMITS: Record<string, Row> = {
+  free: limits(256 * MB, 500000, 10000, 10 * MB, 100 * MB),
+  payg: limits(100 * GB, UNLIMITED, 10000, 10 * MB, 100 * MB),
+  fixed_250mb: limits(250 * MB, UNLIMITED, 10000, 10 * MB, 100 * MB),
+  fixed_1gb: limits(1 * GB, UNLIMITED, 10000, 10 * MB, 200 * MB),
+  fixed_5gb: limits(5 * GB, UNLIMITED, 10000, 20 * MB, 300 * MB),
+  fixed_10gb: limits(10 * GB, UNLIMITED, 10000, 30 * MB, 400 * MB),
+  fixed_50gb: limits(50 * GB, UNLIMITED, 10000, 50 * MB, 500 * MB),
+  fixed_100gb: limits(100 * GB, UNLIMITED, 16000, 75 * MB, 1 * GB),
+  fixed_500gb: limits(500 * GB, UNLIMITED, 16000, 100 * MB, 5 * GB),
+};
+
+const FREE_REGIONS = 'Free usage is limited with max one read region';
+
+/** The free plan's refusals, each 400 (the twin's reading of the HTTP status codes page's "Your request is invalid"): "Max
+ *  Databases 1" (https://upstash.com/pricing/redis) and "Free usage is limited with max one read region"
+ *  (https://upstash.com/docs/redis/features/globaldatabase). */
+function freePlanRefusal(ctx: SemanticsContext, owner: string, readRegions: string[]): Response | undefined {
+  if (readRegions.length > 1) return badRequest(ctx, FREE_REGIONS);
+  if (ctx.rowsRaw('Database').some((d) => d._owner === owner && ctx.own(d).type === 'free' && !d._deleted_at)) return badRequest(ctx, 'The free plan allows 1 database');
+  return undefined;
+}
+
+/** A database's id from the World's instant, the name and the count, so a World mints the same id every run. */
+const mintUuid = (ctx: SemanticsContext, seed: string): string => uuidOf(`database:${ctx.occurredAt}:${seed}:${ctx.rowsRaw('Database', { withDeleted: true }).length + 1}`);
+
+/** A database's own fields (never the kernel's), as the Database schema answers it; `credentials=hide` leaves out its
+ *  password and REST tokens. */
+export function view(record: Row, hide: boolean): Row {
+  const out = ownFields(record);
+  if (hide) { delete out.password; delete out.rest_token; delete out.read_only_rest_token; }
+  return out;
+}
+
+/** A database's password and REST tokens, new for every instant they are made at and every reset (`generation`). */
+function credentials(ctx: SemanticsContext, id: string, generation = 0): Row {
+  const secret = (what: string, length: number): string => createHash('sha256').update(`${what}:${id}:${ctx.occurredAt}:${generation}`).digest('base64url').slice(0, length);
+  // the Standard and Read Only REST tokens (the spec patch, from Upstash's Terraform provider): the twin's tokens are
+  // opaque strings in the shape Upstash's have, an `A` then base64url
+  return { password: secret('password', 32), rest_token: `A${secret('rest', 59)}`, read_only_rest_token: `Ag${secret('readonly', 58)}` };
+}
+
+/** createDatabase. `database_name` and `primary_region` are required (CreateDatabaseRequest, whose `platform` the spec
+ *  patch makes optional: Upstash's own CLI sends none, spec/patches.json), each enum as the schema lists it; a database
+ *  made without a platform is on aws (the twin's decision). `region` is `global`, the one value the CLI sends. Where the reference stops and the twin decides: a missing or unlisted field, and a name the
+ *  account already has, answer 400 naming it; the database is `active` at once (the getDatabase example's state), on the
+ *  plan asked for or `free` ("If omitted, the database defaults to either the pay-as-you-go or free plan, based on the
+ *  account type": an account is free unless the World made it pay-as-you-go, screens/session.tsx's door); its limits are its plan's (PLAN_LIMITS, from
+ *  https://upstash.com/pricing/redis), with the schema's example values for the rest (manifest.ts names them). Its
+ *  REST endpoint is `https://<endpoint>.upstash.io`, which answers its two REST tokens (the pack root's auth). */
+const createDatabase: Semantics = async (ctx) => {
+  const b = body(ctx);
+  const name = typeof b.database_name === 'string' ? b.database_name.trim() : '';
+  if (!name) return badRequest(ctx, 'database_name is required');
+  if (b.platform !== undefined && !PLATFORMS.includes(String(b.platform))) return badRequest(ctx, `platform must be one of ${PLATFORMS.join(', ')}`);
+  if (typeof b.primary_region !== 'string' || !REGIONS.includes(b.primary_region)) return badRequest(ctx, `primary_region must be one of ${REGIONS.join(', ')}`);
+  const owner = emailOf(ctx);
+  const plan = b.plan === undefined ? String(ctx.rowsRaw('_person').find((p) => p.email === owner)?.plan ?? 'free') : String(b.plan);
+  if (!PLANS.includes(plan)) return badRequest(ctx, `plan must be one of ${PLANS.join(', ')}`);
+  const readRegions = Array.isArray(b.read_regions) ? b.read_regions.map(String) : [];
+  const freeRefusal = plan === 'free' ? freePlanRefusal(ctx, owner, readRegions) : undefined;
+  if (freeRefusal) return freeRefusal;
+  if (ctx.rowsRaw('Database').some((d) => d.database_name === name && d._owner === owner && !d._deleted_at)) return badRequest(ctx, `database ${name} already exists`);
+  const id = mintUuid(ctx, name);
+  const h = hex(`endpoint:${id}`);
+  const endpoint = `${ADJECTIVES[parseInt(h.slice(0, 2), 16) % ADJECTIVES.length]}-${ANIMALS[parseInt(h.slice(2, 4), 16) % ANIMALS.length]}-${10000 + (parseInt(h.slice(4, 10), 16) % 90000)}`;
+  const fields: Row = {
+    database_id: id, database_name: name, region: 'global', port: 6379, creation_time: Math.floor(Date.parse(ctx.occurredAt) / 1000),
+    state: 'active', ...credentials(ctx, id), endpoint, tls: b.tls !== false, type: plan === 'free' ? 'free' : plan === 'payg' ? 'payg' : 'paid',
+    budget: typeof b.budget === 'number' ? b.budget : 0, primary_region: b.primary_region, primary_members: [b.primary_region],
+    all_members: [b.primary_region, ...readRegions], read_regions: readRegions, eviction: b.eviction === true, auto_upgrade: false, consistent: false,
+    modifying_state: '', db_max_clients: 10000, ...PLAN_LIMITS[plan],
+    db_memory_threshold: 268435456, db_resource_size: 'S', db_type: 'pebble',
+    // the Database schema's example values (the reference page's rendered answer) for the limits no page states per plan
+    // (manifest.ts records them as the twin's choice)
+    db_conn_idle_timeout: 21600000000000, db_lua_timeout: 250000000, db_lua_credits_per_min: 10000000000, db_store_max_idle: 900000000000,
+    db_max_loads_per_sec: 1000000, replicas: 5,
+    securityAddons: { ipWhitelisting: false, vpcPeering: false, privateLink: false, tlsMutualAuth: false, encryptionAtRest: false },
+    db_acl_enabled: 'false', db_acl_default_user_status: 'true', db_eviction: b.eviction === true, last_plan_upgrade_time: 0,
+    customer_id: owner, daily_backup_enabled: false, prometheus_enabled: 'false', prod_pack_enabled: false,
+    _owner: owner,
+  };
+  await ctx.write('Database', id, fields, 'database.create');
+  return ctx.reply(view(fields, false), 200);
+};
+
+/** getDatabase. `credentials=hide` "remove[s] credentials from the response". A database the account deleted, or never
+ *  had, answers 404 (the twin's decision; the reference declares no error response). */
+const getDatabase: Semantics = async (ctx) => {
+  const id = String(ctx.call.params.id);
+  const record = live(ctx, id);
+  if (!record) return ctx.notFound('Database', id, 'id');
+  return ctx.reply(view(ctx.own(record), new URL(ctx.call.request.url).searchParams.get('credentials') === 'hide'));
+};
+
+/** deleteDatabase answers "OK" (its 200 schema). A deleted database's data goes with it and its REST tokens answer the
+ *  REST API's 401 from then on (the pack root's auth): the twin empties its keyspace with FLUSHALL on its own database. */
+const deleteDatabase: Semantics = async (ctx) => {
+  const id = String(ctx.call.params.id);
+  const record = live(ctx, id);
+  if (!record) return ctx.notFound('Database', id, 'id');
+  await execRedisRun([['FLUSHALL']], { ...(ctx.root !== undefined ? { root: ctx.root } : {}), occurredAt: ctx.occurredAt, database: id });
+  await ctx.write('Database', id, { ...ctx.own(record), _deleted_at: ctx.occurredAt }, 'database.delete');
+  return ctx.reply('OK', 200);
+};
+
+// ── API keys (made on the console's Developer API tab, screens/developer-api.tsx) ─────────────
+
+/** A new API key for `email`: its name, permission and expiry, the key shown once and kept as its SHA-256. */
+export async function makeApiKey(ctx: SemanticsContext, email: string, name: string, permission: 'read_write' | 'read_only', expiresAt: string | null): Promise<{ key: string }> {
+  const n = ctx.rowsRaw('_api_key').length + 1;
+  const key = hex(`apikey:${email}:${name}:${ctx.occurredAt}:${n}`).slice(0, 36);
+  await ctx.record('_api_key', { email, name, permission, expires_at: expiresAt, created_at: ctx.occurredAt, deleted: false, key_sha256: hex(key) }, `apikey:${email}:${name}`);
+  return { key };
+}
+
+/** resetPassword "updates the password of a database" (the spec), and "You can revoke both _Standard_ and _Read Only_
+ *  tokens by resetting password of your database" (https://upstash.com/docs/redis/features/restapi): the old tokens
+ *  answer the REST API's 401 from then on (the pack root's auth reads them from this record). Its answer is the
+ *  `Database` with the new credentials (the twin's reading of its 200 schema; the page does not say). */
+const resetPassword: Semantics = async (ctx) => {
+  const id = String(ctx.call.params.id);
+  const record = live(ctx, id);
+  if (!record) return ctx.notFound('Database', id, 'id');
+  const own = ctx.own(record);
+  const revoked = [...(Array.isArray(own._revoked_tokens) ? own._revoked_tokens : []), own.rest_token, own.read_only_rest_token];
+  const fields = { ...own, ...credentials(ctx, id, revoked.length), _revoked_tokens: revoked };
+  await ctx.write('Database', id, fields, 'database.reset-password');
+  return ctx.reply(view(fields, false), 200);
+};
+
+// the read regions update-regions takes (its request schema's enum)
+const READ_REGIONS = ['us-east-1', 'us-east-2', 'us-west-1', 'us-west-2', 'ca-central-1', 'eu-central-1', 'eu-west-1', 'eu-west-2', 'sa-east-1', 'ap-south-1', 'ap-northeast-1', 'ap-southeast-1', 'ap-southeast-2'];
+
+/** updateRegions sets a database's read regions ("You can add or remove regions on a running Redis database",
+ *  https://upstash.com/docs/redis/features/globaldatabase) and answers "OK". Where the reference stops and the twin
+ *  decides: a region outside the schema's enum, or no array, answers 400; writes still go to the primary region. */
+const updateRegions: Semantics = async (ctx) => {
+  const id = String(ctx.call.params.id);
+  const record = live(ctx, id);
+  if (!record) return ctx.notFound('Database', id, 'id');
+  const asked = body(ctx).read_regions;
+  const regions = Array.isArray(asked) ? asked.map(String) : ['none'];
+  if (regions.some((r) => !READ_REGIONS.includes(r))) return badRequest(ctx, `read_regions must be an array of ${READ_REGIONS.join(', ')}`);
+  if (ctx.own(record).type === 'free' && regions.length > 1) return badRequest(ctx, FREE_REGIONS);
+  const busy = backingUp(ctx, id);
+  if (busy) return busy;
+  const own = ctx.own(record);
+  await ctx.write('Database', id, { ...own, read_regions: regions, all_members: [own.primary_region, ...regions] }, 'database.update-regions');
+  return ctx.reply('OK', 200);
+};
+
+export const apiSemantics: Record<string, Semantics> = {
+  createDatabase,
+  getDatabase,
+  deleteDatabase,
+  resetPassword,
+  updateRegions,
+  ...backupSemantics,
+  ...teamSemantics,
+};

package/api/src/semantics/shared.ts

@@ -0,0 +1,42 @@
+// What the Developer API lane's handlers share: the caller's account, a database it reaches, a request body, a refusal,
+// and the twin's deterministic ids.
+import { createHash } from 'node:crypto';
+import type { SemanticsContext } from '@volter/world-core';
+
+export type Row = Record<string, unknown>;
+export const hex = (s: string): string => createHash('sha256').update(s).digest('hex');
+export const badRequest = (ctx: SemanticsContext, message: string): Response => ctx.refuse({ status: 400, code: 'bad_request', message });
+export const forbidden = (ctx: SemanticsContext, message: string): Response => ctx.refuse({ status: 403, code: 'forbidden', message });
+export const body = (ctx: SemanticsContext): Row => (ctx.body && typeof ctx.body === 'object' && !Array.isArray(ctx.body) ? (ctx.body as Row) : {});
+
+/** A UUID from a seed (the World's instant, a name, a count), so a World mints the same ids every run. */
+export function uuidOf(seed: string): string {
+  const h = hex(seed);
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-4${h.slice(13, 16)}-8${h.slice(17, 20)}-${h.slice(20, 32)}`;
+}
+
+/** The account email the request's Basic credential names (key-gate.ts has admitted only an issued one). */
+export function emailOf(ctx: SemanticsContext): string {
+  const decoded = Buffer.from(/^basic\s+(\S+)$/i.exec(ctx.call.request.headers.get('authorization') ?? '')?.[1] ?? '', 'base64').toString('utf8');
+  return decoded.slice(0, decoded.indexOf(':')).toLowerCase();
+}
+
+/** A record's own fields (never the lane's `_` bookkeeping), as the vendor's schema answers it. */
+export function ownFields(record: Row): Row {
+  return Object.fromEntries(Object.entries(record).filter(([k]) => !k.startsWith('_')));
+}
+
+/** A live database the caller's account reaches: its own, or one moved under a team it owns (moveToTeam makes the
+ *  team's owner the database's `_owner`). Where Upstash's pages stop and the twin decides: that the owner's key reaches
+ *  the team's databases is not stated (../../journeys/customer-life.outline.md, "Where the evidence stops"). */
+/** A backup of the database still running: "During a backup operation, certain administrative operations will be
+ *  temporarily unavailable: Backup operations, database config changes, plan and region setup, transferring database"
+ *  (https://upstash.com/docs/redis/features/backup). Answered 400: the status is the twin's reading of
+ *  https://upstash.com/docs/devops/developer-api/http_status_codes ("Your request is invalid"). */
+export function backingUp(ctx: SemanticsContext, database: string): Response | undefined {
+  return ctx.rowsRaw('Backup').some((k) => k.database_id === database && k.state === 'pending' && !k._deleted_at)
+    ? badRequest(ctx, 'A backup of this database is in progress: backup operations, database config changes, plan and region setup and transferring the database are unavailable until it completes')
+    : undefined;
+}
+
+export const live = (ctx: SemanticsContext, id: string): Row | undefined => ctx.rowsRaw('Database').find((d) => d.database_id === id && !d._deleted_at && d._owner === emailOf(ctx));

package/api/src/semantics/teams.ts

@@ -0,0 +1,108 @@
+// Teams (https://upstash.com/docs/common/account/teams; the spec's create-team, move-to-team, add-team-member,
+// delete-team-member and delete-team). "Team management enables collaboration with other users. You can create a team and
+// invite people to join by using their email addresses." A member is added with a role and "we will send an invitation
+// email to that address. The user joins the team by clicking the acceptance link in the email ... Until the invitation is
+// accepted, the user appears as a pending member" (the console's Account > Teams page, ../screens/teams.tsx, where the
+// link also lands). "Only Admins or the Owner can add/remove users." "Only the original creator (owner) can delete a
+// team. Also the team should not have any active databases."
+//
+// Where the pages stop and the twin decides: a team's id is a UUID (the Team schema's example); its creator is its
+// member with the role `owner`; a database moved under a team keeps answering its owner's key (shared.ts, `live`) and
+// its `customer_id` becomes the team's id ("Customer identifier (email or team ID)", the spec's QStashUser); a refused
+// call answers 400 (a request the rules refuse) or 403 (a caller the rules refuse) in the document's Error schema; the
+// invitation email is the World's record, read at `GET console.upstash.com/_twin/mail?to=` (../screens/teams.tsx).
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { backingUp, badRequest, body, emailOf, forbidden, hex, live, ownFields, uuidOf, type Row } from './shared.ts';
+
+const ROLES = ['admin', 'dev', 'finance'];
+/** The invitation mails the World's mail door shows. */
+export const MAIL = '_mail';
+
+/** A live team by id. */
+export const teamOf = (ctx: SemanticsContext, id: string): Row | undefined => ctx.rowsRaw('Team').find((t) => t.team_id === id && !t._deleted_at);
+/** The team's members, pending ones included, never removed ones. */
+export const membersOf = (ctx: SemanticsContext, team: string): Row[] => ctx.rowsRaw('TeamMember').filter((m) => m.team_id === team && !m._removed_at);
+/** The role a person holds in a team they have joined, or undefined. */
+export const roleOf = (ctx: SemanticsContext, team: string, email: string): string | undefined =>
+  membersOf(ctx, team).find((m) => m.member_email === email && m._pending !== true)?.member_role as string | undefined;
+const manages = (ctx: SemanticsContext, team: string, email: string): boolean => ['owner', 'admin'].includes(roleOf(ctx, team, email) ?? '');
+
+/** createTeam {team_name, copy_cc}: the team, its creator its owner, answered as the Team schema. */
+const createTeam: Semantics = async (ctx) => {
+  const b = body(ctx);
+  const name = typeof b.team_name === 'string' ? b.team_name.trim() : '';
+  if (!name || typeof b.copy_cc !== 'boolean') return badRequest(ctx, 'team_name and copy_cc are required');
+  const owner = emailOf(ctx);
+  // "A user can create up to 5 teams. You can be part of even more teams but only be the owner of 5 teams."
+  if (ctx.rowsRaw('Team').filter((t) => t._owner === owner && !t._deleted_at).length >= 5) return badRequest(ctx, 'A user can create up to 5 teams');
+  const id = uuidOf(`team:${ctx.occurredAt}:${name}:${ctx.rowsRaw('Team', { withDeleted: true }).length + 1}`);
+  const team = { team_id: id, team_name: name, copy_cc: b.copy_cc, _owner: owner };
+  await ctx.write('Team', id, team, 'team.create');
+  await ctx.write('TeamMember', `${id}:${owner}`, { team_id: id, team_name: name, member_email: owner, member_role: 'owner', copy_cc: b.copy_cc }, 'team.owner');
+  return ctx.reply(ownFields(team), 200);
+};
+
+/** moveToTeam {team_id, database_id}: the database goes under the team, answered "OK". */
+const moveToTeam: Semantics = async (ctx) => {
+  const b = body(ctx);
+  const db = live(ctx, String(b.database_id ?? ''));
+  if (!db) return ctx.notFound('Database', String(b.database_id ?? ''), 'database_id');
+  const team = teamOf(ctx, String(b.team_id ?? ''));
+  if (!team || roleOf(ctx, String(team.team_id), emailOf(ctx)) === undefined) return badRequest(ctx, `team ${String(b.team_id ?? '')} is not a team of yours`);
+  // "Finance: This role is limited to managing payment methods and cannot manage databases or users"
+  if (roleOf(ctx, String(team.team_id), emailOf(ctx)) === 'finance') return forbidden(ctx, 'A Finance member cannot manage databases');
+  const busy = backingUp(ctx, String(db.database_id));
+  if (busy) return busy;
+  await ctx.write('Database', String(db.database_id), { ...ctx.own(db), customer_id: team.team_id, _team: team.team_id, _owner: team._owner }, 'database.move-to-team');
+  return ctx.reply('OK', 200);
+};
+
+/** addTeamMember {team_id, member_email, member_role}: a pending member, and the invitation mailed to them. */
+const addTeamMember: Semantics = async (ctx) => {
+  const b = body(ctx);
+  const team = teamOf(ctx, String(b.team_id ?? ''));
+  const email = String(b.member_email ?? '').trim().toLowerCase();
+  if (!team) return badRequest(ctx, `team ${String(b.team_id ?? '')} does not exist`);
+  if (!manages(ctx, String(team.team_id), emailOf(ctx))) return forbidden(ctx, 'Only Admins or the Owner can add/remove users');
+  if (!/^[^@\s]+@[^@\s]+$/.test(email) || !ROLES.includes(String(b.member_role))) return badRequest(ctx, `member_email and a member_role of ${ROLES.join(', ')} are required`);
+  if (membersOf(ctx, String(team.team_id)).some((m) => m.member_email === email)) return badRequest(ctx, `${email} is already a member of ${String(team.team_name)}`);
+  const token = hex(`invite:${String(team.team_id)}:${email}:${ctx.occurredAt}`).slice(0, 40);
+  const member = { team_id: team.team_id, team_name: team.team_name, member_email: email, member_role: b.member_role, copy_cc: team.copy_cc, _pending: true, _invite: token };
+  await ctx.write('TeamMember', `${String(team.team_id)}:${email}`, member, 'team.add-member');
+  await ctx.record(MAIL, {
+    to: email, at: ctx.occurredAt, subject: `You are invited to join ${String(team.team_name)} on Upstash`,
+    text: `${emailOf(ctx)} invited you to join the team ${String(team.team_name)} as ${String(b.member_role)}. Accept the invitation: https://console.upstash.com/invite/${token}`,
+  }, `mail:invite:${token}`);
+  return ctx.reply(ownFields(member), 200);
+};
+
+/** Remove a member or revoke a pending invitation (the API's delete-team-member; the Teams page's Revoke Invite). */
+export async function removeMember(ctx: SemanticsContext, team: string, email: string, operation: string): Promise<string | undefined> {
+  const member = membersOf(ctx, team).find((m) => m.member_email === email);
+  if (!member || member.member_role === 'owner') return `${email} is not a member you can remove`;
+  await ctx.write('TeamMember', `${team}:${email}`, { ...ctx.own(member), _removed_at: ctx.occurredAt }, operation);
+  return undefined;
+}
+
+/** deleteTeamMember {team_id, member_email}: the member goes, answered "OK". */
+const deleteTeamMember: Semantics = async (ctx) => {
+  const b = body(ctx);
+  const team = teamOf(ctx, String(b.team_id ?? ''));
+  if (!team) return badRequest(ctx, `team ${String(b.team_id ?? '')} does not exist`);
+  if (!manages(ctx, String(team.team_id), emailOf(ctx))) return forbidden(ctx, 'Only Admins or the Owner can add/remove users');
+  const refused = await removeMember(ctx, String(team.team_id), String(b.member_email ?? '').trim().toLowerCase(), 'team.delete-member');
+  return refused ? badRequest(ctx, refused) : ctx.reply('OK', 200);
+};
+
+/** deleteTeam: the team goes, answered "OK"; only its owner, and only once it has no database. */
+const deleteTeam: Semantics = async (ctx) => {
+  const id = String(ctx.call.params.id);
+  const team = teamOf(ctx, id);
+  if (!team) return ctx.notFound('Team', id, 'id');
+  if (team._owner !== emailOf(ctx)) return forbidden(ctx, 'Only the original creator (owner) can delete a team');
+  if (ctx.rowsRaw('Database').some((d) => d._team === id && !d._deleted_at)) return badRequest(ctx, 'The team should not have any active databases: delete its databases first');
+  await ctx.write('Team', id, { ...ctx.own(team), _deleted_at: ctx.occurredAt }, 'team.delete');
+  return ctx.reply('OK', 200);
+};
+
+export const teamSemantics: Record<string, Semantics> = { createTeam, moveToTeam, addTeamMember, deleteTeamMember, deleteTeam };

package/api/src/semantics/time.ts

@@ -0,0 +1,40 @@
+// What the World clock does to the Developer API lane's records, caught up before any request to the pack is answered
+// (index.ts, and the pack root's REST API through ../../../src/upstash-server.ts, so a backup due before a write holds the
+// keys as they were), each written at the instant it fell due: with daily backup on, "your database will be
+// automatically backed up every day" (https://upstash.com/docs/redis/features/backup); a backup completes, and a daily
+// backup is gone when its retention has passed. The times are the twin's (semantics/backups.ts).
+import type { SemanticsContext } from '@volter/world-core';
+import { COMPLETE_AFTER_MS, DAILY_KEPT_MS, makeBackup } from './backups.ts';
+
+const DAY_MS = 86_400_000;
+const iso = (ms: number): string => new Date(ms).toISOString();
+/** The first 00:00 UTC strictly after an instant. */
+const nextMidnight = (ms: number): number => (Math.floor(ms / DAY_MS) + 1) * DAY_MS;
+
+export async function catchUp(ctx: SemanticsContext): Promise<void> {
+  const now = Date.parse(ctx.occurredAt);
+  for (const db of ctx.rowsRaw('Database')) {
+    if (db._deleted_at || db.daily_backup_enabled !== true) continue;
+    const last = ctx.rowsRaw('Backup', { withDeleted: true }).filter((k) => k.database_id === db.database_id && k.daily_backup === 'true')
+      .reduce((m, k) => Math.max(m, Date.parse(String(k._created_at))), Date.parse(String(db._daily_since)));
+    for (let due = nextMidnight(last); due <= now; due += DAY_MS) {
+      const at = await ctx.at(iso(due));
+      await makeBackup(at, db, `daily-backup-${iso(due).slice(0, 10)}`, true);
+    }
+  }
+  for (const k of ctx.rowsRaw('Backup')) {
+    const made = Date.parse(String(k._created_at));
+    let row = k;
+    if (row.state === 'pending' && made + COMPLETE_AFTER_MS <= now) {
+      const at = await ctx.at(iso(made + COMPLETE_AFTER_MS));
+      if (at.legal('Backup', 'state', 'complete', 'pending', 'completed', String(k.backup_id), 'time')) continue;
+      row = { ...at.own(row), state: 'completed' };
+      await at.write('Backup', String(k.backup_id), row, 'backup.complete');
+    }
+    const gone = made + COMPLETE_AFTER_MS + DAILY_KEPT_MS;
+    if (row.daily_backup === 'true' && row.state === 'completed' && gone <= now) {
+      const at = await ctx.at(iso(gone));
+      await at.write('Backup', String(k.backup_id), { ...at.own(row), _deleted_at: iso(gone) }, 'backup.expire');
+    }
+  }
+}

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

@@ -0,0 +1,15 @@
+import { type DerivedOwner } from '@volter/world-core';
+export declare const API_HOST = "api.upstash.com";
+export declare const CONSOLE_HOST = "console.upstash.com";
+/** The lane's fetch: a request, and the vendor host it was sent to (api.upstash.com or console.upstash.com). */
+export type UpstashRedisApiFetch = ((request: Request, host: string) => Promise<Response>) & {
+    owners(): Record<string, DerivedOwner>;
+    /** What the World clock has made due (a daily backup, a backup completing), caught up for a request another wire of
+     *  the pack answers: the REST API's write lands after the night's backup, never inside it. */
+    catchUp(request: Request): Promise<void>;
+};
+export declare function createUpstashApiLaneFetch(options?: {
+    root?: string;
+    readOnly?: boolean;
+    clock?: () => string;
+}): UpstashRedisApiFetch;

package/dist/api/src/fetch.js

@@ -0,0 +1,44 @@
+// The Developer API lane of the upstash pack (`api.upstash.com/v2`), as a plain fetch: the pack's router
+// (../../src/upstash-server.ts) sends every request for api.upstash.com here, and every one for
+// console.upstash.com (its sign-in, the Account > Developer API tab, Account > Teams and a team invitation's link, and the
+// QStash page, screens/). What the World clock has made due is caught up first (semantics/time.ts). The generated surface is Upstash's own
+// OpenAPI document; the key gate sits in front of the dispatch (key-gate.ts), then the kernel's cross-cutting checks
+// (read-only, a malformed body), then the handlers (semantics/). An operation this lane does not serve is the gap,
+// answered 404 in the document's Error schema (the twin's decision: the document declares no error response).
+import { bindSemantics, coreFor, createDerivedFetch, crossCutting, semanticsContext } from '@volter/world-core';
+import surface from './generated/surface.gen.json' with { type: 'json' };
+import { manifest } from "./manifest.js";
+import { apiSemantics } from "./semantics/index.js";
+import { keyGate } from "./key-gate.js";
+import { developerApiPage } from "./screens/developer-api.js";
+import { sessionFlow } from "./screens/session.js";
+import { qstashPage } from "./screens/qstash.js";
+import { teamsPages } from "./screens/teams.js";
+import { catchUp } from "./semantics/time.js";
+const SCREEN = { id: 'DeveloperApiPage', method: 'POST', path: '/account/api', class: 'action' };
+const GATE = { id: 'TwinKeyGate', method: 'GET', path: '/v2/redis/databases', class: 'retrieve' };
+export const API_HOST = 'api.upstash.com';
+export const CONSOLE_HOST = 'console.upstash.com';
+export function createUpstashApiLaneFetch(options = {}) {
+    const scope = { ...(options.root !== undefined ? { root: options.root } : {}), ...(options.clock ? { clock: options.clock } : {}) };
+    const derived = createDerivedFetch({
+        surface: surface,
+        handlers: bindSemantics(manifest, apiSemantics, scope),
+        core: coreFor(manifest, scope),
+        around: crossCutting(manifest, { readOnly: options.readOnly ?? false, ...scope }),
+        gap: () => Response.json({ code: 'not_found', message: 'Not Found' }, { status: 404 }),
+    });
+    const contextFor = (request) => semanticsContext(manifest, request, SCREEN, scope);
+    const due = async (request) => { if (!options.readOnly)
+        await catchUp(await contextFor(new Request(request.url))); };
+    return Object.assign(async (request, host) => {
+        await due(request);
+        if (host === CONSOLE_HOST) {
+            const screen = (await sessionFlow(request.clone(), await contextFor(new Request(request.url)))) ?? (await qstashPage(request.clone(), contextFor))
+                ?? (await teamsPages(request.clone(), contextFor)) ?? (await developerApiPage(request, contextFor));
+            return screen ?? new Response('Not Found', { status: 404, headers: { 'content-type': 'text/plain' } });
+        }
+        const ctx = await semanticsContext(manifest, new Request(request.url, { headers: request.headers }), GATE, scope);
+        return keyGate(ctx, request) ?? derived(request);
+    }, { owners: () => derived.owners(), catchUp: due });
+}

package/dist/api/src/fetch.ts

@@ -0,0 +1,54 @@
+// The Developer API lane of the upstash pack (`api.upstash.com/v2`), as a plain fetch: the pack's router
+// (../../src/upstash-server.ts) sends every request for api.upstash.com here, and every one for
+// console.upstash.com (its sign-in, the Account > Developer API tab, Account > Teams and a team invitation's link, and the
+// QStash page, screens/). What the World clock has made due is caught up first (semantics/time.ts). The generated surface is Upstash's own
+// OpenAPI document; the key gate sits in front of the dispatch (key-gate.ts), then the kernel's cross-cutting checks
+// (read-only, a malformed body), then the handlers (semantics/). An operation this lane does not serve is the gap,
+// answered 404 in the document's Error schema (the twin's decision: the document declares no error response).
+import { bindSemantics, coreFor, createDerivedFetch, crossCutting, semanticsContext, type DerivedOperation, type DerivedOwner, type DerivedSurface } from '@volter/world-core';
+import surface from './generated/surface.gen.json' with { type: 'json' };
+import { manifest } from './manifest.ts';
+import { apiSemantics } from './semantics/index.ts';
+import { keyGate } from './key-gate.ts';
+import { developerApiPage } from './screens/developer-api.tsx';
+import { sessionFlow } from './screens/session.tsx';
+import { qstashPage } from './screens/qstash.tsx';
+import { teamsPages } from './screens/teams.tsx';
+import { catchUp } from './semantics/time.ts';
+
+const SCREEN: DerivedOperation = { id: 'DeveloperApiPage', method: 'POST', path: '/account/api', class: 'action' };
+const GATE: DerivedOperation = { id: 'TwinKeyGate', method: 'GET', path: '/v2/redis/databases', class: 'retrieve' };
+
+export const API_HOST = 'api.upstash.com';
+export const CONSOLE_HOST = 'console.upstash.com';
+
+/** The lane's fetch: a request, and the vendor host it was sent to (api.upstash.com or console.upstash.com). */
+export type UpstashRedisApiFetch = ((request: Request, host: string) => Promise<Response>) & {
+  owners(): Record<string, DerivedOwner>;
+  /** What the World clock has made due (a daily backup, a backup completing), caught up for a request another wire of
+   *  the pack answers: the REST API's write lands after the night's backup, never inside it. */
+  catchUp(request: Request): Promise<void>;
+};
+
+export function createUpstashApiLaneFetch(options: { root?: string; readOnly?: boolean; clock?: () => string } = {}): UpstashRedisApiFetch {
+  const scope = { ...(options.root !== undefined ? { root: options.root } : {}), ...(options.clock ? { clock: options.clock } : {}) };
+  const derived = createDerivedFetch({
+    surface: surface as DerivedSurface,
+    handlers: bindSemantics(manifest, apiSemantics, scope),
+    core: coreFor(manifest, scope),
+    around: crossCutting(manifest, { readOnly: options.readOnly ?? false, ...scope }),
+    gap: () => Response.json({ code: 'not_found', message: 'Not Found' }, { status: 404 }),
+  });
+  const contextFor = (request: Request) => semanticsContext(manifest, request, SCREEN, scope);
+  const due = async (request: Request): Promise<void> => { if (!options.readOnly) await catchUp(await contextFor(new Request(request.url))); };
+  return Object.assign(async (request: Request, host: string): Promise<Response> => {
+    await due(request);
+    if (host === CONSOLE_HOST) {
+      const screen = (await sessionFlow(request.clone(), await contextFor(new Request(request.url)))) ?? (await qstashPage(request.clone(), contextFor))
+        ?? (await teamsPages(request.clone(), contextFor)) ?? (await developerApiPage(request, contextFor));
+      return screen ?? new Response('Not Found', { status: 404, headers: { 'content-type': 'text/plain' } });
+    }
+    const ctx = await semanticsContext(manifest, new Request(request.url, { headers: request.headers }), GATE, scope);
+    return keyGate(ctx, request) ?? derived(request);
+  }, { owners: () => derived.owners(), catchUp: due });
+}