@ziprack/sdk 0.2.1 → 0.4.0

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
 

package/dist/docs/security.md

@@ -4,6 +4,7 @@
 - [The Sandbox](#the-sandbox)
 - [The Content Security Policy](#the-content-security-policy)
 - [Tokens and Sessions](#tokens-and-sessions)
+- [The Migration Runner](#the-migration-runner)
 - [Threats the Boundary Does Not Cover](#threats-the-boundary-does-not-cover)
 - [Static Analysis](#static-analysis)
 
@@ -118,12 +119,63 @@ instead of loosening the policy.
   scoped to one version, expiring after `ziprack.asset_token_ttl_hours` (6). The extraction disk is
   never publicly served.
 - **Launch session.** Capability calls go to `/ziprack/s/{session}/messages` with a token in the
-  path — no session cookie, no CSRF, stateless by design, rate limited, expiring after
-  `ziprack.session_ttl_hours` (6). The session is what binds a message to a participant, a version,
+  path — no Laravel session, no CSRF, rate limited, expiring after
+  `ziprack.session_ttl_hours` (6). The token is bound to the launching browser: the launch sets a
+  random host-only, HttpOnly, SameSite=Lax `ziprack_launch` cookie (never shared with sibling subdomains), the token carries its hash, and every
+  session request must present the matching cookie. A token seen in page source, a screenshot or
+  a proxy log cannot be replayed from anywhere else. Logging in or out starts a new cookie, so the next person on a shared
+  browser cannot use the previous user's open sessions. The session is what binds a message to a participant, a version,
   an attempt and a room; nothing in the payload can widen that scope.
 - **Signed file URLs.** `storage@1` hands out short-lived URLs, never object keys.
-- **Channel authentication.** The Rack signs its own WebSocket subscriptions. No token reaches the
-  frame.
+- **Channel authentication.** The Rack signs its own WebSocket subscriptions, and stops signing
+  them for a room once it is closed. No token reaches the frame.
+
+<a name="the-migration-runner"></a>
+## The Migration Runner
+
+[Data migrations](database.md#data-migrations) are package code too, and they run outside the
+applet frame: in the browser of the admin promoting the version, over the applet's whole dataset.
+Two things contain them.
+
+**The runner page has no network.** `GET /ziprack/migration-runner` is served with
+
+```
+default-src 'none'; script-src 'unsafe-inline' blob:; style-src 'unsafe-inline';
+connect-src 'none'; img-src 'none'; font-src 'none'; frame-src 'none'; worker-src blob:;
+form-action 'none'; base-uri 'none'; frame-ancestors 'self'; sandbox allow-scripts
+```
+
+and migration code never runs in its window. The page starts a dedicated worker from a `blob:` URL,
+which inherits that CSP, and the worker imports each migration from a `blob:` URL and runs it. A
+worker has no document, no forms and no writable `location`, so migration code cannot navigate a
+frame or a window to carry the data out in a URL, which a CSP alone cannot stop. Under the CSP it
+cannot fetch or open a socket either, and the worker also removes `fetch`, `XMLHttpRequest`,
+`WebSocket`, `EventSource`, `WebTransport` and `importScripts` before it imports anything. Its only
+way out is `postMessage` to the runner page, which relays to the page that framed it. A worker that
+stops responding is terminated. The page holds no data until that parent posts some in, and is never
+publishable.
+
+**It always runs sandboxed.** The runner is served from the Rack's own origin, so its CSP carries
+`sandbox allow-scripts`: the browser gives the page an opaque origin however it is framed, and
+migration code cannot reach `window.parent`, the admin's session or the admin API. A Rack UI
+should still frame it with `sandbox="allow-scripts"` (and never `allow-same-origin`), exactly as
+it frames an applet, so the isolation does not rest on one header.
+
+**Migrations are privileged.** A migration is handed every carried record of the applet, in every
+`user`, `room` and `applet` scope, and can rewrite any of them. It is trusted the way the package's
+server-side declarations are, not the way applet code is: promoting a version that runs migrations is
+an admin's decision to run that code over everyone's data. The plan carries each migration's source
+(`GET …/versions/{version}/cutover`), so it can be read before it runs.
+
+**The server checks the shape of what comes back.** What the migrations return is checked before it
+replaces any data, and again inside the promotion's transaction: the whole resulting dataset,
+collections left out included, must match the target schema and quota; `scope_id` and `owner_id`
+cannot change; a record moves only between collections of the same scope; a new `user` or `room`
+record must name a scope that already has records, and no owner or one who already owns a record.
+These keep every record where it was, but they cannot tell whose values a record holds: a migration
+could copy or swap values between two participants' records and pass. What a migration cannot do is
+send the data anywhere, reach another applet's data, or see `attempt` and preview records. And the
+data it replaced is in the [snapshot](database.md#snapshots) taken before the cutover.
 
 <a name="threats-the-boundary-does-not-cover"></a>
 ## Threats the Boundary Does Not Cover
@@ -140,6 +192,11 @@ per month — never advisory numbers.
 **Record and storage flooding.** Per-scope quotas, declared in the manifest and capped by the
 deployment regardless of what the manifest asks for.
 
+**Trusting roles.** An applet's [roles](auth.md#roles) arrive in the launch payload and are read by
+applet code, which runs in the participant's browser. No capability enforces them server-side yet,
+so a role is a reason to show a control, not a permission. Keep anything a role must protect behind
+a scope, a `permissions` rule or a facilitator event, which the Rack does enforce.
+
 **Supply chain.** The SBOM is self-attested. OSV findings catch negligence; the
 [capability diff](publishing.md#capability-diff-review) is what catches the realistic attack, which
 is a benign v1 followed by a quietly wider v2.

package/dist/docs/storage.md

@@ -29,7 +29,7 @@ An **upload** is a named slot with a scope and a MIME allowlist. Files always be
 | Field | Rules |
 |---|---|
 | `name` | Required. `^[a-z][a-z0-9_]*$`, max 40, unique. |
-| `scope` | Required. `attempt`, `user`, `room` or `applet`. Same meaning as [db scopes](database.md#scopes). |
+| `scope` | Required. `attempt`, `user`, `room` or `applet`. Same meaning as [db scopes](database.md#scopes), with one difference: an `applet` slot still belongs to the version, so its files do not carry over to the next one. |
 | `mime` | Required, at least one. `type/subtype` or `type/*`. |
 | `max_bytes` | Optional. Default 10 MB, ceiling 50 MB (`ziprack-storage.max_bytes_cap`). |
 | `max_files` | Optional. Default 20, ceiling 500. |

package/dist/docs/studio.md

@@ -349,7 +349,7 @@ produces is a document a non-technical colleague can then open and edit.
 | `ziprack_compose` | Build a tree from a structure-only skeleton plus content maps. |
 | `ziprack_patch` | `create`, `delete`, `move`, `duplicate`, `props`, `style`, `label`, `settings`, `applet`, `theme`. |
 | `ziprack_validate` | Per-key errors, each with the schema that would have been valid. |
-| `ziprack_derive_manifest` | The manifest this document produces, plus a capability diff against the last build. |
+| `ziprack_derive_manifest` | The manifest this document produces, plus a capability diff and promotion warnings against the last build: `needs_approval`, `pinning_changed`, `activity_id_changed`, `activity_removed`, `collection_removed`, `collection_changed`. |
 
 The SDK's docs tools (`ziprack_guidelines`, `ziprack_list_docs`, `ziprack_search_docs`,
 `ziprack_read_doc`) are served alongside these. See [the SDK's MCP server](sdk.md#the-mcp-server).

package/dist/docs/versioning.md

@@ -99,3 +99,19 @@ Between versions:
 - Adding a capability or a profile attribute blocks promotion until approved.
 - Adding or removing `attempt@1` flips the applet between pinned and rolling, and is flagged
   prominently in the diff.
+- Adding, dropping or reshaping a collection is checked against the data at promotion.
+
+### Applet versions and data
+
+Versions are immutable; data is not. `db@1` records in `user`, `room` and `applet` scope belong to
+the applet and carry over every promotion, forward or back, so a new version starts from the data
+the last one left. `attempt` records stay with their attempt and the version it ran on.
+
+What changes between versions is the *shape* the data must have. At promotion the Rack compares the
+outgoing collections with the new ones, validates the existing records against the new schemas, and
+refuses to lose data silently: a version whose schema rejects existing records, or that drops a
+collection holding records, waits for an explicit confirmation. A version that needs records
+reshaped ships a [data migration](database.md#data-migrations) with `up` and `down`, which the Rack
+runs at promotion and records per applet, and every cutover that changes data is preceded by a
+[snapshot](database.md#snapshots). [Data Across Versions](database.md#data-across-versions) has the
+full list of cases.

package/dist/docs/ziprack-1-authoring.md

@@ -17,8 +17,9 @@ Follow this document exactly. The Rack rejects packages and messages that break
 | Attempt | One participant's run (`attempt@1`). Pinned to the version it started on. Holds `status`, `state`, `segment`. |
 | Room | A shared session: an applet plus its participants (`broadcast@1`). Two roles: `participant`, `facilitator`. |
 | Statement | Append-only "actor did verb on activity with result" (`activity@1`). The audit trail and the uniform export. |
-| Record | A mutable row in a declared collection at a declared scope (`db@1`). Working state. |
+| Record | A mutable row in a declared collection at a declared scope (`db@1`). Working state. Carries over to every new version, except `attempt` scope. |
 | Profile attribute | A Rack-owned fact about the participant, released only if declared and permitted (`auth@1`). |
+| Role | A name the participant holds in this applet: `member` or `guest`, `applet-author`, `rack-administrator`, plus the manifest's own `roles` the Rack grants or assigns. Sent at launch; no capability. |
 
 Rules that do not bend:
 
@@ -27,6 +28,7 @@ Rules that do not bend:
 3. **Answers are statements, not state.** State is for resuming position. Every committed answer is `Rack.activity.answer()`.
 4. **Resume must work.** Read `Rack.attempt.state()` and `Rack.attempt.status` at launch and put the participant back where they were.
 5. **Degrade gracefully.** A requested profile attribute may be withheld. A room may have no facilitator yet. Design for absence.
+6. **Your data outlives your version.** `user`, `room` and `applet` records carry over every promotion. Change a collection's shape compatibly, or ship a data migration.
 
 ## 2. Package layout
 
@@ -35,6 +37,7 @@ Rules that do not bend:
 ├── 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, YYYY_MM_DD_HHMMSS_name.js, kept forever
 └── assets/…             everything the entry references, by RELATIVE path
 ```
 
@@ -71,6 +74,7 @@ Installer rules: static files only (`html js mjs css map json wasm txt vtt svg p
 | `requires.capabilities` | Required (may be empty). Each `id@version`; the Rack must implement every one. |
 | `requires.profile` | Attribute keys, only with `auth@1`. Withheld keys are simply absent. |
 | `media[]` | `provider` in the Rack's allowlist (vimeo, youtube); `key` `^\d+$` (Vimeo) or `^[\w-]{11}$` (YouTube). The Rack builds the URL. |
+| `roles[]` | Optional, no capability. `{name, label?, description?, grant?}`, max 20. `name` `^[a-z][a-z0-9]*(-[a-z0-9]+)*$`, max 40, not `rack-administrator`, `applet-author`, `member` or `guest`. `grant`: `everyone`, `members`, `guests` or `assigned` (default: only whom the Rack assigns). |
 
 Every other top-level block belongs to a capability and is invalid unless that capability is declared:
 
@@ -78,12 +82,37 @@ Every other top-level block belongs to a capability and is invalid unless that c
 |---|---|---|
 | `segments[]` | `attempt@1` | `{key, label, values[{key,label}]}`; the first segment drives admin filtering |
 | `activities[]`, `reporting.metrics[]` | `activity@1` | as in cn-sim/1: `{id, type, label, scale?, segment?, sequence?}`; metrics pair a pre and post rating and need `attempt@1` |
-| `collections[]` | `db@1` | `{name, scope, schema, indexed?, quota?, permissions?}` |
+| `collections[]` | `db@1` | `{name, scope, schema, indexed?, quota?, permissions?, seed?}`; `seed` (applet scope only) loads at promotion into an empty collection |
 | `uploads[]` | `storage@1` | `{name, scope, mime[], max_bytes?, max_files?}` |
 | `prompts[]` | `ai@1` | `{id, mode, template, vars?, output_schema?, budget?}` |
 | `broadcast` | `broadcast@1` | `{channels?, facilitator_events?}` |
 
-Scopes (`db@1`, `storage@1`): `attempt` (frozen at completion; needs `attempt@1`), `user` (outlives attempts), `room` (shared; needs `broadcast@1`), `applet` (per version, read-mostly).
+Scopes (`db@1`, `storage@1`): `attempt` (frozen at completion; needs `attempt@1`), `user` (outlives attempts), `room` (shared; needs `broadcast@1`), `applet` (shared by everyone; read-mostly). In `db@1`, `user`, `room` and `applet` records belong to the applet and carry over every promotion; `attempt` records stay with their attempt. `storage@1` applet slots are still per version.
+
+### Data across versions
+
+When a new version changes a collection, the Rack validates the existing records against the new
+schema at promotion and refuses to lose any silently: rejected records, a dropped collection that
+holds records, or a lowered quota wait for an admin to confirm. A scope cannot change; use a new
+collection name. To reshape existing records, ship a data migration in `migrations/`:
+
+```js
+// migrations/2026_10_09_120000_add_difficulty.js
+export function up(db, ctx) {           // db: { collection: [{ id, scope_id, owner_id, data, created_at, updated_at }] }
+    for (const q of db.questions) q.data.difficulty ??= 'medium';
+    ctx.log('back-filled difficulty');
+}
+export function down(db) {              // runs if someone rolls back to a version without this file
+    for (const q of db.questions) delete q.data.difficulty;
+}
+```
+
+Mutate `db` in place or return `{ collection: records[] }`; a returned collection replaces that
+collection (missing records are deleted), others are kept. Migrations run in the browser of the
+admin promoting, with no network: no imports, no `fetch`. The Rack rejects the whole result if any
+record breaks the new schema or quota, changes `scope_id` or `owner_id`, or moves to a collection of
+another scope. Keep every migration you ever ship; the Rack runs only those not yet applied. A
+snapshot is taken before every cutover. `attempt` and preview records are never passed in.
 
 ## 4. The SDK
 
@@ -96,7 +125,7 @@ const launch = await Rack.init({ slug: 'my-applet' });   // mock mode when not i
 | Namespace | Calls | Notes |
 |---|---|---|
 | `Rack` | `init()`, `on('launch'|'event')`, `mode`, `eject()` | `eject()` needs no capability |
-| `Rack.auth` | `user()`, `attribute(key, fallback)` | Released profile from launch data |
+| `Rack.auth` | `user()`, `attribute(key, fallback)`, `roles()`, `hasRole(name)`, `isGuest()` | Released profile from launch data (`auth@1`). Roles need no capability, and **nothing enforces them server-side**: use them to choose what to render, not to protect data |
 | `Rack.attempt` | `status`, `state()`, `segment()`, `setState()`, `setSegment()`, `complete()` | State max 64 KB; `complete()` idempotent; after it, state and segment are refused with `completed` |
 | `Rack.activity` | `answer(id, value)`, `progress(stepId)`, `statement({...})` | Verbs `^[a-z][a-z0-9_.:-]*$`; answers put the value in `result.response` |
 | `Rack.db.collection(name)` | `create`, `get`, `update`, `delete`, `list`, `count` | Filters and sorting only on `indexed` paths; 100 per page |
@@ -106,7 +135,7 @@ const launch = await Rack.init({ slug: 'my-applet' });   // mock mode when not i
 | `Rack.media` | `embedUrl(id)` | Rack-built player URL |
 
 Every call resolves to `{ ok, data?, error?, message? }` and never throws. Error codes: `timeout`,
-`persist_failed`, `undeclared_capability`, `unknown_type`, `validation`, `forbidden`, `completed`,
+`disposed`, `persist_failed`, `undeclared_capability`, `unknown_type`, `validation`, `forbidden`, `completed`,
 `quota_exceeded`, `budget_exceeded`, `not_found`, `conflict`. Do not block the participant on acks;
 `await` only what you must confirm (for example the final answer before `complete()`).
 
@@ -116,10 +145,13 @@ Outside a Rack (`npm run dev`), or if the Rack does not answer within 3 s, the S
 that reads `./manifest.json` so declared capabilities, activities, collections and prompts behave as
 they will in production. State and records persist in `localStorage` under `ziprack-mock:{slug}:*`.
 Rooms use `BroadcastChannel`, so two tabs of your dev server form a room. `Rack.mock.ai(promptId, fn)`
-answers prompts yourself; `Rack.mock.resetAttempt()` replays a completed attempt.
+answers prompts yourself; `Rack.mock.resetAttempt()` replays a completed attempt. The mock
+participant is a `member`; add `?ziprack-guest` to the URL to launch as a guest, and
+`?ziprack-roles=judge,applet-author` to hold those roles.
 
 For tests, `import { FakeHost } from '@ziprack/sdk/testing'` and pass `host.transport()` to
 `Rack.init({ transport })`; then inspect `host.statements`, `host.answers()`, `host.records()`.
+`new FakeHost(manifest, { guest: true, roles: ['judge'] })` sets the identity.
 
 ## 5. Studio, and its MCP server
 
@@ -169,7 +201,9 @@ Uploads land unpublished. Promoting a version is a deliberate admin action. A ne
 capability or a profile attribute waits for explicit approval; adding or removing `attempt@1` changes
 the applet from rolling to pinned (or back) and is flagged prominently. Known vulnerabilities from your
 SBOM appear in the review queue. Changing an activity `id` between versions splits export columns;
-changing a `label` only changes headers.
+changing a `label` only changes headers. Collection changes are checked against the live data at
+promotion (see *Data across versions*); a version with migrations is promoted from the Rack's UI,
+where they run.
 
 ## 8. Pre-upload checklist
 
@@ -178,5 +212,7 @@ changing a `label` only changes headers.
 - [ ] Every question has an `activities[]` entry with a stable `id`, a `type`, a full-sentence `label`.
 - [ ] `setState()` after every transition; refreshing mid-way in mock mode resumes.
 - [ ] `complete()` exactly once; reloading a completed attempt shows the final screen.
+- [ ] Changed a collection's schema? Existing records still validate, or a migration in `migrations/` reshapes them (with `down`).
+- [ ] Every role-gated control also works for someone without the role, and nothing secret depends on a role.
 - [ ] All URLs relative, no external `<script>`, no external images or APIs.
 - [ ] Layout works at phone width and leaves the Rack bar alone.

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export { HostBridge } from './core/bridge';
 export type { AnswerOptions, StatementInput } from './activity';
 export type { Collection, ListQuery, ListResult, RecordRow, WhereClause, WhereOperator } from './db';
 export type { StoredFile, FileStatus } from './storage';
-export type { Chat, ChatReply, Usage } from './ai';
+export type { Chat, ChatReply, Citation, Usage } from './ai';
 export type { Channel, RoomEventName, RoomEvents } from './broadcast';
 export type { MockManifest, AiMockHandler } from './core/mock/MockRack';
 /** The singleton every applet talks through. */