@volter/twin-planetscale 0.1.0

package/dist/api/src/semantics/audit.ts

@@ -0,0 +1,82 @@
+// The organization's audit log. "The organization audit log grants Organization Administrators access to review actions
+// performed by individual members of the organization. In addition, each audit log includes events detailing who
+// performed the action and when it happened"; its table "Audited organization events" names each event and its actions
+// (https://planetscale.com/docs/security/audit-log). The lane records one event for each act of its operations and pages
+// that the table names: database created/deleted; database_branch created/deleted/enabled_safe_migrations/
+// disabled_safe_migrations; database_branch_password created/deleted; database_deploy_request created/closed;
+// deploy_request_review approved; backup_policy created; service_token created/deleted; user signed_in.
+//
+// Where the pages stop and the twin decides: an event's `audit_action` is `<event>.<action>` and its `action` the action;
+// the auditable is the organization (the database, for what happens inside one); the actor is the service token that
+// asked, the person on the page, or PlanetScale for what the World clock does; `location` and `remote_ip` are null (a
+// World has no network). The log keeps events for 15 days, the audit-log page's retention for the Base plan (the plans
+// page's table says 6 months; the twin follows the more specific page). list_audit_logs answers newest first, `limit`
+// events (at most 100, 25 by default): `starting_after` an event's id gives the events older than it, and `ending_before`
+// an event's id the `limit` events just newer than it (the next page toward the present); an id orders events even once
+// its own event has aged out of the log.
+import { createHash } from 'node:crypto';
+import type { SemanticsContext } from '@volter/world-core';
+
+type Row = Record<string, unknown>;
+const RETENTION_MS = 15 * 86_400_000;
+
+export type AuditActor = { type: 'ServiceToken' | 'User' | 'PlanetScale'; id: string; name: string };
+export type AuditObject = { type: string; id: string; name: string };
+
+/** The actor a call acts as: the service token its Authorization names, or the World's own token. */
+export function callActor(ctx: SemanticsContext): AuditActor {
+  const id = /^([^:\s]+):/.exec(ctx.call.request.headers.get('authorization') ?? '')?.[1];
+  const token = id === undefined ? undefined : ctx.rowsRaw('ServiceToken').find((t) => t.id === id);
+  return token ? { type: 'ServiceToken', id: String(token.id), name: String(token.display_name) } : { type: 'ServiceToken', id: id ?? 'service-token', name: 'Service token' };
+}
+export const SYSTEM: AuditActor = { type: 'PlanetScale', id: 'planetscale', name: 'PlanetScale' };
+export const personOf = (email: string, id: string): AuditActor => ({ type: 'User', id, name: email });
+/** A person's id, as a page names them in an actor (the twin's: a hash of their email). */
+export const createdById = (email: string): string => `u${createHash('sha256').update(email).digest('hex').slice(0, 12)}`;
+/** The actor for a person on a page. */
+export const personActorOf = (email: string): AuditActor => personOf(email, createdById(email));
+
+/** Record one event of the organization `org`. */
+export async function audit(ctx: SemanticsContext, org: string, event: string, action: string, target: AuditObject, o: { actor?: AuditActor; auditable?: AuditObject; metadata?: Row } = {}): Promise<void> {
+  const n = ctx.tree().filter((r) => r.type === '_audit_event').length + 1;
+  const id = `ale${String(n).padStart(8, '0')}`;
+  const actor = o.actor ?? callActor(ctx);
+  const auditable = o.auditable ?? { type: 'Organization', id: org, name: org };
+  await ctx.record('_audit_event', {
+    id, actor_id: actor.id, actor_type: actor.type, auditable_id: auditable.id, auditable_type: auditable.type,
+    target_id: target.id, target_type: target.type, location: null, target_display_name: target.name,
+    audit_action: `${event}.${action}`, action, actor_display_name: actor.name, auditable_display_name: auditable.name,
+    remote_ip: null, created_at: ctx.occurredAt, updated_at: ctx.occurredAt, metadata: o.metadata ?? null, _organization: org, _n: n,
+  }, id);
+}
+
+/** The organization a path names. */
+export const orgOf = (ctx: SemanticsContext): string => String(ctx.call.params.organization ?? '');
+
+/** list_audit_logs. */
+export async function listAuditLogs(ctx: SemanticsContext): Promise<Response> {
+  const org = orgOf(ctx);
+  const q = new URL(ctx.call.request.url).searchParams;
+  const limitRaw = q.get('limit');
+  const limit = limitRaw === null ? 25 : Number(limitRaw);
+  if (!Number.isInteger(limit) || limit < 1 || limit > 100) return ctx.refuse({ status: 422, code: 'unprocessable_entity', message: 'limit must be between 1 and 100' });
+  const since = Date.parse(ctx.occurredAt) - RETENTION_MS;
+  const events: Row[] = ctx.tree().filter((r) => r.type === '_audit_event').map((r): Row => ({ ...ctx.own(r), id: String(r.id) }))
+    .filter((e) => e._organization === org && Date.parse(String(e.created_at)) >= since)
+    .sort((a, b) => Number(b._n) - Number(a._n));
+  // a cursor is an event's id, which counts up, so it orders every event, kept or aged out of the log
+  const nOf = (id: string | null): number | undefined => (id && /^ale\d+$/.test(id) ? Number(id.slice(3)) : undefined);
+  const after = nOf(q.get('starting_after'));
+  const before = nOf(q.get('ending_before'));
+  if ((q.get('starting_after') && after === undefined) || (q.get('ending_before') && before === undefined)) return ctx.refuse({ status: 422, code: 'unprocessable_entity', message: 'starting_after and ending_before take an audit log id' });
+  let from = after === undefined ? 0 : events.findIndex((e) => Number(e._n) < after);
+  if (from < 0) from = events.length;
+  let to = events.length;
+  if (before !== undefined) { to = events.findIndex((e) => Number(e._n) <= before); if (to < 0) to = events.length; from = Math.max(from, to - limit); }
+  const slice = events.slice(from, Math.min(to, from + limit));
+  const data = slice.map(({ _organization: _o, _n: _k, ...e }) => e);
+  return ctx.reply({
+    type: 'list', has_next: from + slice.length < events.length, has_prev: from > 0,
+    cursor_start: data[0]?.id ?? null, cursor_end: data.at(-1)?.id ?? null, data,
+  });
+}

