@ziprack/sdk 0.2.1 → 0.3.0

package/dist/auth/index.d.ts

@@ -4,6 +4,8 @@ import type { LaunchUser } from '../core/types';
  * auth@1 — who the participant is and the profile attributes the Rack chose to
  * release. Attributes the manifest requested but the Rack withheld are simply
  * absent; degrade gracefully.
+ *
+ * Roles need no capability: every launch carries them.
  */
 export declare class AuthApi {
     private readonly link;
@@ -11,4 +13,13 @@ export declare class AuthApi {
     user(): LaunchUser | null;
     /** A released profile attribute, or the fallback when withheld. */
     attribute<T = unknown>(key: string, fallback?: T | null): T | null;
+    /**
+     * The roles the participant holds: `member` or `guest`, `applet-author` and
+     * `rack-administrator` when they apply, and the manifest's own roles the
+     * Rack gives them. Read at launch; a change applies from the next launch.
+     */
+    roles(): string[];
+    hasRole(role: string): boolean;
+    /** Whether the participant is a guest rather than a signed-in Rack user. */
+    isGuest(): boolean;
 }

package/dist/core/mock/MockRack.d.ts

@@ -45,6 +45,12 @@ export interface MockManifest {
         channels?: string[];
         mock_mode?: 'first_in' | 'opt_in';
     };
+    roles?: Array<{
+        name: string;
+        label?: string;
+        description?: string;
+        grant?: 'everyone' | 'members' | 'guests' | 'assigned';
+    }>;
     [key: string]: unknown;
 }
 export type AiMockHandler = (vars: JsonObject, mode: 'analysis' | 'chat', message?: string) => unknown | Promise<unknown>;
