@substrat-run/control-plane-api 0.49.0 → 0.50.0

package/dist/api.d.ts

@@ -6,6 +6,7 @@ import type { VerticalClient } from './vertical-client.js';
 import type { DeployVerticalFn, FetchVerticalModulesFn } from './deploy.js';
 import type { PatchScriptBindingsFn } from './wfp.js';
 import type { ObservabilityReader } from './observability.js';
+import type { DirectoryBackupStore, ScopeBackupStore } from './backups.js';
 import { type CustomHostnameProvisioner } from './custom-hostnames.js';
 export interface ControlPlaneApiOptions {
     host: ScopeHost;
@@ -109,6 +110,32 @@ export interface ControlPlaneApiOptions {
      * means forgetting that costs a feature, never a leak.
      */
     observability?: ObservabilityReader;
+    /**
+     * Where a reap's recoverable copy is stored (#493) — host-injected like
+     * `observability`, so this package holds no bucket binding. When present, reaping a
+     * scope writes a full-fidelity dump here FIRST and records its ref on the admin-log
+     * entry; a store that throws aborts the reap, because a wipe with no copy is exactly
+     * what the seam exists to prevent.
+     *
+     * Absent ⇒ a reap that did not explicitly ask for a backup proceeds without one (the
+     * self-host / embedded / test shape, where there is no platform bucket), and one that
+     * DID ask is refused 501 rather than silently reaping. That asymmetry is deliberate:
+     * the console always asks, so a control plane deployed with the binding missing fails
+     * loudly instead of quietly dropping the guarantee — the lesson `PLATFORM_BASE_DOMAINS`
+     * taught when it silently went unset.
+     */
+    scopeBackups?: ScopeBackupStore;
+    /**
+     * Where the platform's OWN copies live (#40) — the directory, not a tenant's scope.
+     * Host-injected on the same posture as `scopeBackups`, and pointable at the same
+     * bucket (the key prefixes keep the two apart) or at a different one.
+     *
+     * Absent ⇒ the directory backup routes answer 501 and the cron's backup phase is
+     * skipped. Loud, never silent: a control plane running with no directory copy is a
+     * platform one bug away from unrecoverable, and that must be visible rather than
+     * inferred from an absence of backups nobody looked for.
+     */
+    directoryBackups?: DirectoryBackupStore;
     /**
      * Issues + polls Cloudflare-for-SaaS custom hostnames (#305, §4.7) — host-injected
      * like `deployVertical`, so this package holds no Cloudflare credential (D-34). When

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AA+B5B,OAAO,KAAK,EAGV,eAAe,EAIhB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAGtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAe3D,OAAO,KAAK,EAAe,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACzF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAQtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAGL,KAAK,yBAAyB,EAC/B,MAAM,uBAAuB,CAAC;AAE/B,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,SAAS,CAAC;IAChB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC3C;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,KAAK,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IAChG;;;;;;;;;OASG;IACH,sBAAsB,CAAC,EAAE,CACvB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,eAAe,KACnB,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IACzC;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IACpF;;;;;OAKG;IACH,cAAc,CAAC,EAAE,gBAAgB,CAAC;IAClC;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,sBAAsB,CAAC;IAC9C;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,qBAAqB,CAAC;IAC5C;;;;;;;;OAQG;IACH,sBAAsB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C;;;;OAIG;IACH,YAAY,EAAE,iBAAiB,CAAC;IAChC;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,WAAW,CAAC;IAClC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,mBAAmB,CAAC;IACpC;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,yBAAyB,CAAC;IAC9C;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;CAChC;AAKD,KAAK,IAAI,GAAG;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,SAAS,EAAE,SAAS,CAAA;CAAE,CAAC;AA8M7D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAAE,SAAS,EAAE,IAAI,CAAA;CAAE,CAAC,CA8oFhG"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AA+B5B,OAAO,KAAK,EAGV,eAAe,EAMhB,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAGtD,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3E,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAe3D,OAAO,KAAK,EAAe,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACzF,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAC;AAQtD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,KAAK,EAEV,oBAAoB,EAEpB,gBAAgB,EACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAGL,KAAK,yBAAyB,EAC/B,MAAM,uBAAuB,CAAC;AAE/B,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,SAAS,CAAC;IAChB;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC;IAC3C;;;;;;OAMG;IACH,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,eAAe,KAAK,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IAChG;;;;;;;;;OASG;IACH,sBAAsB,CAAC,EAAE,CACvB,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,eAAe,KACnB,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IACzC;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;IACpF;;;;;OAKG;IACH,cAAc,CAAC,EAAE,gBAAgB,CAAC;IAClC;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,sBAAsB,CAAC;IAC9C;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,qBAAqB,CAAC;IAC5C;;;;;;;;OAQG;IACH,sBAAsB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC3C;;;;OAIG;IACH,YAAY,EAAE,iBAAiB,CAAC;IAChC;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,WAAW,CAAC;IAClC;;;;;OAKG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,mBAAmB,CAAC;IACpC;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,EAAE,gBAAgB,CAAC;IAChC;;;;;;;;;OASG;IACH,gBAAgB,CAAC,EAAE,oBAAoB,CAAC;IACxC;;;;;;;OAOG;IACH,iBAAiB,CAAC,EAAE,yBAAyB,CAAC;IAC9C;;;;;;OAMG;IACH,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;CAChC;AAKD,KAAK,IAAI,GAAG;IAAE,KAAK,EAAE,eAAe,CAAC;IAAC,SAAS,EAAE,SAAS,CAAA;CAAE,CAAC;AA0O7D;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,IAAI,CAAC;IAAE,SAAS,EAAE,IAAI,CAAA;CAAE,CAAC,CAu9FhG"}

package/dist/api.js

@@ -5,10 +5,11 @@ import { TENANT_HEADER } from './auth.js';
 import { ControlPlaneError } from './client.js';
 import { provisionSiblingScope } from './platform-drain.js';
 import { mapError } from './errors.js';
-import { maskDump } from './mask.js';
+import { maskDump, maskRecords } from './mask.js';
 import { assertSandboxContract, deployManifest, storedDeployManifest, deploymentRefFor, stableDeploymentRefFor, nextMigrationTag, upstreamStatusOf, } from './deploy.js';
 import { blobStoreBindings, collectBlobStoreHandles, collectTenantStoreHandles, tenantStoreBindings, } from './tenant-stores.js';
 import { mintPushToken, pushActorFor } from './push-token.js';
+import { backupDirectoryIfDue } from './directory-backup.js';
 import { isCustomHostname, validateBindableHostname, } from './custom-hostnames.js';
 // -- request schemas ---------------------------------------------------------
 // Parse, don't trust: every input crosses Zod at the boundary. The ids stay
@@ -142,6 +143,31 @@ const snapshotScopeBody = z.object({
     kind: z.string().min(1).optional(),
     expiresAt: z.string().datetime({ offset: true }).optional(),
 });
+// A reap request (#493). `backup` is deliberately TRI-STATE, not a defaulted boolean:
+//   true      — back up or refuse (the console always sends this, so a control plane
+//               deployed without a backup store fails loudly instead of quietly wiping)
+//   false     — the explicit "I accept an unrecoverable wipe"
+//   undefined — back up if a store is configured, proceed without one if not, which is
+//               what keeps every pre-#493 caller (and self-host) working unchanged
+const reapScopeBody = z.object({
+    backup: z.boolean().optional(),
+});
+// A directory-restore request (#40). `capturedAt` addresses the copy — there is one
+// directory, so that is its whole address. `overwrite` is the guard against the
+// dangerous case: replaying a restore onto a control plane that already recovered.
+const restoreDirectoryBody = z.object({
+    capturedAt: z.string().min(1),
+    overwrite: z.boolean().optional(),
+});
+/**
+ * How a stored backup is named in the admin log and to callers: the route that fetches
+ * it. Store-neutral by construction — the R2 key scheme stays private to the store — and
+ * an operator reading a reap entry gets an address they can actually GET, rather than a
+ * bucket path they would have to know the platform's internals to use.
+ */
+function backupRefOf(b) {
+    return `/tenants/${b.tenantId}/scopes/${b.scopeId}/backups/${b.capturedAt}`;
+}
 // A per-PR preview request (preview-and-snapshots.md §2/§9 — the "run a new version
 // against a fork of prod" slice). `tag` is a short DNS-safe label (`pr-123`): it names
 // the preview both in its scope slug (`<vertical>--<tag>`) and in its hostname
@@ -391,6 +417,7 @@ export function createControlPlaneApi(options) {
     app.post('/tenants/:tenantId/reap', async (c) => {
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
         const actor = c.get('actor');
+        const { backup: wantsBackup } = reapScopeBody.parse(await c.req.json().catch(() => ({})));
         const tenant = await admin.getTenant(actor, tenantId);
         if (!tenant)
             return c.json({ error: `unknown tenant: ${tenantId}` }, 404);
@@ -405,12 +432,22 @@ export function createControlPlaneApi(options) {
                     continue;
                 if (scope.status !== 'archived')
                     await admin.archiveScope(actor, tenantId, scope.id);
+                // A backup here is OPT-IN, the inverse of the per-scope reap's default (#493).
+                // A scope reap is operational cleanup, so leaving a copy is the safe default; a
+                // TENANT reap is the deletion of a customer, and §4.8 exists partly to serve an
+                // Art. 17 erasure — silently writing that customer's data to a bucket the reap
+                // does not clear would defeat the request it was made to satisfy. Staff who are
+                // retiring (not erasing) a tenant pass `backup: true` deliberately.
+                const backup = wantsBackup === true ? await backupScope(c, tenantId, scope) : null;
                 const vertical = await verticalForScope(c, scope);
                 if (vertical)
                     await vertical.deleteScope({ scopeId: scope.id });
                 // Tenant teardown reaps every scope and releases every name by design — force past
                 // the bound-hostname guard (which fences the interactive per-scope reap route below).
-                await admin.reapScope(actor, tenantId, scope.id, { force: true });
+                await admin.reapScope(actor, tenantId, scope.id, {
+                    force: true,
+                    ...(backup ? { backupRef: backupRefOf(backup) } : {}),
+                });
             }
             await admin.reapTenant(actor, tenantId);
             return c.json(await admin.getTenant(actor, tenantId));
@@ -1051,6 +1088,154 @@ export function createControlPlaneApi(options) {
             throw e;
         }
     });
+    // -- backups (#493) --------------------------------------------------------
+    // The recoverable copy a reap leaves behind. Delegation mirrors the export route
+    // exactly: `admin.exportScope` is the canonical call — it writes the K-24 access-log
+    // entry, and IS the bytes when the host is co-located — and a vertical-held scope's
+    // real tables overlay it. FULL fidelity, never masked: a masked dump cannot restore,
+    // and a backup that cannot restore is a false promise (see `backups.ts`).
+    const backupScope = async (c, tenantId, scope) => {
+        const store = options.scopeBackups;
+        if (!store) {
+            throw new ControlPlaneError(501, 'no backup target configured — this control plane cannot store a scope backup ' +
+                '(bind one, or reap with backup=false to accept an unrecoverable wipe)');
+        }
+        // Residency (K-7/K-32): the platform bucket is global, so writing a jurisdiction-
+        // pinned scope's bytes into it would move them out of the region the scope was
+        // promised. Refuse rather than back up to the wrong place — and, because the reap
+        // aborts with it, rather than wipe a scope we cannot legally copy.
+        if (scope.jurisdiction !== 'global') {
+            throw new ControlPlaneError(409, `scope ${scope.id} is pinned to '${scope.jurisdiction}' — the platform backup ` +
+                `store is global, so a backup would move its data out of that jurisdiction ` +
+                `(K-32); refused until a per-jurisdiction store exists`);
+        }
+        const dump = await admin.exportScope(c.get('actor'), tenantId, scope.id);
+        const vertical = await verticalForScope(c, scope);
+        const tables = vertical ? await vertical.exportScope(scope.id) : dump.tables;
+        return store.put({ vertical: scope.vertical, dump: { ...dump, tables } });
+    };
+    // The copies held for one scope — metadata only, so listing a reaped scope's backups
+    // is cheap and hands out no bytes. Readable AFTER the reap (that is the point): the
+    // directory row survives as a tombstone, and this is what tells the operator a
+    // recoverable copy exists and when it was taken.
+    app.get('/tenants/:tenantId/scopes/:scopeId/backups', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
+        if (!options.scopeBackups)
+            return c.json({ error: 'no backup target configured' }, 501);
+        // Reads the directory, not the store, for the tenant cross-check: the store is keyed
+        // by (tenant, scope) but nothing there proves the caller's tenant owns the scope.
+        const scope = await admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
+        if (!scope)
+            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+        return c.json(await options.scopeBackups.list({ tenantId, scopeId }));
+    });
+    // One backup's DUMP — the restore source. Staff-only like the export it came from
+    // (not in BUILDER_ROUTES), and full-fidelity, so it is the same governed-pull posture:
+    // K-3 cross-checked above, and `POST …/restore` is where it goes back.
+    app.get('/tenants/:tenantId/scopes/:scopeId/backups/:capturedAt', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
+        const capturedAt = c.req.param('capturedAt');
+        if (!options.scopeBackups)
+            return c.json({ error: 'no backup target configured' }, 501);
+        const scope = await admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
+        if (!scope)
+            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+        const dump = await options.scopeBackups.get({ tenantId, scopeId, capturedAt });
+        if (!dump)
+            return c.json({ error: `no backup for scope ${scopeId} at ${capturedAt}` }, 404);
+        return c.json(dump);
+    });
+    // Take a backup WITHOUT reaping — the standalone copy (a pre-migration checkpoint, an
+    // export-to-keep). The reap route below takes its own; this is the same act made
+    // available on its own, so "back up" is not something only a destructive path can do.
+    app.post('/tenants/:tenantId/scopes/:scopeId/backups', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
+        const scope = await admin.getScopeRecord(c.get('actor'), tenantId, scopeId);
+        if (!scope)
+            return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
+        try {
+            return c.json(await backupScope(c, tenantId, scope), 201);
+        }
+        catch (e) {
+            if (e instanceof ControlPlaneError) {
+                return c.json({ error: e.message }, e.status);
+            }
+            throw e;
+        }
+    });
+    // -- directory backups (#40) -----------------------------------------------
+    // The platform's own disaster recovery, on the same store posture as the scope
+    // backups above and deliberately on a different axis from them: a scope has ~30-day
+    // point-in-time recovery, the directory has one Durable Object and no second copy of
+    // the mapping that makes every scope addressable. These routes are the manual arms of
+    // the cron phase (`backupDirectoryIfDue`) — take one now, see what is held, and the
+    // break-glass restore. Staff-only: none is in BUILDER_ROUTES, and none is per-tenant,
+    // because the subject of all three is every tenant at once.
+    // What copies exist, newest first — metadata only, so this is cheap and hands out no
+    // bytes. This is also the answer to "is the backup actually running?", which is the
+    // question an unrehearsed backup story never has a way to ask.
+    app.get('/directory/backups', async (c) => {
+        if (!options.directoryBackups)
+            return c.json({ error: 'no directory backup target configured' }, 501);
+        return c.json(await options.directoryBackups.list());
+    });
+    // Take one NOW, cadence ignored — the pre-migration checkpoint an operator takes by
+    // hand before touching the directory, and the way a fresh deployment gets its first
+    // copy without waiting a day for the cron.
+    app.post('/directory/backups', async (c) => {
+        if (!options.directoryBackups)
+            return c.json({ error: 'no directory backup target configured' }, 501);
+        const result = await backupDirectoryIfDue({
+            admin,
+            store: options.directoryBackups,
+            actor: c.get('actor'),
+            force: true,
+        });
+        return c.json(result.taken, 201);
+    });
+    // One copy's DUMP — the restore source, and the off-platform escape hatch: an operator
+    // who wants the directory on their own disk GETs this. The most privileged read the
+    // control plane offers (every tenant, every hostname, every identity), so staff-only
+    // and audited by `exportDirectory` underneath.
+    app.get('/directory/backups/:capturedAt', async (c) => {
+        if (!options.directoryBackups)
+            return c.json({ error: 'no directory backup target configured' }, 501);
+        const capturedAt = c.req.param('capturedAt');
+        const dump = await options.directoryBackups.get({ capturedAt });
+        if (!dump)
+            return c.json({ error: `no directory backup at ${capturedAt}` }, 404);
+        return c.json(dump);
+    });
+    // Break-glass: REPLACE the directory with a stored copy.
+    //
+    // Guarded by an explicit `overwrite` rather than a confirmation string, because the
+    // dangerous case is not a slip of the fingers — it is a well-formed retry against a
+    // control plane that has already recovered, which would silently roll the platform
+    // back to the copy's moment and lose every tenant created since. So a directory that
+    // still holds tenants refuses (409) unless the caller says, in the body, that
+    // replacing them is the intent. An EMPTY directory — the actual disaster, a fresh DO
+    // with nothing in it — needs no such ceremony.
+    app.post('/directory/restore', async (c) => {
+        if (!options.directoryBackups)
+            return c.json({ error: 'no directory backup target configured' }, 501);
+        const body = restoreDirectoryBody.parse(await c.req.json().catch(() => ({})));
+        const dump = await options.directoryBackups.get({ capturedAt: body.capturedAt });
+        if (!dump)
+            return c.json({ error: `no directory backup at ${body.capturedAt}` }, 404);
+        const actor = c.get('actor');
+        const live = await admin.listTenants(actor, { limit: 1 });
+        if (live.length > 0 && !body.overwrite) {
+            return c.json({
+                error: 'the directory is not empty — a restore REPLACES it, so anything created ' +
+                    'since this copy was taken would be lost; pass overwrite=true to confirm',
+            }, 409);
+        }
+        await admin.restoreDirectory(actor, dump);
+        return c.json({ capturedAt: dump.capturedAt, tables: dump.tables.length });
+    });
     // Reap an ARCHIVED primary scope (control-plane.md §4.4): free its DO storage —
     // Cloudflare never garbage-collects a Durable Object, so a deleted app's bytes persist
     // forever otherwise — while keeping the directory row as a tombstone. A POST verb, not
