@volter/twin-upstash 0.1.0

package/dist/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/dist/api/src/semantics/shared.d.ts

@@ -0,0 +1,21 @@
+import type { SemanticsContext } from '@volter/world-core';
+export type Row = Record<string, unknown>;
+export declare const hex: (s: string) => string;
+export declare const badRequest: (ctx: SemanticsContext, message: string) => Response;
+export declare const forbidden: (ctx: SemanticsContext, message: string) => Response;
+export declare const body: (ctx: SemanticsContext) => Row;
+/** A UUID from a seed (the World's instant, a name, a count), so a World mints the same ids every run. */
+export declare function uuidOf(seed: string): string;
+/** The account email the request's Basic credential names (key-gate.ts has admitted only an issued one). */
+export declare function emailOf(ctx: SemanticsContext): string;
+/** A record's own fields (never the lane's `_` bookkeeping), as the vendor's schema answers it. */
+export declare function ownFields(record: Row): Row;
+/** 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 declare function backingUp(ctx: SemanticsContext, database: string): Response | undefined;
+export declare const live: (ctx: SemanticsContext, id: string) => Row | undefined;

package/dist/api/src/semantics/shared.js

@@ -0,0 +1,34 @@
+// 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';
+export const hex = (s) => createHash('sha256').update(s).digest('hex');
+export const badRequest = (ctx, message) => ctx.refuse({ status: 400, code: 'bad_request', message });
+export const forbidden = (ctx, message) => ctx.refuse({ status: 403, code: 'forbidden', message });
+export const body = (ctx) => (ctx.body && typeof ctx.body === 'object' && !Array.isArray(ctx.body) ? ctx.body : {});
+/** 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) {
+    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) {
+    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) {
+    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, database) {
+    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, id) => ctx.rowsRaw('Database').find((d) => d.database_id === id && !d._deleted_at && d._owner === emailOf(ctx));

package/dist/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/dist/api/src/semantics/teams.d.ts

@@ -0,0 +1,13 @@
+import type { Semantics, SemanticsContext } from '@volter/world-core';
+import { type Row } from './shared.js';
+/** The invitation mails the World's mail door shows. */
+export declare const MAIL = "_mail";
+/** A live team by id. */
+export declare const teamOf: (ctx: SemanticsContext, id: string) => Row | undefined;
+/** The team's members, pending ones included, never removed ones. */
+export declare const membersOf: (ctx: SemanticsContext, team: string) => Row[];
+/** The role a person holds in a team they have joined, or undefined. */
+export declare const roleOf: (ctx: SemanticsContext, team: string, email: string) => string | undefined;
+/** Remove a member or revoke a pending invitation (the API's delete-team-member; the Teams page's Revoke Invite). */
+export declare function removeMember(ctx: SemanticsContext, team: string, email: string, operation: string): Promise<string | undefined>;
+export declare const teamSemantics: Record<string, Semantics>;

package/dist/api/src/semantics/teams.js

@@ -0,0 +1,100 @@
+import { backingUp, badRequest, body, emailOf, forbidden, hex, live, ownFields, uuidOf } from "./shared.js";
+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, id) => 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, team) => 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, team, email) => membersOf(ctx, team).find((m) => m.member_email === email && m._pending !== true)?.member_role;
+const manages = (ctx, team, email) => ['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 = 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 = 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 = 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, team, email, operation) {
+    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 = 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 = 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 = { createTeam, moveToTeam, addTeamMember, deleteTeamMember, deleteTeam };

package/dist/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/dist/api/src/semantics/time.d.ts

@@ -0,0 +1,2 @@
+import type { SemanticsContext } from '@volter/world-core';
+export declare function catchUp(ctx: SemanticsContext): Promise<void>;

package/dist/api/src/semantics/time.js

@@ -0,0 +1,34 @@
+import { COMPLETE_AFTER_MS, DAILY_KEPT_MS, makeBackup } from "./backups.js";
+const DAY_MS = 86_400_000;
+const iso = (ms) => new Date(ms).toISOString();
+/** The first 00:00 UTC strictly after an instant. */
+const nextMidnight = (ms) => (Math.floor(ms / DAY_MS) + 1) * DAY_MS;
+export async function catchUp(ctx) {
+    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/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/qstash/src/doors.d.ts

@@ -0,0 +1,6 @@
+import type { DerivedOperation, SemanticsContext } from '@volter/world-core';
+import { type CatchUpReport } from './semantics/delivery.js';
+/** The operation a door's context is named by: no spec operation is. */
+export declare const DOOR: DerivedOperation;
+/** A door's answer, or undefined for a request that is not a door's. `report` is what the catch-up in front did. */
+export declare function door(ctx: SemanticsContext, request: Request, report: CatchUpReport): Promise<Response | undefined>;