package/dist/api/src/semantics/backups.d.ts

@@ -0,0 +1,37 @@
+import { type SemanticsContext } from '@volter/world-core';
+type Row = Record<string, unknown>;
+export declare const UNITS: Record<string, number>;
+/** The actor PlanetScale's own scheduled backups carry (the twin's). */
+export declare const SCHEDULER: {
+    id: string;
+    display_name: string;
+    avatar_url: string;
+};
+/** The first time after `after` (ms) a policy runs. */
+export declare function nextRun(policy: Row, after: number): number;
+/** The Base plan's required system policy, made with each database. */
+export declare const makeDefaultPolicy: (ctx: SemanticsContext, database: string) => Promise<Row>;
+declare function createBackupPolicy(ctx: SemanticsContext): Promise<Response>;
+declare function listBackupPolicies(ctx: SemanticsContext): Promise<Response>;
+declare function getBackupPolicy(ctx: SemanticsContext): Promise<Response>;
+/** Each policy's backups that have fallen due, in the order they fell due across every policy, each made at the instant
+ *  it fell due. Nothing but a request writes a branch, so every backup this catch-up settles holds the branch as it
+ *  stands now: its image and size are read once per branch. Where that stops: a deploy the same catch-up carries into the
+ *  branch (semantics/deploy-requests.ts runs first) is held by a backup that fell due before it (the twin's limit). */
+export declare function catchUpPolicies(ctx: SemanticsContext): Promise<void>;
+/** The bytes of `main`'s stored rows (the World's image), what a backup of `main` holds. */
+export declare function mainBytes(ctx: SemanticsContext): number;
+/** How long after it is asked for a backup starts and completes (the twin's timing; semantics/time.ts runs it). */
+export declare const START_AFTER = 30000;
+export declare const COMPLETE_AFTER = 120000;
+/** What a completed backup holds: its branch's image, stored once per distinct image as a `_snapshot`. */
+export declare function snapshotBranch(ctx: SemanticsContext, backup: Row): Promise<{
+    id: string;
+    size: number;
+}>;
+export declare const backupPolicySemantics: {
+    create_backup_policy: typeof createBackupPolicy;
+    list_backup_policies: typeof listBackupPolicies;
+    get_backup_policy: typeof getBackupPolicy;
+};
+export {};

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