@@ -1064,6 +1249,9 @@ export function createControlPlaneApi(options) {
         const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
         const scopeId = scopeIdSchema.parse(c.req.param('scopeId'));
         const actor = c.get('actor');
+        // Body is optional so the bare `POST …/reap` every existing caller sends still
+        // parses; `backup` tri-states on purpose (see the ordering comment below).
+        const { backup: wantsBackup } = reapScopeBody.parse(await c.req.json().catch(() => ({})));
         const scope = await admin.getScopeRecord(actor, tenantId, scopeId);
         if (!scope)
             return c.json({ error: `unknown scope for tenant: (${tenantId}, ${scopeId})` }, 404);
@@ -1082,12 +1270,41 @@ export function createControlPlaneApi(options) {
                     `unbind it before reaping (reap wipes storage and cannot be undone)`,
             }, 409);
         }
+        // The recoverable copy, BEFORE any byte is wiped (#493). Ordering is the whole
+        // guarantee: `backupScope` has to have resolved — durably stored — before
+        // `deleteScope` runs, so a store that throws (or is missing when one was asked for)
+        // aborts the reap with the scope intact. `backup: false` is the explicit "I accept an
+        // unrecoverable wipe"; omitting it backs up when a store is configured and proceeds
+        // without one when the platform has none.
+        //
+        // Its own try/catch, OUTSIDE the reap's: a backup failure and a reap failure are
+        // different facts to an operator, and collapsing a dead bucket into the generic 500
+        // would read as "the reap broke" when the scope is in fact untouched (#321's lesson).
+        let backup = null;
+        if (!(wantsBackup === false || (wantsBackup === undefined && !options.scopeBackups))) {
+            try {
+                backup = await backupScope(c, tenantId, scope);
+            }
+            catch (e) {
+                if (e instanceof ControlPlaneError) {
+                    return c.json({ error: e.message }, e.status);
+                }
+                return c.json({
+                    error: 'backup failed — the scope was NOT reaped and its data is intact; ' +
+                        'retry, or reap with backup=false to accept an unrecoverable wipe',
+                    detail: e instanceof Error ? e.message : String(e),
+                }, 502);
+            }
+        }
         try {
             const vertical = await verticalForScope(c, scope);
             if (vertical)
                 await vertical.deleteScope({ scopeId });
-            await admin.reapScope(actor, tenantId, scopeId);
-            return c.json(await admin.getScopeRecord(actor, tenantId, scopeId));
+            await admin.reapScope(actor, tenantId, scopeId, {
+                ...(backup ? { backupRef: backupRefOf(backup) } : {}),
+            });
+            const reaped = await admin.getScopeRecord(actor, tenantId, scopeId);
+            return c.json({ ...reaped, backup });
         }
         catch (e) {
             if (e instanceof ControlPlaneError) {
@@ -1136,6 +1353,117 @@ export function createControlPlaneApi(options) {
             throw e;
         }
     });
