@ziprack/sdk 0.2.1 → 0.3.0

package/dist/docs/extending.md

@@ -7,6 +7,8 @@
 - [Message Handlers](#message-handlers)
 - [Launch Payload](#launch-payload)
 - [Install Hooks](#install-hooks)
+- [Promotion Hooks](#promotion-hooks)
+- [Rack Roles](#rack-roles)
 - [Conformance and Status](#conformance-and-status)
 - [The SDK Side](#the-sdk-side)
 
@@ -60,7 +62,8 @@ class SurveyCapability extends AbstractCapability
 | `validateManifest()` | Cross-field checks; add errors to the validator. |
 | `messageHandlers()` | `type => handler class`. |
 | `launchPayload()` | What to merge into `rack:launch` under this capability's id. |
-| `onInstall()` / `onPromote()` / `onRetire()` | Version lifecycle hooks. `onInstall()` runs inside the install transaction, so row changes only. |
+| `onInstall()` / `onPromote()` / `onRetire()` | Version lifecycle hooks. `onInstall()` runs inside the install transaction, after extraction, so row changes only. `onPromote()` runs after the promotion commits. |
+| `preparePromotion()` | Only with `ParticipatesInPromotion`: carry state over when the current version changes, or refuse. See [Promotion Hooks](#promotion-hooks). |
 | `adminRoutes()` | Headless admin routes, registered only when `ziprack/admin` is installed. |
 | `conformanceTests()` | Checks contributed to the conformance suite. |
 | `statusChecks()` | Warnings for `ziprack:status` and `/ziprack/health`. |
@@ -208,15 +211,78 @@ public function onInstall(AppletVersion $version, ?AppletVersion $previous): voi
 }
 ```
 
-`onInstall()` runs inside the install transaction, with the previous current version for comparison
-— which is what lets `db@1` register, update and orphan collections as they change between
-versions. If it throws, the whole installation rolls back and extracted files are removed.
+`onInstall()` runs inside the install transaction, after the package is extracted, with the
+previous current version for comparison. It can read the package's files from
+`$version->storage_path` on `ziprack.disk` — which is how `db@1` checks seed files and migration
+names. Keep it to checking and to rows the live version cannot see: the version is not current yet,
+so anything that changes what running sessions read belongs in [promotion](#promotion-hooks). If it
+throws, the whole installation rolls back and extracted files are removed; throw a
+`PackageInstallException` to give the uploader a message.
 
 Keep it to row changes. `CREATE`, `ALTER` and `DROP` commit any open transaction on MySQL and
 MariaDB, which breaks the install and lets the conformance suite's data escape its rollback. If a
 capability needs tables, ship them as migrations; the conformance suite fails any check that commits
 its transaction.
 
+<a name="promotion-hooks"></a>
+## Promotion Hooks
+
+A capability that holds per-applet state which has to follow the current version — `db@1` and its
+records — implements `ZipRack\Core\Contracts\ParticipatesInPromotion`:
+
+```php
+use ZipRack\Core\Contracts\ParticipatesInPromotion;
+
+class SurveyCapability extends AbstractCapability implements ParticipatesInPromotion
+{
+    public function preparePromotion(AppletVersion $version, ?AppletVersion $outgoing, array $input): ?Closure
+    {
+        $plan = $this->planner->plan($version, $outgoing);
+
+        if ($plan->losesAnswers() && ! ($input['accept_loss'] ?? false)) {
+            throw new PromotionBlockedException('Version '.$version->version.' drops surveys that have answers.');
+        }
+
+        return fn () => $this->planner->apply($plan);   // inside the promotion transaction
+    }
+}
+```
+
+`PromoteVersion::handle($version, $force, $input)` calls it on every capability the *target*
+version declares, whenever the current version actually changes, forwards or back:
+
+1. `preparePromotion()` runs **before** the transaction opens, so slow or file-writing work — `db@1`
+   writes its snapshot here — stays out of it. Throw a `PromotionBlockedException` to refuse.
+2. The closures it returned run **inside** the promotion transaction, before `current_version_id`
+   moves. Row changes only, for the same DDL reason as `onInstall()`.
+3. After the commit, `onPromote()` runs.
+
+`$input` is this capability's share of the promotion input, keyed by its id: the admin API's
+promote body passes `db: {…}` to `db@1`. A refusal that carries something the caller should show
+extends `PromotionBlockedException`; `db@1` throws `ZipRack\Core\Installer\DataCutoverRequired`,
+with a `reason` and the plan as `details()`, which the admin API turns into a `409`.
+
+<a name="rack-roles"></a>
+## Rack Roles
+
+An applet's declared [roles](auth.md#roles) can be assigned to everyone holding one of the Rack's
+own roles. zipRACK asks the Rack what those are through `ZipRack\Core\Contracts\RackRoles`:
+
+```php
+interface RackRoles
+{
+    /** @return array<string, string> key => label */
+    public function all(): array;
+
+    /** @return list<string> keys */
+    public function of(Authenticatable $user): array;
+}
+```
+
+The default, `GateRackRoles`, has one role, `administrator`, from the `ziprack.admin` gate. A Rack
+with authors, facilitators or departments binds its own, the same way it binds
+[`AppletAccess`](reporting.md#who-may-do-what).
+
 <a name="conformance-and-status"></a>
 ## Conformance and Status
 

package/dist/docs/installation.md

@@ -99,7 +99,7 @@ ones you will actually touch.
 |---|---|
 | `ziprack-auth.php` | `releasable` — the single place a deployment answers "what can applets see about our people"; `claim_map` |
 | `ziprack-attempt.php` | `max_state_bytes` (64 KB), `max_segment_keys` (20) |
-| `ziprack-db.php` | `max_records_per_scope` (5000), `max_record_bytes` (64 KB), `max_indexed_paths` (8), `list_limit` (100) |
+| `ziprack-db.php` | `max_records_per_scope` (5000), `max_record_bytes` (64 KB), `max_indexed_paths` (8), `list_limit` (100), `snapshots.disk` (`ziprack.disk`; must be persistent), `snapshots.keep` (10) |
 | `ziprack-storage.php` | `disk`, `max_bytes_cap` (50 MB), `url_ttl_minutes` (10), `scanner` (`null` \| `clamav`) |
 | `ziprack-ai.php` | `provider`, `models.analysis`, `models.chat`, `allowed_models`, the whole `budget` block |
 | `ziprack-broadcast.php` | `join_prefix`, `facilitator_grace_seconds` (60), `presence_window_seconds` (45), `max_event_bytes` |
@@ -122,6 +122,7 @@ validation. Defaults apply when a manifest declares nothing.
 | `GET /ziprack/f/{file}` | Signed, short-lived download of a stored file (`storage`). |
 | `POST /ziprack/s/{session}/broadcast/auth` | Rack-side WebSocket channel authentication (`broadcast`). |
 | `GET /ziprack/health` | Fleet visibility: format, core version, capabilities, warnings. |
+| `GET /ziprack/migration-runner` | The no-network page a Rack UI frames, sandboxed, to run [data migrations](database.md#data-migrations) at promotion. |
 | `GET /r/{code}` | Join a room by code (`broadcast`). |
 | `*` `/ziprack/admin/*` | The headless admin API (`ziprack/admin`). |
 
@@ -172,8 +173,8 @@ the deployment owns. A Rack can add an approved image host; it cannot reintroduc
 
 | Command | Does |
 |---|---|
-| `ziprack:install {zip} [--applet=] [--activate]` | Install a package as a new version. |
-| `ziprack:promote {slug} {version} [--force]` | Make a version current. `--force` also approves a pending capability review. |
+| `ziprack:install {zip} [--slug=] [--activate] [--force]` | Install a package as a new version; `--slug` installs into that existing applet. `--activate` promotes it, `--force` past a pending capability review. |
+| `ziprack:promote {slug} {version} [--force] [--accept-data-loss] [--keep-invalid]` | Make a version current. `--force` also approves a pending capability review; `--accept-data-loss` confirms a [data cutover](publishing.md#the-data-cutover) that rejects or drops records, and `--keep-invalid` keeps rejected records instead of deleting them. |
 | `ziprack:retire {slug} {version}` | Kill switch: the version can no longer be launched. |
 | `ziprack:status [--json]` | Format, core version, installed capabilities, warnings. |
 | `ziprack:conformance [--json]` | Verify this Rack honours `ziprack/1`. |
@@ -182,5 +183,9 @@ the deployment owns. A Rack can add an approved image host; it cannot reintroduc
 | `ziprack:roster:import {csv}` | Import profile attributes by email. |
 | `ziprack:room:create {slug} [--name=] [--mode=] [--roster=]` | Create a room and print its join code. |
 | `ziprack:rooms:tick` | Vacate and reassign dropped facilitators. **Schedule every minute.** |
-| `ziprack:db:prune [--force]` | Drop tables of collections no current manifest declares. |
+| `ziprack:db:prune [--stranded] [--force]` | Delete collections no current manifest declares, and their records. `--stranded` also deletes applet-scoped rows earlier versions left behind before v1.8. |
+| `ziprack:db:recover {slug} {version} [collection] [--replace] [--force]` | Bring those stranded rows back into the live dataset. |
+| `ziprack:db:snapshot {slug}` · `ziprack:db:snapshots {slug}` | Snapshot an applet's data; list its snapshots. |
+| `ziprack:db:restore {slug} {snapshot} [--force]` | Replace an applet's data with a snapshot and make that version current again. |
+| `ziprack:mcp:token {email} [--name=]` · `ziprack:mcp:revoke {email} [token] [--all]` | Mint and revoke [MCP](mcp.md) tokens. |
 | `ziprack:response-analysis [--applet=] [--force]` | Regenerate admin AI summaries. **Schedule every few hours.** |

package/dist/docs/introduction.md

@@ -40,7 +40,7 @@ The iframe is rendered with:
 
 ```html
 <iframe sandbox="allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox"
-        allow="autoplay; fullscreen; picture-in-picture; encrypted-media">
+        allow="autoplay; fullscreen; picture-in-picture; encrypted-media; clipboard-write">
 ```
 
 Note the absence of `allow-same-origin`. The applet document has an **opaque origin**: no cookies,
@@ -72,11 +72,12 @@ ever cross the boundary.
 | **Applet** | One experience or app, identified by an immutable `slug`. Has many versions. | core |
 | **Version** | One uploaded zip. Immutable. Exactly one is current. | core |
 | **Participant** | The person in front of the applet, resolved from the Rack's own users (or a guest cookie). | core |
+| **Role** | A name the participant holds in an applet: built in (`member`, `guest`, `applet-author`, `rack-administrator`) or declared by the manifest and assigned by the Rack. Sent at launch. | core |
 | **Attempt** | One participant's run. Holds `status`, `state`, `segment`. Pinned to the version it started on. | `attempt@1` |
 | **Statement** | Append-only record: actor did verb on activity with result. The audit trail and the uniform export. | `activity@1` |
-| **Record** | A mutable row in a declared collection, at a declared scope. Working state. | `db@1` |
+| **Record** | A mutable row in a declared collection, at a declared scope. Working state that carries over to new versions. | `db@1` |
 | **Stored file** | A participant upload, addressable only once scanned clean. | `storage@1` |
-| **Room** | A shared session: an applet version plus its members, each `participant` or `facilitator`. | `broadcast@1` |
+| **Room** | A shared session: an applet plus its members, each `participant` or `facilitator`. | `broadcast@1` |
 | **Profile attribute** | A Rack-owned fact about the participant, released only if requested and permitted. | `auth@1` |
 
 Statements and records coexist because they answer different questions. A statement is *what
@@ -103,8 +104,9 @@ any call the manifest did not declare.
 Capability versions are independent of the format string and of the Composer package version. See
 [Versioning](versioning.md).
 
-Two things need no capability: [declared media](media.md) (`Rack.media.embedUrl(id)`) and
-`Rack.eject()`, which asks the Rack to leave the applet.
+Three things need no capability: [declared media](media.md) (`Rack.media.embedUrl(id)`),
+[roles](auth.md#roles) (`Rack.auth.hasRole(name)`), and `Rack.eject()`, which asks the Rack to
+leave the applet.
 
 <a name="what-ziprack-is-not"></a>
 ## What zipRACK Is Not

package/dist/docs/manifest.md

@@ -3,6 +3,7 @@
 - [Introduction](#introduction)
 - [Core Fields](#core-fields)
 - [The Requires Block](#the-requires-block)
+- [Roles](#roles)
 - [Capability Sections](#capability-sections)
 - [A Complete Example](#a-complete-example)
 - [Validation Errors](#validation-errors)
@@ -42,6 +43,7 @@ upload meaningful: the manifest is a contract a reviewer can read.
 | `entry` | Optional, default `index.html`. Relative, no `..`, ends in `.html`. |
 | `requires` | Required, even if empty. See below. |
 | `media` | Optional. See [Media](media.md). |
+| `roles` | Optional. The applet's own roles. See [Roles](#roles). |
 
 Everything else at the top level belongs to a capability. A section whose owning capability is not
 declared is a validation error, and so is a section no installed capability owns.
@@ -64,6 +66,28 @@ declared is a validation error, and so is a section no installed capability owns
 - Declaring `attempt@1` has a side effect: it pins every participant to the version they started on.
   See [Versioning](versioning.md#version-pinning).
 
+<a name="roles"></a>
+## Roles
+
+```json
+"roles": [
+    { "name": "dungeon-master", "label": "Dungeon Master", "description": "Runs the session." },
+    { "name": "spectator", "grant": "guests" }
+]
+```
+
+A core key, so it needs no capability. Every launch tells the applet which roles the participant
+holds; the Rack decides who holds them. See [Roles](auth.md#roles) for how they resolve.
+
+| Field | Rules |
+|---|---|
+| `name` | Required. Lowercase words joined by hyphens, `^[a-z][a-z0-9]*(-[a-z0-9]+)*$`, max 40, unique. Not one of the built-in roles: `rack-administrator`, `applet-author`, `member`, `guest`. |
+| `label` | Optional, max 60. Shown to whoever assigns the role. Defaults to `name`. |
+| `description` | Optional, max 255. |
+| `grant` | Optional. Who holds it before anyone is assigned: `everyone`, `members`, `guests` or `assigned` (the default — nobody). |
+
+At most 20 roles.
+
 <a name="capability-sections"></a>
 ## Capability Sections
 
@@ -111,6 +135,10 @@ An applet exercising every capability at once. Most applets need three or four.
         { "id": "debrief.clip", "provider": "youtube", "key": "dQw4w9WgXcQ" }
     ],
 
+    "roles": [
+        { "name": "judge", "label": "Judge", "description": "Scores the final pitches." }
+    ],
+
     "segments": [
         {
             "key": "track",
@@ -205,6 +233,10 @@ one message. The checks that catch people out:
 | `A room-scoped collection requires the [broadcast] capability` | Scope implies capability. |
 | `Indexed path [votes] must be a string, integer, number or boolean property declared in the schema` | You can only index what you declared, and only scalars. |
 | `Only applet-scoped collections can be seeded` | A seed is shared reference data; see [Seeding](database.md#seeding). |
+| `Role names are lowercase words joined by hyphens, like "dungeon-master".` | `roles[].name` has capitals, underscores or spaces. |
+| `Role [guest] is one every Rack provides …; it cannot be declared.` | `rack-administrator`, `applet-author`, `member` and `guest` are built in. |
+| `Duplicate role [judge].` | Role names are unique. |
+| `A role's grant is one of everyone, members, guests or assigned.` | Any other `grant`. |
 | `Placeholder {{pitch}} is not declared in vars.properties` | Prompt templates and their `vars` schema must agree. |
 | `Analysis prompts need an output_schema of type object` | `mode: "analysis"` is structured output by definition. |
 | `The $room channel is reserved for the Rack` | Pick another channel name. |

package/dist/docs/mcp.md

@@ -100,7 +100,7 @@ user is no longer an admin.
 | `rack-status` | mcp | Format, implemented capabilities, health notes. Needs `ViewRack` |
 | `list-applets`, `get-applet`, `get-applet-version` | mcp | Applets, versions, review state, manifest |
 | `create-upload` | mcp | A signed upload URL (see below) |
-| `promote-version` | mcp | Make a version current. It cannot approve, so it cannot force |
+| `promote-version` | mcp | Make a version current. It cannot approve, so it cannot force. See below |
 | `get-scaffold-skill` | mcp | The applet scaffold skill's files |
 | `list-attempts`, `get-attempt`, `attempt-overview` | attempt | |
 | `list-statements`, `applet-metrics` | activity | |
@@ -118,6 +118,17 @@ Capability tools are only present when their capability package is installed.
 - **Audit log.** Writes (`mcp:upload`, `mcp:promote`) go to the audit log with the admin and the
   OAuth client or token name they came through.
 
+`promote-version` takes `slug`, `version`, and for the [data cutover](publishing.md#the-data-cutover):
+
+| Argument | |
+|---|---|
+| `accept_data_loss` | Promote even though the new version's collections reject or drop existing records. Pass it only after the user has seen what would be lost. |
+| `keep_invalid` | With `accept_data_loss`, keep the records the new schema rejects instead of deleting them. |
+
+A refused cutover comes back as a validation error carrying the message and the plan's notes, so
+the agent can tell the user what would change. A version with data migrations is always refused:
+they run in the browser, so it must be promoted from the applet's page in the Rack.
+
 <a name="uploading-a-package"></a>
 ## Uploading a Package
 
@@ -133,8 +144,9 @@ The rules in [Publishing](publishing.md) are unchanged.
 
 - **Default.** A later version installs as not current.
 - **With `activate: true`.** The version is promoted, unless it asks for capabilities that no admin
-  has approved yet. In that case the response carries a `warning` and the version waits in the
-  review queue.
+  has approved yet, or its data cutover needs a decision. In either case the response carries a
+  `warning` and the version stays installed but not current: approve it in the review queue, or
+  promote it with `promote-version` (or from the Rack, when it has migrations).
 - **Reuse.** A used or expired URL answers `410`. Call `create-upload` again.
 
 <a name="the-scaffold-skill"></a>

package/dist/docs/protocol.md

@@ -7,6 +7,7 @@
 - [Streaming](#streaming)
 - [Events](#events)
 - [What the Shell Does](#what-the-shell-does)
+- [The Migration Runner](#the-migration-runner)
 
 <a name="when-you-need-this"></a>
 ## When You Need This
@@ -51,6 +52,10 @@ The applet announces readiness as early as it can; the host replies with the ful
 (see [Launch Data](sdk.md#launch-data)). Do not send capability calls before `rack:launch` arrives —
 queue them, as the SDK does.
 
+The core of the payload is `schema`, `actor`, `applet`, `capabilities`, `media` and `roles` — the
+participant's [roles](auth.md#roles) in this applet, as a list of names, sent whatever the manifest
+declares. Each declared capability adds its own key.
+
 <a name="calls-and-acks"></a>
 ## Calls and Acks
 
@@ -119,3 +124,40 @@ Knowing its behaviour explains timings you would otherwise find surprising:
   `/ziprack/s/{session}/stream/{requestId}` and relays each chunk as a partial ack.
 - **Completion.** A successful `attempt:complete` flips the Rack's own completion chrome — which is
   why a completed attempt lands on its final screen rather than restarting.
+
+<a name="the-migration-runner"></a>
+## The Migration Runner
+
+A second, unrelated frame protocol, between the Rack's own UI and the page that runs a package's
+[data migrations](database.md#data-migrations) at promotion. No applet is involved: the parent is
+the Rack page promoting the version, the child is `GET /ziprack/migration-runner` (route
+`ziprack.migration-runner`), framed sandboxed (see [Security](security.md#the-migration-runner)).
+You need this only if you are building a Rack UI.
+
+Messages are plain objects, not `ziprack` envelopes. Everything the runner posts carries
+`ziprackMigrationRunner: true`; it accepts messages only from `window.parent`, and runs once per
+page load.
+
+```
+runner → parent  { ziprackMigrationRunner: true, type: "ready" }
+parent → runner  { type: "run", steps, collections, context, timeoutMs? }
+runner → parent  { ziprackMigrationRunner: true, type: "log", step, level, text }      … as it runs
+runner → parent  { ziprackMigrationRunner: true, type: "done", collections, ms }
+              or { ziprackMigrationRunner: true, type: "error", step, code, message, stack? }
+```
+
+| Field | |
+|---|---|
+| `steps` | `[{ name, direction: "up" \| "down", source }]`, in run order — the plan's steps from `GET …/cutover`. |
+| `collections` | `{ name: { scope, records } }` — `collections` from `GET …/cutover/data`. |
+| `context` | `{ applet, from, to }`: the slug and the outgoing and target version strings. |
+| `timeoutMs` | Per step. Default 30000. |
+| `level` | `meta`, `step`, `ok`, `fail`, `log`, `info`, `warn` or `error`. |
+| `code` | `missing_up`, `missing_down` (the migration has no such function), `threw`, `timeout`, `bad_result` (it returned something other than `{ collection: records[] }`). |
+
+Each step's source is imported as a module from a `blob:` URL and called with a copy of the
+records; a returned object replaces the collections it names. `done.collections` holds every
+collection, by name, as a list of records: pass it to `POST …/cutover/check` and then, with the
+plan's fingerprint and the logged lines, to `…/promote` as `db.records`, `db.fingerprint` and
+`db.log`. After an `error`, nothing is promoted. The runner also renders every line as a terminal,
+so the parent can show the frame itself as the log.

package/dist/docs/publishing.md

@@ -4,6 +4,7 @@
 - [Installing a Version](#installing-a-version)
 - [Capability Diff Review](#capability-diff-review)
 - [Promotion](#promotion)
+- [The Data Cutover](#the-data-cutover)
 - [The Review Queue](#the-review-queue)
 - [Retiring a Version](#retiring-a-version)
 - [The Audit Log](#the-audit-log)
@@ -27,12 +28,15 @@ php artisan ziprack:install dist-zip/my-applet-1.0.0.zip --activate   # install
 
 or `POST /ziprack/admin/versions/upload` with the zip.
 
-Installation validates the manifest against this Rack's capability set, records the version, runs
-each declared capability's `onInstall()` hook inside a transaction, and only then extracts files. A
-version arrives as `ready` but **not current**, unless it is the applet's first — there is nothing
-to review a first version against, so it is promoted automatically.
+Installation validates the manifest against this Rack's capability set, then, inside one
+transaction, records the version, extracts its files and runs each declared capability's
+`onInstall()` hook — after extraction, so a hook can read the package. `db@1` uses it to check seed
+files and migration names and to register collection names the applet has never had; it does not
+touch existing data. A failure anywhere rolls the transaction back and deletes the extracted
+directory. A version arrives as `ready` but **not current**, unless it is the applet's first —
+there is nothing to review a first version against, so it is promoted automatically.
 
-Once files are extracted the Rack resolves declared media (the oEmbed lookup) and, when
+Once installed the Rack resolves declared media (the oEmbed lookup) and, when
 `publishing.osv_lookup` is on, queues a batch of the SBOM's purls against OSV.dev. Findings attach
 to the version and surface in the review queue; they do not block the install.
 
@@ -74,9 +78,84 @@ php artisan ziprack:promote my-applet 1.1.0 --force    # approve the pending rev
 or `POST /ziprack/admin/applets/{applet}/versions/{version}/approve` followed by
 `…/promote`.
 
-Promotion is refused when the version is not `ready`, or when it has an unapproved capability
-addition — the error names exactly what was added. On success, `current_version_id` moves and each
-capability's `onPromote()` hook runs.
+Promotion is refused when the version is not `ready`, when it has an unapproved capability
+addition — the error names exactly what was added — or when carrying the applet's data over needs
+a decision (below). Otherwise the capabilities' promotion work and the move of `current_version_id`
+commit in one transaction, then each capability's `onPromote()` hook runs.
+
+<a name="the-data-cutover"></a>
+## The Data Cutover
+
+A version declaring `db@1` brings the applet's records over with it (see
+[Data Across Versions](database.md#data-across-versions)). The Rack plans the cutover first, and
+refuses with a reason while the plan needs a decision:
+
+| Reason | Means | To promote |
+|---|---|---|
+| `migration_required` | [Data migrations](database.md#data-migrations) have to run: the version's pending `up`s, or `down`s for applied migrations it lacks. | Promote from the Rack's UI, which runs them in the browser. |
+| `data_changed` | The data changed between planning the cutover (or running the migrations) and committing it. | Review the plan and promote again; run the migrations again. |
+| `version_changed` | Another promotion committed while this one was being prepared. | Review the new plan and promote again. |
+| `migration_invalid` | What the migrations returned does not fit the version. The plan carries the check. | Fix the migration and upload a new version. |
+| `data_loss` | No migration runs, and the new schema or quota rejects existing records, or a dropped collection holds records. | Confirm with `accept_data_loss`. |
+
+Over the admin API the refusal is a `409`:
+
+```json
+{
+    "message": "Version 2.0.0 changes collections that hold data. Review what changes and confirm.",
+    "reason": "data_loss",
+    "plan": {
+        "version": { "id": 12, "version": "2.0.0" },
+        "from": { "id": 9, "version": "1.4.0" },
+        "status": "confirm",
+        "needs_browser": false,
+        "rollback": false,
+        "steps": [],
+        "collections": [
+            {
+                "name": "questions", "scope": "applet", "change": "changed", "records": 240,
+                "diff": [{ "path": "difficulty", "change": "required_property_added", "detail": "New required property difficulty." }],
+                "invalid": 240, "invalid_samples": [{ "id": "…", "errors": { "difficulty": ["…"] } }],
+                "over_quota": 0, "seed": "skipped"
+            }
+        ],
+        "notes": [{ "level": "warning", "message": "240 of 240 records in [questions] do not match the new schema." }],
+        "fingerprint": "…"
+    }
+}
+```
+
+and the decision goes back in the promote body under `db`:
+
+| Key | |
+|---|---|
+| `accept_data_loss` | Confirm a `data_loss` plan. A JSON boolean; anything else is a `422`. |
+| `invalid` | `discard` (the default) deletes the records the new schema rejects; `keep` leaves them. |
+| `records`, `fingerprint`, `log` | A migrating version: what the migrations returned, by collection; the fingerprint of the data they ran on; the runner's log, kept with the snapshot. |
+
+`GET …/versions/{version}/cutover` returns the same plan without promoting, including each step's
+source. A Rack UI promoting a migrating version reads `…/cutover/data` (the records and their
+fingerprint), runs the steps in the [migration runner](protocol.md#the-migration-runner), checks the
+result with `POST …/cutover/check` (`{records}` → `{ok, errors, collections}`), then promotes with
+`db.records` and `db.fingerprint`. The server checks the records again inside the transaction.
+
+From the command line and over MCP a lossy plan can be confirmed but a migration cannot run:
+
+```sh
+php artisan ziprack:promote my-applet 2.0.0 --accept-data-loss
+php artisan ziprack:promote my-applet 2.0.0 --accept-data-loss --keep-invalid
+```
+
+Every cutover that changes data is preceded by a [snapshot](database.md#snapshots).
+
+**Uploading with activate.** `ziprack:install --activate`, an admin upload with `activate`, and
+MCP's `create-upload` with `activate: true` try the promotion straight after installing, with no
+cutover decision. If the cutover needs one, the version is installed but not current: the admin
+upload and the MCP upload answer `201` with a `warning` and `cutover: {reason, plan}`, and the
+command prints the refusal and exits non-zero. Promote it once the decision is made.
+
+A version that drops `db@1` still goes through the cutover: the applet's collections all count as
+removed, so promoting it needs the same confirmation as removing them one by one.
 
 What promotion means depends on pinning:
 

package/dist/docs/reporting.md

@@ -32,7 +32,8 @@ GET /ziprack/admin/applets/{applet}/panels
 ```
 
 `panels` is the intersection of what the current version declares and what this Rack implements —
-render exactly those and nothing else.
+render exactly those and nothing else. It also contains `roles` when the current version declares
+any [roles](auth.md#roles), for the screen that assigns them.
 
 | Declared | Renders |
 |---|---|
@@ -56,9 +57,10 @@ All routes sit under `ziprack-admin.prefix` (default `/ziprack/admin`) behind `w
 | `GET applets` · `POST applets` | List and create |
 | `GET applets/{applet}` · `PATCH applets/{applet}` | Show and update |
 | `GET applets/{applet}/panels` | What to render |
-| `POST versions/upload` · `POST applets/{applet}/versions` | Install a package |
+| `GET applets/{applet}/roles` · `PUT applets/{applet}/roles/{role}` | Declared roles and their assignments; replace one role's ([Roles](auth.md#rack-side)) |
+| `POST versions/upload` · `POST applets/{applet}/versions` | Install a package; with `activate`, a blocked promotion answers `201` with `warning` (and `cutover`) |
 | `GET applets/{applet}/versions/{version}` | Manifest, requires diff, SBOM, OSV findings, publisher |
-| `POST …/{version}/approve` · `…/promote` · `…/retire` | The publishing actions |
+| `POST …/{version}/approve` · `…/promote` · `…/retire` | The publishing actions. `promote` takes `force` and `db`, and answers `409` when the [data cutover](publishing.md#the-data-cutover) needs a decision |
 | `GET review-queue` | Everything awaiting a decision |
 | `GET participants` · `GET audit-log` | People and capability calls |
 
@@ -69,6 +71,8 @@ Capability packages add their own, and only when installed:
 | `GET applets/{applet}/overview` · `…/attempts` · `…/attempts/{attempt}` | `attempt` |
 | `GET applets/{applet}/attempts/{attempt}/statements` · `…/export.csv` · `…/metrics` | `activity` |
 | `GET applets/{applet}/collections` · `…/collections/{name}/records` | `db` |
+| `GET applets/{applet}/versions/{version}/cutover` · `…/cutover/data` · `POST …/cutover/check` | `db` — the cutover plan, the records migrations run on, a check of what they return |
+| `GET applets/{applet}/snapshots` · `POST …/snapshots` · `GET …/snapshots/{snapshot}/log` · `…/download` · `POST …/restore` | `db` — [snapshots](database.md#snapshots); a restore requires `confirm` set to the applet's slug |
 | `GET applets/{applet}/files` | `storage` |
 | `GET applets/{applet}/ai/spend` · `…/ai/calls` | `ai` |
 | `GET applets/{applet}/rooms` · `POST rooms` · `GET rooms/{room}` · `POST rooms/{room}/status` · `GET rooms/{room}/events` | `broadcast` |
@@ -84,7 +88,7 @@ zipRACK asks, and the Rack answers. Every check goes through one contract,
 |---|---|---|
 | `UseAdmin` | `ziprack.use-admin` | The admin API, the MCP server, personal MCP tokens |
 | `CreateApplet` | `ziprack.create-applet` | `POST applets`, `POST versions/upload`, an agent's upload without a slug |
-| `ManageApplet` | `ziprack.manage-applet` | Every `applets/{applet}` route; unpublished and `?preview` player launches |
+| `ManageApplet` | `ziprack.manage-applet` | Every `applets/{applet}` route — promoting, assigning roles, the cutover routes, taking and restoring snapshots; unpublished and `?preview` player launches |
 | `ReviewVersions` | `ziprack.review` | `GET review-queue`, approving, promoting with `force` past review |
 | `ViewRack` | `ziprack.view-rack` | `GET status`, `GET audit-log`, every participant, the `rack-status` tool |
 
@@ -188,3 +192,6 @@ The skeleton ships a reference admin over these endpoints. When you replace it:
 2. Render `db@1` record tables from the collection's declared JSON Schema — the schema is there
    precisely so the UI does not need per-applet knowledge.
 3. Treat the review queue as the landing page. It is where the decisions are.
+4. Show the cutover plan before promoting, and run migrations in the sandboxed
+   [migration runner](protocol.md#the-migration-runner). A Rack UI is the only place a version with
+   data migrations can be promoted.

package/dist/docs/sdk.md

@@ -64,8 +64,9 @@ interface LaunchData {
     applet: { slug: string; name: string; version: string };
     capabilities: string[];                  // as declared, e.g. ['auth@1', 'db@1']
     media: Record<string, MediaEmbed>;       // Rack-built player URLs by declared id
+    roles?: string[];                        // e.g. ['member', 'judge']; absent before Rack v1.8
 
-    auth?:      { user: LaunchUser };
+    auth?:      { user: LaunchUser; withheld?: string[] };
     attempt?:   { id, status, state, segment };
     activity?:  { activities: LaunchActivity[] };
     db?:        { collections: Array<{ name, scope }> };
@@ -75,9 +76,11 @@ interface LaunchData {
 }
 ```
 
-Each capability contributes its own key, and only when declared. The typed accessors read from the
-same payload, so `Rack.auth.user()`, `Rack.attempt.state()` and `Rack.activity.activities()` are
-synchronous and free.
+Each capability contributes its own key, and only when declared. `roles` is core and always
+present; read it through `Rack.auth.roles()`, `Rack.auth.hasRole(name)` and `Rack.auth.isGuest()`,
+which need no capability (see [Roles](auth.md#roles)). The typed accessors read from the same
+payload, so `Rack.auth.user()`, `Rack.auth.roles()`, `Rack.attempt.state()` and
+`Rack.activity.activities()` are synchronous and free.
 
 ```ts
 Rack.on('launch', (data) => render(data));   // fires immediately if already launched
@@ -178,6 +181,14 @@ Rack.mock.ai('score_pitch', (vars) => ({ clarity: 4, feedback: `Nice work on "${
 Rack.mock.resetAttempt();   // replay a completed attempt
 ```
 
+The mock participant is a `member` holding the manifest's `everyone` and `members` grants. Try
+other identities from the page URL:
+
+```
+http://localhost:5173/?ziprack-guest                         a guest, with the guests grants
+http://localhost:5173/?ziprack-roles=judge,applet-author     as if the Rack had assigned these
+```
+
 Mock mode also engages if a real Rack fails to answer `rack:launch` within `launchTimeoutMs`. That
 is a deliberate development convenience, and the console says so — if you see it in production,
 something is wrong with the shell, not with your applet.
@@ -214,6 +225,19 @@ it('records the answer and completes exactly once', async () => {
 | `host.attempt()`, `host.records(name)`, `host.files()` | Persisted state. |
 | `host.push(event)` | Push a `rack:event` in, as the Rack would, to drive broadcast handlers. |
 
+`new FakeHost(manifest, options)` takes the mock Rack's options. Those worth knowing:
+
+| Option | |
+|---|---|
+| `guest` | Launch as a guest: `guest` instead of `member`, and the `guests` grants. |
+| `roles` | Roles held on top of the grants, as if assigned. Any name, built-in ones included. |
+| `role` | The room role, `participant` or `facilitator`, instead of the one the assignment mode gives. |
+| `participantId`, `participantName` | The actor. |
+
+```ts
+const host = new FakeHost(manifest, { roles: ['judge'] });
+```
+
 <a name="leaving-the-applet"></a>
 ## Leaving the Applet