@@ -0,0 +1,264 @@
+// Backup policies, the backups the World clock makes, and what a completed backup holds.
+// "Our Base plan includes automated backups every 12 hours"; "You can add additional scheduled backups for your
+// branches"; "To restore a backup to a new branch" (https://planetscale.com/docs/vitess/backups). The spec's
+// create_backup_policy takes a name, a `target` (production or development branches), a retention and a frequency, a
+// `schedule_time` ("HH:MM"), a `schedule_day` ("0 is Sunday, 6 is Saturday") and a `schedule_week` ("0 is the first week,
+// 3 is the fourth week"); its BackupPolicy's `required` is "Whether the policy is a required system backup".
+//
+// Where the pages stop and the twin decides: the Base plan's backups are a required system policy each database is made
+// with ("Default schedule": production branches, every 12 hours at 00:00 and 12:00 UTC, kept 7 days: the pages give the
+// frequency and neither the hours nor the retention). A policy's backup falls at its schedule_time on the days its
+// frequency names (every N hours from schedule_time, every N days, on schedule_day every N weeks, or on schedule_day of
+// week schedule_week every N months, the week being days 1–7, 8–14, 15–21 or 22–28 of the month), for every ready branch
+// of its target, and runs as an asked-for backup does (semantics/time.ts). A completed backup holds its branch's schema
+// and rows (a `_snapshot`, one per distinct image), which a restore copies into a new branch; a backup whose retention
+// has passed is deleted on the World clock.
+import { createHash } from 'node:crypto';
+import { applyTwinWrite } from '@volter/world-core';
+import { scopeImage } from "../../../src/planetscale-store.js";
+import { branchScope, branchesOf } from "./branches.js";
+import { mintId, page } from "./shared.js";
+import { audit, orgOf } from "./audit.js";
+export const UNITS = { hour: 3_600_000, day: 86_400_000, week: 604_800_000, month: 2_592_000_000, year: 31_536_000_000 };
+const DAY = 86_400_000;
+const unprocessable = (ctx, message) => ctx.refuse({ status: 422, code: 'unprocessable_entity', message });
+const body = (ctx) => (ctx.body && typeof ctx.body === 'object' && !Array.isArray(ctx.body) ? ctx.body : {});
+/** The actor PlanetScale's own scheduled backups carry (the twin's). */
+export const SCHEDULER = { id: 'planetscale', display_name: 'PlanetScale', avatar_url: 'https://app.planetscale.com/gravatar-fallback.png' };
+/** The first time after `after` (ms) a policy runs. */
+export function nextRun(policy, after) {
+    return firstRun(policy, after) ?? noRunWithin();
+}
+function firstRun(policy, after) {
+    const start = Math.floor(after / DAY);
+    let hit;
+    Array.from({ length: 800 }, (_, k) => start + k).some((day) => (hit = runOn(policy, day, after)) !== undefined);
+    return hit;
+}
+/** The first time on `day` (days since 1970, UTC) after `after` that a policy runs, if it runs that day. */
+function runOn(policy, day, after) {
+    const [hh, mm] = String(policy.schedule_time ?? '00:00').split(':').map(Number);
+    const offset = (hh * 60 + mm) * 60_000;
+    const n = Math.max(1, Number(policy.frequency_value ?? 1));
+    const unit = String(policy.frequency_unit);
+    const created = Date.parse(String(policy.created_at));
+    const createdDay = Math.floor(created / DAY);
+    const d = new Date(day * DAY);
+    const times = [];
+    if (unit === 'hour') {
+        for (let t = offset % (n * 3_600_000); t < DAY; t += n * 3_600_000)
+            times.push(day * DAY + t);
+    }
+    else {
+        const ok = unit === 'day' ? (day - createdDay) % n === 0
+            : unit === 'week' ? d.getUTCDay() === Number(policy.schedule_day ?? 0) && Math.floor((day - createdDay) / 7) % n === 0
+                : unit === 'month' ? d.getUTCDay() === Number(policy.schedule_day ?? 0) && Math.floor((d.getUTCDate() - 1) / 7) === Number(policy.schedule_week ?? 0)
+                    && ((d.getUTCFullYear() - new Date(created).getUTCFullYear()) * 12 + d.getUTCMonth() - new Date(created).getUTCMonth()) % n === 0
+                    : false;
+        if (ok)
+            times.push(day * DAY + offset);
+    }
+    return times.find((t) => t > after && t >= created);
+}
+/** A policy none of whose runs falls within the next 800 days: it never runs in a World's span. */
+function noRunWithin() {
+    return Number.POSITIVE_INFINITY;
+}
+/** A policy as the spec's BackupPolicy answers it. */
+async function makePolicy(ctx, database, p) {
+    const id = mintId(ctx, 'BackupPolicy', 'bp', `${database}/${p.name}`);
+    const at = ctx.occurredAt;
+    const draft = { ...p, created_at: at };
+    const next = nextRun(draft, Date.parse(at));
+    return ctx.write('BackupPolicy', id, {
+        id, display_name: p.name, ...p, created_at: at, updated_at: at, last_ran_at: null,
+        next_run_at: Number.isFinite(next) ? new Date(next).toISOString() : null, _database: database,
+    }, 'backup_policy.create');
+}
+/** The Base plan's required system policy, made with each database. */
+export const makeDefaultPolicy = (ctx, database) => makePolicy(ctx, database, {
+    name: 'Default schedule', target: 'production', retention_value: 7, retention_unit: 'day', frequency_value: 12, frequency_unit: 'hour',
+    schedule_time: '00:00', schedule_day: 0, schedule_week: 0, required: true,
+});
+const policiesOf = (ctx, database) => ctx.rowsRaw('BackupPolicy').filter((p) => p._database === database && !p._deleted_at);
+const policyView = (ctx, p) => ctx.get('BackupPolicy', String(p.id));
+function createdDatabase(ctx) {
+    const name = String(ctx.call.params.database ?? '');
+    const db = ctx.rowsRaw('Database').find((d) => d.name === name && !d._deleted_at);
+    return db ? { db } : { refused: ctx.notFound('Database', name, 'database') };
+}
+async function createBackupPolicy(ctx) {
+    const { refused, db } = createdDatabase(ctx);
+    if (refused)
+        return refused;
+    const b = body(ctx);
+    const name = typeof b.name === 'string' && b.name ? b.name : '';
+    if (!name)
+        return unprocessable(ctx, 'name is required');
+    const target = String(b.target ?? 'production');
+    if (target !== 'production' && target !== 'development')
+        return unprocessable(ctx, 'target must be production or development');
+    const retentionUnit = String(b.retention_unit ?? '');
+    const frequencyUnit = String(b.frequency_unit ?? '');
+    if (!(retentionUnit in UNITS))
+        return unprocessable(ctx, 'retention_unit must be one of hour, day, week, month, year');
+    if (!['hour', 'day', 'week', 'month'].includes(frequencyUnit))
+        return unprocessable(ctx, 'frequency_unit must be one of hour, day, week, month');
+    const int = (v) => (Number.isInteger(v) ? Number(v) : undefined);
+    const retentionValue = int(b.retention_value);
+    const frequencyValue = int(b.frequency_value);
+    if (!retentionValue || retentionValue < 1 || !frequencyValue || frequencyValue < 1)
+        return unprocessable(ctx, 'retention_value and frequency_value must be whole numbers of at least 1');
+    const time = typeof b.schedule_time === 'string' ? b.schedule_time : '00:00';
+    if (!/^([01]\d|2[0-3]):[0-5]\d$/.test(time))
+        return unprocessable(ctx, 'schedule_time must be HH:MM');
+    const day = b.schedule_day === undefined ? null : int(b.schedule_day);
+    const week = b.schedule_week === undefined ? null : int(b.schedule_week);
+    if (day === undefined || (day !== null && (day < 0 || day > 6)))
+        return unprocessable(ctx, 'schedule_day must be 0 (Sunday) to 6 (Saturday)');
+    if (week === undefined || (week !== null && (week < 0 || week > 3)))
+        return unprocessable(ctx, 'schedule_week must be 0 to 3');
+    if ((frequencyUnit === 'week' || frequencyUnit === 'month') && day === null)
+        return unprocessable(ctx, 'schedule_day is required for a weekly or monthly policy');
+    if (frequencyUnit === 'month' && week === null)
+        return unprocessable(ctx, 'schedule_week is required for a monthly policy');
+    const record = await makePolicy(ctx, String(db.name), {
+        name, target, retention_value: retentionValue, retention_unit: retentionUnit, frequency_value: frequencyValue, frequency_unit: frequencyUnit,
+        schedule_time: time, schedule_day: day ?? 0, schedule_week: week ?? 0, required: false,
+    });
+    await audit(ctx, orgOf(ctx), 'backup_policy', 'created', { type: 'BackupPolicy', id: String(record.id), name }, { auditable: { type: 'Database', id: String(db.id), name: String(db.name) } });
+    return ctx.reply(policyView(ctx, record), 201);
+}
+async function listBackupPolicies(ctx) {
+    const { refused, db } = createdDatabase(ctx);
+    if (refused)
+        return refused;
+    return page(ctx, policiesOf(ctx, String(db.name)).map((p) => policyView(ctx, p)));
+}
+async function getBackupPolicy(ctx) {
+    const { refused, db } = createdDatabase(ctx);
+    if (refused)
+        return refused;
+    const p = policiesOf(ctx, String(db.name)).find((x) => x.id === ctx.call.params.id);
+    return p ? ctx.reply(policyView(ctx, p)) : ctx.notFound('BackupPolicy', String(ctx.call.params.id), 'id');
+}
+/** Each policy's backups that have fallen due, in the order they fell due across every policy, each made at the instant
+ *  it fell due. Nothing but a request writes a branch, so every backup this catch-up settles holds the branch as it
+ *  stands now: its image and size are read once per branch. Where that stops: a deploy the same catch-up carries into the
+ *  branch (semantics/deploy-requests.ts runs first) is held by a backup that fell due before it (the twin's limit). */
+export async function catchUpPolicies(ctx) {
+    const now = Date.parse(ctx.occurredAt);
+    const databases = new Set(ctx.rowsRaw('Database').filter((d) => !d._deleted_at).map((d) => String(d.name)));
+    const policies = ctx.rowsRaw('BackupPolicy').filter((p) => !p._deleted_at && databases.has(String(p._database)));
+    if (!policies.some((p) => typeof p.next_run_at === 'string' && Date.parse(p.next_run_at) <= now))
+        return;
+    const held = new Map();
+    const holding = async (at, database, branch) => {
+        const key = `${database}/${String(branch.name)}`;
+        if (!held.has(key)) {
+            const snap = await snapshotBranch(at, { _database: database, database_branch: { name: branch.name } });
+            held.set(key, branch.name === 'main' ? { id: snap.id, size: mainBytes(at) } : snap);
+        }
+        return held.get(key);
+    };
+    let n = ctx.rowsRaw('Backup', { withDeleted: true }).length;
+    // every backup and policy run this catch-up makes, written as one action (the pack's store writes a transaction's rows
+    // the same way): each keeps the instants it fell due, started, completed and expired in its own fields
+    const made = [];
+    let last = '';
+    const branches = new Map([...databases].map((d) => [d, branchesOf(ctx, d)]));
+    // each policy's last run is written once, at the instant of its last run
+    const ran = new Map();
+    for (;;) {
+        const due = policies.filter((p) => typeof p.next_run_at === 'string' && Date.parse(p.next_run_at) <= now)
+            .sort((a, b) => String(a.next_run_at).localeCompare(String(b.next_run_at)))[0];
+        if (!due)
+            break;
+        const when = String(due.next_run_at);
+        const at = await ctx.at(when);
+        const production = due.target === 'production';
+        for (const branch of branches.get(String(due._database)) ?? []) {
+            if (branch.production !== production || String(branch.created_at) > when)
+                continue;
+            // a branch is ready a minute after it is made (semantics/time.ts); one not ready yet at `when` is skipped
+            if (Date.parse(String(branch.created_at)) + 60_000 > Date.parse(when))
+                continue;
+            n += 1;
+            const backup = scheduledBackup(at, String(due._database), branch, due, n, now, await holding(at, String(due._database), branch));
+            if (backup)
+                made.push(backup);
+        }
+        const next = nextRun(due, Date.parse(when));
+        Object.assign(due, { last_ran_at: when, next_run_at: Number.isFinite(next) ? new Date(next).toISOString() : null, updated_at: when });
+        ran.set(String(due.id), { at, when });
+        last = when;
+    }
+    for (const p of policies)
+        if (ran.has(String(p.id)))
+            made.push({ type: '_backup_policy', id: String(p.id), fields: ctx.own(p) });
+    if (!made.length)
+        return;
+    const [subject, ...rest] = made;
+    await applyTwinWrite('planetscale', {
+        operation: 'backup_policy.run', subjectType: subject.type, subjectId: subject.id, fields: subject.fields,
+        projection: { updates: rest }, occurredAt: last, actor: { kind: 'system' },
+    }, ctx.root);
+}
+/**
+ * A backup a policy made at `ctx`'s instant. One the World clock has already carried past its run is caught up in the
+ * same write: it started and completed at the instants the lane's timers give (semantics/time.ts), each move asked of
+ * the machine, and, when its retention has also passed, it is deleted. One still running is left to semantics/time.ts.
+ */
+function scheduledBackup(ctx, database, branch, policy, n, now, holds) {
+    const at = ctx.occurredAt;
+    const id = `bk${createHash('sha256').update(`${at}:${database}/${String(branch.name)}:${String(policy.id)}:${n}`).digest('hex').slice(0, 12)}`;
+    const retention = Number(policy.retention_value) * UNITS[String(policy.retention_unit)];
+    const ref = { id: String(branch.id), name: String(branch.name), production: branch.production === true, created_at: String(branch.created_at), updated_at: String(branch.updated_at), deleted_at: null };
+    const { _database: _d, ...policyView } = ctx.own(policy);
+    const base = {
+        id, name: `backup-${n}`, state: 'pending', size: 0, estimated_storage_cost: 0,
+        created_at: at, updated_at: at, started_at: null, completed_at: null, expires_at: null, deleted_at: null,
+        pvc_size: 0, uncompressed_size: 0, protected: false, required: policy.required === true, restored_branches: [],
+        actor: SCHEDULER, backup_policy: policyView, schema_snapshot: null, database_branch: ref,
+        _database: database, _retention_ms: retention,
+    };
+    const completed = new Date(Date.parse(at) + COMPLETE_AFTER).toISOString();
+    if (Date.parse(completed) > now)
+        return { type: '_backup', id, fields: base };
+    if (ctx.legal('Backup', 'state', 'start', 'pending', 'running', id, 'time'))
+        return undefined;
+    if (ctx.legal('Backup', 'state', 'complete', 'running', 'success', id, 'time'))
+        return undefined;
+    const expires = new Date(Date.parse(completed) + retention).toISOString();
+    const gone = Date.parse(expires) <= now;
+    return { type: '_backup', id, fields: {
+            ...base, state: 'success', size: holds.size, pvc_size: holds.size, uncompressed_size: holds.size,
+            started_at: new Date(Date.parse(at) + START_AFTER).toISOString(), completed_at: completed, updated_at: gone ? expires : completed,
+            expires_at: expires, _snapshot: holds.id, ...(gone ? { deleted_at: expires } : {}),
+        } };
+}
+/** The bytes of `main`'s stored rows (the World's image), what a backup of `main` holds. */
+export function mainBytes(ctx) {
+    return ctx.tree().filter((r) => r.type === 'row' && r.deleted !== true).map((r) => ctx.own(r))
+        .filter((f) => f.gone !== true && f.deleted !== true).reduce((n, f) => n + Buffer.byteLength(JSON.stringify(f.cells ?? {})), 0);
+}
+/** How long after it is asked for a backup starts and completes (the twin's timing; semantics/time.ts runs it). */
+export const START_AFTER = 30_000;
+export const COMPLETE_AFTER = 120_000;
+/** What a completed backup holds: its branch's image, stored once per distinct image as a `_snapshot`. */
+export async function snapshotBranch(ctx, backup) {
+    const database = String(backup._database ?? '');
+    const branch = String(backup.database_branch?.name ?? 'main');
+    const image = scopeImage(ctx.root, database ? branchScope(database, branch) : undefined);
+    const text = JSON.stringify(image);
+    const id = `snapshot:${createHash('sha256').update(text).digest('hex').slice(0, 24)}`;
+    if (!ctx.tree().some((r) => r.type === '_snapshot' && r.id === id))
+        await ctx.record('_snapshot', { image }, id);
+    const size = image.rows.reduce((n, t) => n + t.rows.reduce((m, r) => m + Buffer.byteLength(JSON.stringify(r.cells)), 0), 0);
+    return { id, size };
+}
+export const backupPolicySemantics = {
+    create_backup_policy: createBackupPolicy,
+    list_backup_policies: listBackupPolicies,
+    get_backup_policy: getBackupPolicy,
+};