+    // -- tenant export (#36) ----------------------------------------------------
+    //
+    // GDPR Art. 20 portability, and the escrow handover: one tenant, whole, in one file.
+    //
+    // Composed ENTIRELY from the sanctioned reads above — `listScopes`, `listOrgs`,
+    // `listMembers`, `listRoles`, `listEntitlements`, `listIdentityLinks`,
+    // `listHostnames`, the store ledgers, `listConnections`, `exportScope`. That is the
+    // constraint the design puts on this route, not an implementation preference:
+    // control-plane.md §7 says the control plane must not acquire a back door into scope
+    // databases, and the only sanctioned path is the audited admin surface. An export
+    // that reached past it would BE the back door — and every read here is already
+    // K-24 access-logged, so the trail is a property of the parts.
+    //
+    // It is deliberately NOT the same shape as a directory dump (#40): that one is raw
+    // tables for recovery, this one is the platform's documented vocabulary for a reader
+    // who does not know the schema. Only the per-scope `data` is raw, because that is the
+    // half that has to be reloadable.
+    app.get('/tenants/:tenantId/export', async (c) => {
+        const tenantId = tenantIdSchema.parse(c.req.param('tenantId'));
+        const actor = c.get('actor');
+        const tenant = await admin.getTenant(actor, tenantId);
+        if (!tenant)
+            return c.json({ error: `unknown tenant: ${tenantId}` }, 404);
+        // Every scope, tombstones included: an archived or reaped scope is part of the
+        // tenant's history, and an export that quietly dropped them would misrepresent what
+        // the tenant was. Their DATA is a different question, handled below.
+        const scopes = await admin.listScopes(actor, { tenantId });
+        // Residency (K-7/K-32), checked across the WHOLE tenant before anything is read: an
+        // export lands on a machine outside the platform's control, so one pinned scope
+        // taints the file. Refused as a unit rather than silently exporting the global
+        // scopes and omitting the pinned ones — a partial export that does not say it is
+        // partial is the failure mode worth avoiding.
+        const pinned = scopes.filter((s) => s.jurisdiction !== 'global');
+        if (pinned.length > 0) {
+            return c.json({
+                error: `tenant ${tenantId} has ${pinned.length} scope(s) pinned to a jurisdiction ` +
+                    `(${[...new Set(pinned.map((s) => s.jurisdiction))].join(', ')}) — an export would ` +
+                    `move that data out of the region it was promised; refused (K-32). Export the ` +
+                    `global scopes individually, or wait for a per-jurisdiction path.`,
+            }, 403);
+        }
+        const full = c.req.query('full') === 'true';
+        try {
+            const orgs = await admin.listOrgs(actor, tenantId);
+            // Revoked memberships included: K-21 makes a removal a tombstone precisely because
+            // "was a member until March" is the fact an audit asks for.
+            const members = (await Promise.all(orgs.map((o) => admin.listMembers(actor, tenantId, o.id, { includeRevoked: true })))).flat();
+            const [roles, entitlements, identityLinks, hostnames, stores, blobStores, connections] = await Promise.all([
+                admin.listRoles(actor, { tenantId }),
+                admin.listEntitlements(actor, tenantId),
+                admin.listIdentityLinks(actor, tenantId),
+                admin.listHostnames(actor, { tenantId }),
+                admin.listTenantStores(actor, { tenantId }),
+                admin.listBlobStores(actor, { tenantId }),
+                admin.listConnections(actor, { tenantId }),
+            ]);
+            // Scope DATA, from the same delegation the per-scope export route uses: the
+            // canonical `exportScope` writes the audit entry and is the bytes when co-located;
+            // a vertical-held scope's real tables overlay it. A reaped scope has no storage
+            // left to read, so it is skipped here while its RECORD stays above — the tombstone
+            // is honest, an error would not be.
+            const live = scopes.filter((s) => s.status !== 'reaped');
+            const data = [];
+            for (const scope of live) {
+                const dump = await admin.exportScope(actor, tenantId, scope.id);
+                const vertical = await verticalForScope(c, scope);
+                const tables = vertical ? await vertical.exportScope(scope.id) : dump.tables;
+                data.push({ ...dump, tables: full ? tables : maskDump(tables) });
+            }
+            // The admin log is FULL-only (#36): it records what STAFF did, so it is not the
+            // customer's Art. 20 data, and it carries staff actor ids and internal action
+            // names. An escrow or a dispute needs it, which is why break-glass reaches it
+            // rather than nothing reaching it.
+            const adminLog = full ? await admin.auditLog(actor, { tenantId }) : null;
+            const body = {
+                tenantId,
+                capturedAt: new Date().toISOString(),
+                masked: !full,
+                tenant: full ? tenant : maskRecords([tenant])[0],
+                scopes: full ? scopes : maskRecords(scopes),
+                orgs: full ? orgs : maskRecords(orgs),
+                members: full ? members : maskRecords(members),
+                // Roles, entitlements and hostnames are configuration rather than personal data,
+                // so they read the same in both fidelities — but they still go through the sweep,
+                // because deciding per-collection what "cannot contain PII" means is exactly the
+                // assumption that ages badly. One rule, applied everywhere.
+                roles: full ? roles : maskRecords(roles),
+                entitlements: full ? entitlements : maskRecords(entitlements),
+                // Identity links are the sharpest item here: `externalId` is usually an email.
+                identityLinks: full ? identityLinks : maskRecords(identityLinks),
+                hostnames: full ? hostnames : maskRecords(hostnames),
+                stores: [...stores, ...blobStores].map((s) => ({
+                    kind: s.kind,
+                    vertical: s.vertical,
+                    binding: s.binding,
+                    ref: s.ref,
+                    createdAt: s.createdAt,
+                })),
+                connections: full ? connections : maskRecords(connections),
+                adminLog,
+                data,
+            };
+            return c.json(body);
+        }
+        catch (e) {
+            if (e instanceof ControlPlaneError) {
+                return c.json({ error: e.message }, e.status);
+            }
+            throw e;
+        }
+    });
     // The write half of the governed pull (§8) — load a dump INTO an existing scope:
     // restore a backup, back out to a snapshot, or land a locally-built world on a
     // hosted app. Staff-only like the export (not in BUILDER_ROUTES). No jurisdiction