@@ -56,6 +62,10 @@ export interface MockRackOptions {
     participantName?: string;
     /** Force the mock room role instead of deriving it from the assignment mode. */
     role?: RoomRole;
+    /** Launch as a guest: `guest` instead of `member`, and the guest grants. */
+    guest?: boolean;
+    /** Roles to hold on top of the grants, as if the Rack had assigned them (any name, built-in ones included). */
+    roles?: string[];
 }
 export type MockOutcome = AckResult | {
     stream: AsyncIterable<JsonObject>;
@@ -93,6 +103,11 @@ export declare class MockRack {
     onEvent(listener: (event: RackEvent) => void): () => void;
     pushEvent(event: RackEvent): void;
     launchData(nameHint?: string): LaunchData;
+    /**
+     * What a Rack would resolve: member or guest, the manifest's grants, and
+     * any roles the options say were assigned.
+     */
+    roles(): string[];
     mockAi(promptId: string, handler: AiMockHandler): void;
     dispose(): void;
     handle(type: string, payload: JsonObject): Promise<MockOutcome>;

package/dist/core/rack.d.ts

@@ -66,3 +66,12 @@ export declare class RackClient {
     private flushQueue;
     private mockRack;
 }
+/**
+ * Mock-mode identity from the page URL, so an author can try each role:
+ * `?ziprack-roles=dungeon-master,applet-author` adds assigned roles and
+ * `?ziprack-guest` launches as a guest.
+ */
+export declare function mockIdentityFromUrl(search?: string): {
+    roles?: string[];
+    guest?: boolean;
+};

package/dist/core/types.d.ts

@@ -86,8 +86,15 @@ export interface LaunchData {
     applet: LaunchApplet;
     capabilities: string[];
     media: Record<string, MediaEmbed>;
+    /**
+     * The roles the participant holds in this applet: `member` or `guest`,
+     * `applet-author` and `rack-administrator` when they apply, plus the
+     * manifest's own roles the Rack gives them. Absent on Racks before v1.8.
+     */
+    roles?: string[];
     auth?: {
         user: LaunchUser;
+        withheld?: string[];
     };
     attempt?: LaunchAttempt;
     activity?: {

package/dist/docs/README.md

@@ -24,10 +24,10 @@ These docs cover both halves. If you are building an applet, start with
 
 ## Capabilities
 
-- [Authentication](auth.md) — `auth@1`
+- [Authentication](auth.md) — `auth@1`, and roles
 - [Attempts](attempts.md) — `attempt@1`
 - [Activity](activity.md) — `activity@1`
-- [Database](database.md) — `db@1`
+- [Database](database.md) — `db@1`, data across versions, migrations, snapshots
 - [Storage](storage.md) — `storage@1`
 - [AI](ai.md) — `ai@1`
 - [Broadcast](broadcast.md) — `broadcast@1`
@@ -37,7 +37,7 @@ These docs cover both halves. If you are building an applet, start with
 
 - [Installation](installation.md) — composing a Rack from capability packages
 - [Security](security.md) — the sandbox, the CSP, the threats it does not cover
-- [Publishing](publishing.md) — install, capability diff, review queue, promotion, kill switch
+- [Publishing](publishing.md) — install, capability diff, review queue, promotion and the data cutover, kill switch
 - [Reporting](reporting.md) — the admin API, CSV export, metrics
 - [Who may do what](reporting.md#who-may-do-what) — `AppletAccess`, abilities, applet owners
 - [Conformance](conformance.md) — proving a deployment is still a Rack

package/dist/docs/applet-packages.md

@@ -17,10 +17,16 @@ An applet ships as a single zip, named for the applet and the version it contain
 ├── manifest.json        required, at the zip root
 ├── sbom.json            required — CycloneDX, or package-lock.json
 ├── index.html           the entry (configurable via manifest.entry)
+├── migrations/…         optional — data migrations, one ES module per file
 └── assets/…             everything the entry references, by RELATIVE path
 ```
 
-Nothing else is special. The Rack extracts the archive, keeps the file tree intact, and serves it
+`migrations/` is the one other directory the Rack reads: the [data migrations](database.md#data-migrations)
+that reshape existing records when the version is promoted. Its files are ordinary `.js` or `.mjs`
+files to the installer, named `YYYY_MM_DD_HHMMSS_name.js` and sitting directly inside it; any other
+name there refuses the package.
+
+Apart from those, nothing is special. The Rack extracts the archive, keeps the file tree intact, and serves it
 through a token-prefixed path. There is no build step on the server, no server-side templating, no
 framework to satisfy — whatever your bundler emits is what runs.
 
@@ -39,10 +45,11 @@ than skipping a bad file:
 - **The slug must match** the applet you are uploading to, and it is immutable once created.
 - **A `version` string uploads once per applet.** Bump it every time, including during testing.
 
-Installation runs inside a transaction: the version row is created, every declared capability's
-`onInstall()` hook runs — this is where `db@1` creates the collection tables and their generated
-columns — and only then are files extracted. A failure anywhere rolls the whole thing back and
-deletes the extracted directory.
+Installation runs inside a transaction: the version row is created, the files are extracted, and
+then every declared capability's `onInstall()` hook runs — this is where `db@1` checks seed files
+and migration names and registers new collection names. No tables are created; records are only
+touched at [promotion](publishing.md#the-data-cutover). A failure anywhere rolls the whole thing
+back and deletes the extracted directory.
 
 <a name="the-starter"></a>
 ## The Starter
@@ -97,15 +104,18 @@ having, because negligence is the common case.
 `npm run package` in the starter does the whole job:
 
 ```js
-// scripts/package.js — abbreviated
+// scripts/package.mjs — abbreviated
 const manifest = JSON.parse(readFileSync('dist/manifest.json', 'utf8'));
 
 execSync('npm sbom --sbom-format cyclonedx --omit dev', { cwd: lockDir })  // → dist/sbom.json
+cpSync('migrations', 'dist/migrations', { recursive: true });                // when present
 execSync(`zip -r -X "${zipPath}" . -x ".*" -x "__MACOSX*"`, { cwd: 'dist' });
 ```
 
-Two details worth keeping if you write your own: `-X` drops extra file attributes, and excluding
-dotfiles keeps `.DS_Store` out of an archive the installer would otherwise skip anyway.
+Three details worth keeping if you write your own: `-X` drops extra file attributes, excluding
+dotfiles keeps `.DS_Store` out of an archive the installer would otherwise skip anyway, and a
+top-level `migrations/` is copied in as written — never bundled, because the Rack imports each file
+on its own.
 
 Upload the result through the admin API, or from the deployment:
 

package/dist/docs/auth.md

@@ -4,6 +4,7 @@
 - [Declaring Attributes](#declaring-attributes)
 - [Reading the Participant](#reading-the-participant)
 - [Degrading Gracefully](#degrading-gracefully)
+- [Roles](#roles)
 - [Rack Side](#rack-side)
 
 <a name="introduction"></a>
@@ -86,6 +87,59 @@ Design the withheld path first and treat personalisation as an enhancement. An a
 `Hello, undefined` when an attribute is missing has failed validation of a kind the Rack cannot
 perform for you.
 
+`launch.auth.withheld` lists the requested keys this deployment never releases, which is useful in
+development to tell "not configured here" from "not set for this person". It says nothing about any
+one participant.
+
+<a name="roles"></a>
+## Roles
+
+Roles answer a different question: *what part does this person play in this applet?* They need no
+capability. Every launch carries the participant's roles, resolved by the Rack:
+
+```ts
+Rack.auth.roles();                    // ['member', 'applet-author', 'judge']
+Rack.auth.hasRole('judge');           // true
+Rack.auth.isGuest();                  // false
+```
+
+Every Rack resolves four built-in roles for every applet:
+
+| Role | Held by |
+|---|---|
+| `member` | A signed-in Rack user. |
+| `guest` | A cookie-keyed [guest](installation.md#participants-and-guests). Exactly one of `member` and `guest` is present. |
+| `applet-author` | The applet's owner. |
+| `rack-administrator` | A user the `ziprack.admin` gate allows. |
+
+An applet adds its own in the manifest's [`roles`](manifest.md#roles) block. Each declared role has
+a `grant`, which says who holds it before the Rack assigns anyone:
+
+| `grant` | Held by |
+|---|---|
+| `everyone` | Every participant. |
+| `members` | Every signed-in participant. |
+| `guests` | Every guest. |
+| `assigned` | Nobody, until the Rack assigns it. The default. |
+
+The Rack then **assigns** declared roles to signed-in participants, per applet: to a Rack user, to
+everyone holding one of the Rack's own roles (an administrator, say), to an email address, or to
+every address at a domain. An assignment adds to the grant; it never takes the role away from
+someone the grant gives it to. Guests receive grants only, never assignments.
+
+Roles are resolved at launch, so an assignment applies from the participant's next launch. An
+assignment to a role the current version no longer declares is kept, but ignored until a version
+declares the role again.
+
+> **Roles inform your code; nothing enforces them yet.** No capability checks a role server-side:
+> a `db@1` collection's `permissions` and a broadcast's `facilitator_events` know nothing about
+> them. Use roles to decide what to render and which actions to offer. Do not rely on them to keep a
+> determined participant out of data the manifest's scopes and permissions already expose.
+
+Declared roles are not the room's `facilitator` and `participant`. Those belong to
+[`broadcast@1`](broadcast.md#the-facilitator-role), change during a session, and are enforced by
+the Rack.
+
 <a name="rack-side"></a>
 ## Rack Side
 
@@ -104,3 +158,25 @@ Admin endpoints:
 To source attributes from SSO claims instead, bind
 `ZipRack\Auth\Contracts\ProfileAttributeSource`; `ClaimMapSource` is the default implementation and
 a reasonable starting point.
+
+Role assignments are core, so they work whether or not `ziprack/auth` is installed:
+
+| Route | Purpose |
+|---|---|
+| `GET /ziprack/admin/applets/{applet}/roles` | `roles` (the current version's, each with its `assignments`), `undeclared` (assignments to roles it no longer declares), `built_in`, `rack_roles`. |
+| `PUT /ziprack/admin/applets/{applet}/roles/{role}` | Replace one role's assignments: `{ assignments: [{ type, value }] }`. |
+
+| `type` | `value` |
+|---|---|
+| `user` | A Rack user's id. |
+| `rack_role` | A key from `RackRoles::all()`. |
+| `email` | An address, compared case-insensitively. |
+| `domain` | `example.com` (a leading `@` is dropped). Matches that domain exactly, not its subdomains. |
+
+The Rack's own roles come from `ZipRack\Core\Contracts\RackRoles`: `all()` returns every key and
+label, `of($user)` the keys one user holds. The default, `GateRackRoles`, knows one, `administrator`,
+from the `ziprack.admin` gate. A Rack with its own roles binds its implementation:
+
+```php
+$this->app->singleton(RackRoles::class, MyRackRoles::class);
+```

package/dist/docs/broadcast.md

@@ -26,7 +26,7 @@ Transport is Laravel Reverb. That is a deployment concern: nothing in the applet
 <a name="rooms"></a>
 ## Rooms
 
-A **room** is an applet version plus its members. Every member has exactly one of two roles —
+A **room** is an applet plus its members. Every member has exactly one of two roles —
 `participant` or `facilitator` — and membership is orthogonal to attempts: a room may contain
 attempts (each person running their own inside a shared session) or none at all.
 

package/dist/docs/conformance.md

@@ -28,19 +28,18 @@ The suite runs inside a transaction that is rolled back, so it is safe against a
 check builds its own fixture — a temporary applet, a version, a package — and cleans up after itself.
 
 ```
-✓ manifest requires schema
-✓ installer rejects unsafe zips
-✓ unimplemented capability is refused
-✓ undeclared capability is refused
-✓ csp is tightened
-✓ retired version is gone
-✓ promotion requires review
-✓ completed attempt is frozen
-✓ attempts are pinned
-✓ statements are append-only
-✓ records are scoped and validated
+  PASS A manifest missing required fields fails validation with the expected error
+  PASS The installer rejects zips containing traversal, absolute paths, symlinks or disallowed files
+  PASS An applet requesting a capability this Rack does not implement is refused at install
+  …
+  PASS db@1: records are schema-validated, quota-limited and invisible across scopes
+  PASS db@1: applet data carries over to a new version, and a version that would lose some is not promoted silently
+
+18 checks, 0 failed.
 ```
 
+A failing check prints `FAIL`, its name and the reason, and the command exits non-zero.
+
 <a name="what-it-checks"></a>
 ## What It Checks
 
@@ -55,17 +54,19 @@ Core checks run on every Rack:
 | `CspIsTightened` | The response CSP contains the required directives, and `img-src` does not contain `https:`. |
 | `RetiredVersionIsGone` | A retired version can no longer be launched. |
 | `PromotionRequiresReview` | A version adding a capability cannot be promoted unapproved. |
+| `RolesAreDeclaredAndResolved` | A manifest declaring a built-in role fails validation, and a guest launch resolves exactly `guest` plus the roles granted to everyone and to guests. |
 
 Each installed capability contributes its own, so the suite grows with the Rack:
 
 | Check | Capability |
 |---|---|
-| `CompletedAttemptIsFrozen`, `AttemptsArePinned` | `attempt` |
+| `CompletedAttemptIsFrozen`, `AttemptsArePinned`, `PreviewAttemptsAreSeparate` | `attempt` |
 | `StatementsAreAppendOnly` | `activity` |
 | `RecordsAreScopedAndValidated` | `db` |
+| `DataSurvivesPromotion` | `db` — applet records carry over to a new current version, and a version whose schema rejects them is refused with `DataCutoverRequired` rather than promoted |
 | `UploadsAreScopedAndTyped` | `storage` |
 | `AiBudgetsAreEnforced` | `ai` |
-| `FacilitatorEventsAreEnforced` | `broadcast` |
+| `FacilitatorEventsAreEnforced`, `InviteNeedsAnOpenRoom` | `broadcast` |
 
 <a name="in-ci"></a>
 ## In CI

package/dist/docs/database.md

@@ -8,7 +8,11 @@
 - [Permissions](#permissions)
 - [Quotas](#quotas)
 - [Seeding](#seeding)
+- [Data Across Versions](#data-across-versions)
+- [Data Migrations](#data-migrations)
+- [Snapshots](#snapshots)
 - [How It Is Stored](#how-it-is-stored)
+- [Rack Side](#rack-side)
 
 <a name="introduction"></a>
 ## Introduction
@@ -67,11 +71,19 @@ what happens to it when an attempt ends.
 | `attempt` | One attempt | **Frozen when the attempt completes**, alongside `state` | `attempt@1` |
 | `user` | One participant | Outlives any attempt | — |
 | `room` | Everyone in the room | The room | `broadcast@1` |
-| `applet` | Everyone on this applet version | The version. Read-mostly: seed data, shared catalogs | — |
+| `applet` | Everyone using the applet, on every version | The applet. Carries over every promotion. Seed data, shared catalogs | — |
 
 A session that has no attempt or no room cannot touch a collection scoped to one; the call is
 refused with `forbidden` rather than silently falling back to something else.
 
+`user`, `room` and `applet` records belong to the applet, not to a version, so they are still there
+after you promote a new one — see [Data Across Versions](#data-across-versions). `attempt` records
+stay with their attempt, and so with the version it ran on.
+
+A session reads and writes a collection through the definition of the version it launched on. An
+attempt pinned to an earlier version keeps that version's schema, indexes and quota until it
+completes, even after a later version changed them.
+
 <a name="reading-and-writing"></a>
 ## Reading and Writing
 
@@ -183,33 +195,230 @@ The seed file is a JSON array of records, each one a document exactly as `create
 ]
 ```
 
-The installer loads it when the version is installed, inside the same transaction, and holds every
-record to the rules a write would face: it must be an object, it must match the schema, it must fit
+The seed is **checked at install and loaded at promotion**. At install the Rack holds every record
+to the rules a write would face: it must be an object, it must match the schema, it must fit
 `max_bytes`, and the file must fit `max_records`. One bad record refuses the whole package, and the
 error names the record's index and the failing path. A package with a bad seed never installs.
 
+When the version is promoted, the seed loads into the collection **only if its live dataset is
+empty**. A seed is the starting data, never a reset: once the applet has records, a later version's
+seed file is not loaded, even if it changed. The promotion plan says so. To change records that
+already exist, ship a [data migration](#data-migrations).
+
 Things to know:
 
 - **Only `applet` scope.** No room, participant or attempt exists at install, so nothing else has
   a scope to seed into.
-- **Every version gets its own copy.** `applet` records belong to the version, so each version
-  loads its own seed file. Records written to the previous version stay with that version.
+- **Loaded once, then the data is yours.** Records carry over every promotion. If the collection is
+  emptied (preview records do not count), the next promotion loads the seed again.
 - **Seeded records have no owner.** `owner_id` is `null`, so under the default `owner` permission
   participants can read them but cannot change them. Declare `members` or `facilitator` if they
   should be editable.
-- **No `RecordChanged` events.** Nobody is listening to a version that has not launched yet.
+- **No `RecordChanged` events.** The seed loads inside the promotion, before any session runs the
+  new version.
 - **The quota still applies.** A seed is capped at 5000 records (`max_records_per_scope`), and so
   is everything later written to that scope.
 - **Not in the mock Rack.** The SDK's `MockRack` does not load seed files. In local development,
   create the records from your dev harness.
 
+<a name="data-across-versions"></a>
+## Data Across Versions
+
+Promoting a version carries the applet's data over to it. `user`, `room` and `applet` records are
+kept and checked against the new version's collections; `attempt` records are left alone, in the
+shape their attempt wrote them. Nothing about your data changes at install: a new version's
+collections are checked, and names the applet has never had are registered empty, but the live
+version keeps reading what it always read until promotion.
+
+At promotion the Rack plans the cutover. For each declared collection it works out whether it is
+`added`, `removed`, `restored`, `changed` or `unchanged`, describes the structural diff (a new
+required property, a narrowed enum, a changed quota), and — when no migration runs — validates
+every existing record against the new schema and quota. A promotion that would leave records the
+new version rejects, strand a collection that holds records, or roll migrations back is not done
+silently: it is refused until someone confirms, and the refusal carries the plan. See
+[Promotion](publishing.md#promotion) for how that looks from the admin API, the CLI and MCP.
+
+| The new version… | What happens at promotion |
+|---|---|
+| Changes nothing about its collections | Promotes. Records are untouched; no snapshot is taken. |
+| Makes a compatible change: a new optional property, a wider enum, a new index, a new collection | Promotes. Existing records validate, so they carry over as they are. A snapshot is taken first when a collection holding records changed. New collections start empty, or with their seed. |
+| Ships a [migration](#data-migrations) that has not run on this applet | Must be promoted from the Rack's UI, which runs the migrations in the browser, checks the result, then commits it. The CLI and MCP refuse it (`migration_required`). |
+| Makes an incompatible change with no migration | Refused with `data_loss`, naming how many records the new schema rejects, with samples. Once confirmed, rejected records are deleted (`invalid: discard`, the default) or kept as they are (`keep`). A kept record fails validation on its next update until it is fixed. |
+| Drops a collection that holds records | Refused with `data_loss`. Once confirmed, the collection is set aside with its records; `ziprack:db:prune` deletes them. A later version that declares it again gets them back. |
+| Changes a collection's `scope` | Refused **at install**: `Collection [x] cannot change scope from [room] to [applet]; use a new collection name.` A migration cannot move records between scopes either. |
+| Lowers `max_records` below what a scope holds, or `max_bytes` below a record's size | Refused with `data_loss`. Once confirmed, oversize records count as rejected; a scope over its new record quota keeps its records but refuses `create()` with `quota_exceeded` until it is back under. |
+| Ships a changed seed file for a collection that has records | Promotes. The seed is not loaded, and the plan notes it. Use a migration. |
+| Is an earlier version that lacks migrations already run (a rollback) | Those migrations run `down`, newest first, from the source the Rack stored when they ran up — in the browser, like any migration, and flagged as a rollback. A migration with no `down` stops it; restore the [snapshot](#snapshots) taken before it ran instead. An earlier version with no migrations involved is treated like any other change. |
+| Is the applet's first | Nothing to carry over. Its migrations are recorded as applied without running, and the seed loads. |
+
+Uploading without activating changes nothing about the data; the plan is made when someone
+promotes. An upload *with* activate tries the promotion, and if the cutover needs a decision the
+version stays installed but not current.
+
+Two more rules apply to every cutover:
+
+- **Preview records are dropped where shapes change.** A cutover that runs migrations deletes every
+  [preview](attempts.md#preview-runs) record of the applet; one that does not deletes the preview
+  records of the collections whose definition changed. Migrations never see preview records.
+- **Pinned attempts keep the old shape.** An in-progress attempt on the outgoing version reads and
+  writes `user`, `room` and `applet` records through that version's definition until it completes.
+  After a cutover that reshapes them, it can still write records in the old shape. If your applet is
+  pinned, write code that tolerates both, or reshape only what in-progress attempts do not write.
+
+<a name="data-migrations"></a>
+## Data Migrations
+
+When a new version needs existing records in a new shape — a renamed property, a split collection,
+a value back-filled from another — ship a data migration. A migration is an ES module in a
+`migrations/` directory at the zip root:
+
+```
+my-applet-2.0.0.zip
+├── manifest.json
+├── migrations/
+│   ├── 2026_09_01_090000_add_difficulty.js
+│   └── 2026_10_09_120000_split_archived_ideas.js
+└── …
+```
+
+| Rule | |
+|---|---|
+| Name | `YYYY_MM_DD_HHMMSS_name.js` (or `.mjs`), lowercase, directly inside `migrations/`. Anything else refuses the package at install. |
+| Order | Name order. The timestamp prefix is the order. |
+| Cumulative | **Keep every migration you have ever shipped.** The Rack runs the ones this applet has not run yet, so any earlier version can be brought forward. |
+| Self-contained | Each file is imported on its own, with no network. Do not import other files or packages. The starter copies `migrations/` into the zip as written, unbundled. |
+| Exports | `up(db, ctx)`, and `down(db, ctx)` if the change can be undone. Either as named exports or on the default export. |
+
+```js
+// migrations/2026_09_01_090000_add_difficulty.js
+export function up(db, ctx) {
+    for (const question of db.questions) {
+        question.data.difficulty ??= 'medium';
+    }
+    ctx.log(`set a difficulty on ${db.questions.length} questions`);
+}
+
+export function down(db) {
+    for (const question of db.questions) {
+        delete question.data.difficulty;
+    }
+}
+```
+
+`db` holds the applet's carried records, by collection name: every `user`, `room` and `applet`
+collection, including ones the outgoing version no longer declares. A record is:
+
+```ts
+interface MigrationRecord {
+    id: string;
+    scope_id: number;          // the room or participant; 0 for applet scope
+    owner_id: number | null;
+    data: object;              // the document, as create() took it
+    created_at: string;
+    updated_at: string;
+}
+```
+
+Mutate it in place, or return `{ collection: records[] }` for the collections you replace. A
+collection you return replaces that collection; one you leave out is kept unchanged, so its records
+must already fit the target version.
+
+```js
+// migrations/2026_10_09_120000_split_archived_ideas.js
+export default {
+    up(db) {
+        return {
+            ideas: db.ideas.filter((idea) => idea.data.status !== 'archived'),
+            archived_ideas: db.ideas.filter((idea) => idea.data.status === 'archived'),
+        };
+    },
+
+    down(db) {
+        return { ideas: [...db.ideas, ...db.archived_ideas] };
+    },
+};
+```
+
+A record that appears under another collection's name moves there, keeping its id. To add a record,
+leave out `id`; it is given a new one. A collection the target version does not declare cannot be
+written to: returning it is ignored.
+
+`ctx` is `{ direction, applet, from, to, scopes, log }`: `'up'` or `'down'`, the applet slug, the
+outgoing and target version strings (`from` is `null` when nothing was current), each collection's
+scope by name, and `log(...)` for lines kept with the snapshot. `console.log`, `info`, `warn` and
+`error` are captured the same way.
+
+**The Rack checks what comes back.** Every record the cutover leaves in place, returned or kept,
+must match the target version's schema and fit its quota. A record cannot change its `scope_id` or `owner_id`, and can move only to
+a collection with the same scope. A new record in a `user` or `room` collection needs the
+`scope_id` of a participant or room that already has records, and its `owner_id` must be `null` or
+someone who already owns one. Records missing from a returned collection are deleted. If any check
+fails, nothing is written and the errors name the collection, the record and the problem. These are
+checks on structure, not on which participant's values end up in which record: migrations see every
+scope's data and are [privileged code](security.md#the-migration-runner).
+
+Migrations run in the browser of whoever promotes, in a sandboxed frame with no network access
+(see [Security](security.md#the-migration-runner)), one after another, 30 seconds each by default.
+A migration that throws, times out, lacks the function it needs, or returns anything other than
+`{ collection: records[] }` stops the run, and nothing is written. If the applet's data changes
+while they run, the promotion is refused with `data_changed` and they run again.
+
+The Rack keeps a ledger of which migrations have run on each applet, with each one's source. Going
+forward, pending `up`s run in name order. Promoting a version that lacks some applied migrations
+runs their `down`s in reverse, from the stored source, so a rollback works even after a later
+package dropped the file. A migration with no `down` cannot be rolled back; the Rack says so, and
+you restore the snapshot taken before it ran.
+
+`attempt` records are never passed in: they stay in the shape their attempt wrote them. Preview
+records are not passed in either.
+
+Migrations are plain functions over plain arrays, so test them like any other: import the module,
+call `up` on a fixture, assert on the result. The mock Rack does not run them.
+
+<a name="snapshots"></a>
+## Snapshots
+
+Before every cutover that changes data, the Rack copies the applet's entire dataset: every record
+in every collection and scope, preview and set-aside ones included, the collection registry, the
+migration ledger and the applet's [role](auth.md#roles) assignments. The copy is written before the
+promotion's transaction opens and marked applied if the cutover commits, so a migration that
+wrecks the data can always be undone.
+
+The transaction then locks the applet's collections, which holds record writes off until it
+commits, and checks the data is still what the cutover was planned and snapshotted from. A write
+that landed in between refuses the promotion with `data_changed`, before anything is deleted, so a
+cutover never removes a record its snapshot does not hold. Likewise, a promotion refuses with
+`version_changed` if another one committed while it was being prepared.
+
+Snapshots are also taken before every restore, so a restore can itself be undone, and on request:
+
+```sh
+php artisan ziprack:db:snapshot my-applet
+php artisan ziprack:db:snapshots my-applet               # list them, with ids
+php artisan ziprack:db:restore my-applet 42 --force
+```
+
+A restore replaces all of the applet's records, its collection registry, its ledger and its role
+assignments with the snapshot's, then makes the version that was current when it was taken current
+again, if that version is still `ready`. The file's sha256 is checked first; a snapshot that does
+not match is not restored.
+
+The file is gzipped NDJSON: a header line (`format: ziprack-snapshot/1`, with the registry, the
+ledger, role assignments and record counts), then one line per record. It is stored at
+`ziprack/snapshots/{slug}/…ndjson.gz` on `ziprack-db.snapshots.disk`, which defaults to
+`ziprack.disk`. **That disk must be persistent** — S3 in production, like packages.
+
+The newest `ziprack-db.snapshots.keep` (10) are kept per applet, and never at the expense of the
+newest one taken before a cutover.
+
 <a name="how-it-is-stored"></a>
 ## How It Is Stored
 
 Worth knowing, because it explains the constraints above.
 
 Every collection's records live in one shared `ziprack_records` table, created by a migration and
-keyed by collection and scope. The document lives in a JSON column; filters and ordering on an
+keyed by collection and scope — the attempt, participant or room id, or `0` for `applet` scope.
+The document lives in a JSON column; filters and ordering on an
 `indexed` path read that path out of the JSON, typed from the declared schema so numbers compare as
 numbers. Every query is narrowed by an index on `(collection_id, scope_id)` first, and the quota caps
 a scope's records, so that read is always over a small, bounded set. The declared schema is still
@@ -221,10 +430,44 @@ with `is_preview` set when it is created. The flag never changes after that, so
 the flag of whoever wrote each card. Applets never see it; it exists for the admin, which leaves
 preview records out unless asked.
 
-**Installing a version never changes the database schema.** Adding a collection or an indexed path
-only writes rows, so the install stays one transaction on every database. Collections that no
-current manifest declares any more keep their records until you run:
+**Installing or promoting a version never changes the database schema.** Adding a collection or an
+indexed path only writes rows, so both stay one transaction on every database. The collection
+registry follows the current version: promotion updates each definition and sets aside the
+collections the new version no longer declares. They keep their records until you run:
 
 ```sh
 php artisan ziprack:db:prune
+php artisan ziprack:db:prune --stranded    # also the rows described below
+```
+
+**Upgrading from a Rack before v1.8.** Applet-scoped records used to belong to the version that
+wrote them, so every upgrade started from an empty dataset. A migration re-keys the current
+version's rows to the applet; earlier versions' rows are left where they were, unreachable. Bring
+one version's rows back into the live dataset, or delete them all:
+
+```sh
+php artisan ziprack:db:recover my-applet 1.2.0 [collection] [--replace] [--force]
+php artisan ziprack:db:prune --stranded
 ```
+
+`recover` adds to the live records (`--replace` deletes those first), reports how many recovered
+records the current schema rejects, and takes a snapshot before it changes anything.
+
+<a name="rack-side"></a>
+## Rack Side
+
+| Command | Does |
+|---|---|
+| `ziprack:db:prune [--stranded] [--force]` | Delete set-aside collections and their records; with `--stranded`, pre-v1.8 applet rows too. |
+| `ziprack:db:recover {slug} {version} [collection] [--replace] [--force]` | Bring an earlier version's stranded applet-scoped records back. |
+| `ziprack:db:snapshot {slug}` · `ziprack:db:snapshots {slug}` | Take a snapshot; list them. |
+| `ziprack:db:restore {slug} {snapshot} [--force]` | Replace the applet's data with a snapshot. |
+
+The admin API routes — the record browser, the cutover plan and check, snapshots — are listed in
+[Reporting](reporting.md#the-admin-api).
+
+A Rack that lets its operators edit records uses `ZipRack\Db\RecordAdmin`: `create()` (into an
+`applet` collection only, since every other scope belongs to a participant, room or attempt),
+`update()`, `setField()` across many records, all or none, and `delete()`. Every write is checked
+against the schema and quota exactly as an applet's write is, and fires the same `RecordChanged`
+event, with a `null` participant, so a live room sees the edit.