package/dist/api/src/semantics/backups.ts

@@ -0,0 +1,258 @@
+// Backup policies, the backups the World clock makes, and what a completed backup holds.
+// "Our Base plan includes automated backups every 12 hours"; "You can add additional scheduled backups for your
+// branches"; "To restore a backup to a new branch" (https://planetscale.com/docs/vitess/backups). The spec's
+// create_backup_policy takes a name, a `target` (production or development branches), a retention and a frequency, a
+// `schedule_time` ("HH:MM"), a `schedule_day` ("0 is Sunday, 6 is Saturday") and a `schedule_week` ("0 is the first week,
+// 3 is the fourth week"); its BackupPolicy's `required` is "Whether the policy is a required system backup".
+//
+// Where the pages stop and the twin decides: the Base plan's backups are a required system policy each database is made
+// with ("Default schedule": production branches, every 12 hours at 00:00 and 12:00 UTC, kept 7 days: the pages give the
+// frequency and neither the hours nor the retention). A policy's backup falls at its schedule_time on the days its
+// frequency names (every N hours from schedule_time, every N days, on schedule_day every N weeks, or on schedule_day of
+// week schedule_week every N months, the week being days 1–7, 8–14, 15–21 or 22–28 of the month), for every ready branch
+// of its target, and runs as an asked-for backup does (semantics/time.ts). A completed backup holds its branch's schema
+// and rows (a `_snapshot`, one per distinct image), which a restore copies into a new branch; a backup whose retention
+// has passed is deleted on the World clock.
+import { createHash } from 'node:crypto';
+import { applyTwinWrite, type ProjectedResource, type SemanticsContext } from '@volter/world-core';
+import { scopeImage, type ScopeImage } from '../../../src/planetscale-store.ts';
+import { branchScope, branchesOf } from './branches.ts';
+import { mintId, page } from './shared.ts';
+import { audit, orgOf } from './audit.ts';
+
+type Row = Record<string, unknown>;
+
+export const UNITS: Record<string, number> = { hour: 3_600_000, day: 86_400_000, week: 604_800_000, month: 2_592_000_000, year: 31_536_000_000 };
+const DAY = 86_400_000;
+const unprocessable = (ctx: SemanticsContext, message: string): Response => ctx.refuse({ status: 422, code: 'unprocessable_entity', message });
+const body = (ctx: SemanticsContext): Row => (ctx.body && typeof ctx.body === 'object' && !Array.isArray(ctx.body) ? (ctx.body as Row) : {});
+
+/** The actor PlanetScale's own scheduled backups carry (the twin's). */
+export const SCHEDULER = { id: 'planetscale', display_name: 'PlanetScale', avatar_url: 'https://app.planetscale.com/gravatar-fallback.png' };
+
+/** The first time after `after` (ms) a policy runs. */
+export function nextRun(policy: Row, after: number): number {
+  return firstRun(policy, after) ?? noRunWithin();
+}
+
+function firstRun(policy: Row, after: number): number | undefined {
+  const start = Math.floor(after / DAY);
+  let hit: number | undefined;
+  Array.from({ length: 800 }, (_, k) => start + k).some((day) => (hit = runOn(policy, day, after)) !== undefined);
+  return hit;
+}
+
+/** The first time on `day` (days since 1970, UTC) after `after` that a policy runs, if it runs that day. */
+function runOn(policy: Row, day: number, after: number): number | undefined {
+  const [hh, mm] = String(policy.schedule_time ?? '00:00').split(':').map(Number) as [number, number];
+  const offset = (hh * 60 + mm) * 60_000;
+  const n = Math.max(1, Number(policy.frequency_value ?? 1));
+  const unit = String(policy.frequency_unit);
+  const created = Date.parse(String(policy.created_at));
+  const createdDay = Math.floor(created / DAY);
+  const d = new Date(day * DAY);
+  const times: number[] = [];
+  if (unit === 'hour') {
+    for (let t = offset % (n * 3_600_000); t < DAY; t += n * 3_600_000) times.push(day * DAY + t);
+  } else {
+    const ok = unit === 'day' ? (day - createdDay) % n === 0
+      : unit === 'week' ? d.getUTCDay() === Number(policy.schedule_day ?? 0) && Math.floor((day - createdDay) / 7) % n === 0
+      : unit === 'month' ? d.getUTCDay() === Number(policy.schedule_day ?? 0) && Math.floor((d.getUTCDate() - 1) / 7) === Number(policy.schedule_week ?? 0)
+        && ((d.getUTCFullYear() - new Date(created).getUTCFullYear()) * 12 + d.getUTCMonth() - new Date(created).getUTCMonth()) % n === 0
+      : false;
+    if (ok) times.push(day * DAY + offset);
+  }
+  return times.find((t) => t > after && t >= created);
+}
+
+/** A policy none of whose runs falls within the next 800 days: it never runs in a World's span. */
+function noRunWithin(): number {
+  return Number.POSITIVE_INFINITY;
+}
+
+/** A policy as the spec's BackupPolicy answers it. */
+async function makePolicy(ctx: SemanticsContext, database: string, p: { name: string; target: string; retention_value: number; retention_unit: string; frequency_value: number; frequency_unit: string; schedule_time: string; schedule_day: number; schedule_week: number; required: boolean }): Promise<Row> {
+  const id = mintId(ctx, 'BackupPolicy', 'bp', `${database}/${p.name}`);
+  const at = ctx.occurredAt;
+  const draft = { ...p, created_at: at };
+  const next = nextRun(draft, Date.parse(at));
+  return ctx.write('BackupPolicy', id, {
+    id, display_name: p.name, ...p, created_at: at, updated_at: at, last_ran_at: null,
+    next_run_at: Number.isFinite(next) ? new Date(next).toISOString() : null, _database: database,
+  }, 'backup_policy.create');
+}
+
+/** The Base plan's required system policy, made with each database. */
+export const makeDefaultPolicy = (ctx: SemanticsContext, database: string): Promise<Row> => makePolicy(ctx, database, {
+  name: 'Default schedule', target: 'production', retention_value: 7, retention_unit: 'day', frequency_value: 12, frequency_unit: 'hour',
+  schedule_time: '00:00', schedule_day: 0, schedule_week: 0, required: true,
+});
+
+const policiesOf = (ctx: SemanticsContext, database: string): Row[] => ctx.rowsRaw('BackupPolicy').filter((p) => p._database === database && !p._deleted_at);
+const policyView = (ctx: SemanticsContext, p: Row): Row => ctx.get('BackupPolicy', String(p.id))!;
+
+function createdDatabase(ctx: SemanticsContext): { refused?: Response; db?: Row } {
+  const name = String(ctx.call.params.database ?? '');
+  const db = ctx.rowsRaw('Database').find((d) => d.name === name && !d._deleted_at);
+  return db ? { db } : { refused: ctx.notFound('Database', name, 'database') };
+}
+
+async function createBackupPolicy(ctx: SemanticsContext): Promise<Response> {
+  const { refused, db } = createdDatabase(ctx);
+  if (refused) return refused;
+  const b = body(ctx);
+  const name = typeof b.name === 'string' && b.name ? b.name : '';
+  if (!name) return unprocessable(ctx, 'name is required');
+  const target = String(b.target ?? 'production');
+  if (target !== 'production' && target !== 'development') return unprocessable(ctx, 'target must be production or development');
+  const retentionUnit = String(b.retention_unit ?? '');
+  const frequencyUnit = String(b.frequency_unit ?? '');
+  if (!(retentionUnit in UNITS)) return unprocessable(ctx, 'retention_unit must be one of hour, day, week, month, year');
+  if (!['hour', 'day', 'week', 'month'].includes(frequencyUnit)) return unprocessable(ctx, 'frequency_unit must be one of hour, day, week, month');
+  const int = (v: unknown): number | undefined => (Number.isInteger(v) ? Number(v) : undefined);
+  const retentionValue = int(b.retention_value);
+  const frequencyValue = int(b.frequency_value);
+  if (!retentionValue || retentionValue < 1 || !frequencyValue || frequencyValue < 1) return unprocessable(ctx, 'retention_value and frequency_value must be whole numbers of at least 1');
+  const time = typeof b.schedule_time === 'string' ? b.schedule_time : '00:00';
+  if (!/^([01]\d|2[0-3]):[0-5]\d$/.test(time)) return unprocessable(ctx, 'schedule_time must be HH:MM');
+  const day = b.schedule_day === undefined ? null : int(b.schedule_day);
+  const week = b.schedule_week === undefined ? null : int(b.schedule_week);
+  if (day === undefined || (day !== null && (day < 0 || day > 6))) return unprocessable(ctx, 'schedule_day must be 0 (Sunday) to 6 (Saturday)');
+  if (week === undefined || (week !== null && (week < 0 || week > 3))) return unprocessable(ctx, 'schedule_week must be 0 to 3');
+  if ((frequencyUnit === 'week' || frequencyUnit === 'month') && day === null) return unprocessable(ctx, 'schedule_day is required for a weekly or monthly policy');
+  if (frequencyUnit === 'month' && week === null) return unprocessable(ctx, 'schedule_week is required for a monthly policy');
+  const record = await makePolicy(ctx, String(db!.name), {
+    name, target, retention_value: retentionValue, retention_unit: retentionUnit, frequency_value: frequencyValue, frequency_unit: frequencyUnit,
+    schedule_time: time, schedule_day: day ?? 0, schedule_week: week ?? 0, required: false,
+  });
+  await audit(ctx, orgOf(ctx), 'backup_policy', 'created', { type: 'BackupPolicy', id: String(record.id), name }, { auditable: { type: 'Database', id: String(db!.id), name: String(db!.name) } });
+  return ctx.reply(policyView(ctx, record), 201);
+}
+
+async function listBackupPolicies(ctx: SemanticsContext): Promise<Response> {
+  const { refused, db } = createdDatabase(ctx);
+  if (refused) return refused;
+  return page(ctx, policiesOf(ctx, String(db!.name)).map((p) => policyView(ctx, p)));
+}
+
+async function getBackupPolicy(ctx: SemanticsContext): Promise<Response> {
+  const { refused, db } = createdDatabase(ctx);
+  if (refused) return refused;
+  const p = policiesOf(ctx, String(db!.name)).find((x) => x.id === ctx.call.params.id);
+  return p ? ctx.reply(policyView(ctx, p)) : ctx.notFound('BackupPolicy', String(ctx.call.params.id), 'id');
+}
+
+/** Each policy's backups that have fallen due, in the order they fell due across every policy, each made at the instant
+ *  it fell due. Nothing but a request writes a branch, so every backup this catch-up settles holds the branch as it
+ *  stands now: its image and size are read once per branch. Where that stops: a deploy the same catch-up carries into the
+ *  branch (semantics/deploy-requests.ts runs first) is held by a backup that fell due before it (the twin's limit). */
+export async function catchUpPolicies(ctx: SemanticsContext): Promise<void> {
+  const now = Date.parse(ctx.occurredAt);
+  const databases = new Set(ctx.rowsRaw('Database').filter((d) => !d._deleted_at).map((d) => String(d.name)));
+  const policies = ctx.rowsRaw('BackupPolicy').filter((p) => !p._deleted_at && databases.has(String(p._database)));
+  if (!policies.some((p) => typeof p.next_run_at === 'string' && Date.parse(p.next_run_at) <= now)) return;
+  const held = new Map<string, { id: string; size: number }>();
+  const holding = async (at: SemanticsContext, database: string, branch: Row): Promise<{ id: string; size: number }> => {
+    const key = `${database}/${String(branch.name)}`;
+    if (!held.has(key)) {
+      const snap = await snapshotBranch(at, { _database: database, database_branch: { name: branch.name } });
+      held.set(key, branch.name === 'main' ? { id: snap.id, size: mainBytes(at) } : snap);
+    }
+    return held.get(key)!;
+  };
+  let n = ctx.rowsRaw('Backup', { withDeleted: true }).length;
+  // every backup and policy run this catch-up makes, written as one action (the pack's store writes a transaction's rows
+  // the same way): each keeps the instants it fell due, started, completed and expired in its own fields
+  const made: ProjectedResource[] = [];
+  let last = '';
+  const branches = new Map([...databases].map((d) => [d, branchesOf(ctx, d)]));
+  // each policy's last run is written once, at the instant of its last run
+  const ran = new Map<string, { at: SemanticsContext; when: string }>();
+  for (;;) {
+    const due = policies.filter((p) => typeof p.next_run_at === 'string' && Date.parse(p.next_run_at) <= now)
+      .sort((a, b) => String(a.next_run_at).localeCompare(String(b.next_run_at)))[0];
+    if (!due) break;
+    const when = String(due.next_run_at);
+    const at = await ctx.at(when);
+    const production = due.target === 'production';
+    for (const branch of branches.get(String(due._database)) ?? []) {
+      if (branch.production !== production || String(branch.created_at) > when) continue;
+      // a branch is ready a minute after it is made (semantics/time.ts); one not ready yet at `when` is skipped
+      if (Date.parse(String(branch.created_at)) + 60_000 > Date.parse(when)) continue;
+      n += 1;
+      const backup = scheduledBackup(at, String(due._database), branch, due, n, now, await holding(at, String(due._database), branch));
+      if (backup) made.push(backup);
+    }
+    const next = nextRun(due, Date.parse(when));
+    Object.assign(due, { last_ran_at: when, next_run_at: Number.isFinite(next) ? new Date(next).toISOString() : null, updated_at: when });
+    ran.set(String(due.id), { at, when });
+    last = when;
+  }
+  for (const p of policies) if (ran.has(String(p.id))) made.push({ type: '_backup_policy', id: String(p.id), fields: ctx.own(p) as ProjectedResource['fields'] });
+  if (!made.length) return;
+  const [subject, ...rest] = made;
+  await applyTwinWrite('planetscale', {
+    operation: 'backup_policy.run', subjectType: subject!.type, subjectId: subject!.id, fields: subject!.fields,
+    projection: { updates: rest }, occurredAt: last, actor: { kind: 'system' },
+  }, ctx.root);
+}
+
+/**
+ * A backup a policy made at `ctx`'s instant. One the World clock has already carried past its run is caught up in the
+ * same write: it started and completed at the instants the lane's timers give (semantics/time.ts), each move asked of
+ * the machine, and, when its retention has also passed, it is deleted. One still running is left to semantics/time.ts.
+ */
+function scheduledBackup(ctx: SemanticsContext, database: string, branch: Row, policy: Row, n: number, now: number, holds: { id: string; size: number }): ProjectedResource | undefined {
+  const at = ctx.occurredAt;
+  const id = `bk${createHash('sha256').update(`${at}:${database}/${String(branch.name)}:${String(policy.id)}:${n}`).digest('hex').slice(0, 12)}`;
+  const retention = Number(policy.retention_value) * UNITS[String(policy.retention_unit)]!;
+  const ref = { id: String(branch.id), name: String(branch.name), production: branch.production === true, created_at: String(branch.created_at), updated_at: String(branch.updated_at), deleted_at: null };
+  const { _database: _d, ...policyView } = ctx.own(policy);
+  const base: Row = {
+    id, name: `backup-${n}`, state: 'pending', size: 0, estimated_storage_cost: 0,
+    created_at: at, updated_at: at, started_at: null, completed_at: null, expires_at: null, deleted_at: null,
+    pvc_size: 0, uncompressed_size: 0, protected: false, required: policy.required === true, restored_branches: [],
+    actor: SCHEDULER, backup_policy: policyView, schema_snapshot: null, database_branch: ref,
+    _database: database, _retention_ms: retention,
+  };
+  const completed = new Date(Date.parse(at) + COMPLETE_AFTER).toISOString();
+  if (Date.parse(completed) > now) return { type: '_backup', id, fields: base as ProjectedResource['fields'] };
+  if (ctx.legal('Backup', 'state', 'start', 'pending', 'running', id, 'time')) return undefined;
+  if (ctx.legal('Backup', 'state', 'complete', 'running', 'success', id, 'time')) return undefined;
+  const expires = new Date(Date.parse(completed) + retention).toISOString();
+  const gone = Date.parse(expires) <= now;
+  return { type: '_backup', id, fields: {
+    ...base, state: 'success', size: holds.size, pvc_size: holds.size, uncompressed_size: holds.size,
+    started_at: new Date(Date.parse(at) + START_AFTER).toISOString(), completed_at: completed, updated_at: gone ? expires : completed,
+    expires_at: expires, _snapshot: holds.id, ...(gone ? { deleted_at: expires } : {}),
+  } as ProjectedResource['fields'] };
+}
+
+/** The bytes of `main`'s stored rows (the World's image), what a backup of `main` holds. */
+export function mainBytes(ctx: SemanticsContext): number {
+  return ctx.tree().filter((r) => r.type === 'row' && r.deleted !== true).map((r) => ctx.own(r))
+    .filter((f) => f.gone !== true && f.deleted !== true).reduce((n, f) => n + Buffer.byteLength(JSON.stringify(f.cells ?? {})), 0);
+}
+
+/** How long after it is asked for a backup starts and completes (the twin's timing; semantics/time.ts runs it). */
+export const START_AFTER = 30_000;
+export const COMPLETE_AFTER = 120_000;
+
+/** What a completed backup holds: its branch's image, stored once per distinct image as a `_snapshot`. */
+export async function snapshotBranch(ctx: SemanticsContext, backup: Row): Promise<{ id: string; size: number }> {
+  const database = String(backup._database ?? '');
+  const branch = String((backup.database_branch as Row | undefined)?.name ?? 'main');
+  const image: ScopeImage = scopeImage(ctx.root, database ? branchScope(database, branch) : undefined);
+  const text = JSON.stringify(image);
+  const id = `snapshot:${createHash('sha256').update(text).digest('hex').slice(0, 24)}`;
+  if (!ctx.tree().some((r) => r.type === '_snapshot' && r.id === id)) await ctx.record('_snapshot', { image }, id);
+  const size = image.rows.reduce((n, t) => n + t.rows.reduce((m, r) => m + Buffer.byteLength(JSON.stringify(r.cells)), 0), 0);
+  return { id, size };
+}
+
+export const backupPolicySemantics = {
+  create_backup_policy: createBackupPolicy,
+  list_backup_policies: listBackupPolicies,
+  get_backup_policy: getBackupPolicy,
+};
+