@ziprack/sdk 0.2.1 → 0.3.0

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)
 
@@ -125,6 +126,53 @@ instead of loosening the policy.
 - **Channel authentication.** The Rack signs its own WebSocket subscriptions. 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 +188,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.js

@@ -1,5 +1,5 @@
-import { n as f, c as h, i as g, a as u, M as l, b as w, L as b } from "./store-BXGon4iJ.js";
-import { F as K, P as V, d as W } from "./store-BXGon4iJ.js";
+import { n as f, c as h, i as g, a as u, M as l, b as w, L as b } from "./store-DQbG_t2D.js";
+import { F as K, P as V, d as W } from "./store-DQbG_t2D.js";
 class v {
   constructor(t) {
     this.link = t;
@@ -113,7 +113,7 @@ class L {
     return e.ok && (this.local.status = "completed"), e;
   }
 }
-class A {
+class R {
   constructor(t) {
     this.link = t;
   }
@@ -125,8 +125,23 @@ class A {
     const s = this.user();
     return !s || !(t in s) ? e : s[t];
   }
+  /**
+   * 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() {
+    return this.link.launch()?.roles ?? [];
+  }
+  hasRole(t) {
+    return this.roles().includes(t);
+  }
+  /** Whether the participant is a guest rather than a signed-in Rack user. */
+  isGuest() {
+    return this.hasRole("guest");
+  }
 }
-const R = "$room";
+const A = "$room";
 class E {
   constructor(t, e) {
     this.link = t, this.name = e, this.listeners = /* @__PURE__ */ new Map(), this.unsubscribe = null;
@@ -152,7 +167,7 @@ class E {
     return this.unsubscribe?.(), this.unsubscribe = null, this.listeners.clear(), this.link.send("broadcast:leave", { channel: this.name });
   }
 }
-class T {
+class S {
   constructor(t) {
     this.link = t, this.channels = /* @__PURE__ */ new Map(), this.roomListeners = /* @__PURE__ */ new Map(), this.localRole = null, this.localMembers = null, this.localState = null, this.detach = null, this.state = {
       /** Server-arbitrated shared state. */
@@ -219,7 +234,7 @@ class T {
   }
   ensureRoomListener() {
     this.detach ??= this.link.onEvent((t) => {
-      if (t.channel !== R)
+      if (t.channel !== A)
         return;
       const e = t.payload;
       t.event === "presence" && Array.isArray(e.members) && (this.localMembers = e.members), t.event === "state" && typeof e.key == "string" && (this.localState = { ...this.localState ?? this.launch()?.state ?? {}, [e.key]: e.value }), t.event === "role" && e.participant_id === this.link.launch()?.actor.id && (this.localRole = e.role), this.roomListeners.get(t.event)?.forEach((s) => s(e));
@@ -229,7 +244,7 @@ class T {
 function d(r) {
   return { ok: !1, error: "undeclared_capability", message: `The manifest does not declare the [${r}] capability.` };
 }
-class S {
+class T {
   constructor(t, e) {
     this.link = t, this.name = e;
   }
@@ -261,7 +276,7 @@ class D {
     this.link = t;
   }
   collection(t) {
-    return new S(this.link, t);
+    return new T(this.link, t);
   }
   collections() {
     return this.link.launch()?.db?.collections ?? [];
@@ -380,16 +395,16 @@ class P {
       return;
     }
     if (t.partial && !t.done) {
-      const { requestId: F, ok: U, partial: $, ...k } = t;
+      const { requestId: F, ok: j, partial: $, ...k } = t;
       e.onPartial?.(k), clearTimeout(e.timer), e.timer = setTimeout(() => this.expire(t.requestId), e.timeoutMs);
       return;
     }
     clearTimeout(e.timer), this.pending.delete(t.requestId);
-    const { requestId: s, ok: n, data: i, error: a, message: o, details: p, partial: C, done: j, ...c } = t;
+    const { requestId: s, ok: n, data: i, error: a, message: o, details: p, partial: U, done: z, ...c } = t;
     e.resolve({ ok: n, data: i ?? (Object.keys(c).length ? c : void 0), error: a, message: o, details: p });
   }
 }
-const q = 3e3, I = 5e3;
+const I = 3e3, q = 5e3;
 class m {
   constructor() {
     this.transport = null, this.initPromise = null, this.launchData = null, this.queue = [], this.launchListeners = /* @__PURE__ */ new Set(), this.eventListeners = /* @__PURE__ */ new Set(), this.pendingAiMocks = [];
@@ -401,7 +416,7 @@ class m {
       onEvent: (e) => this.on("event", e),
       mode: () => this.mode
     };
-    this.auth = new A(t), this.attempt = new L(t), this.activity = new v(t), this.db = new D(t), this.storage = new O(t), this.ai = new M(t), this.broadcast = new T(t), this.media = new _(t), this.mock = {
+    this.auth = new R(t), this.attempt = new L(t), this.activity = new v(t), this.db = new D(t), this.storage = new O(t), this.ai = new M(t), this.broadcast = new S(t), this.media = new _(t), this.mock = {
       ai: (e, s) => {
         const n = this.mockRack();
         n ? n.mockAi(e, s) : this.pendingAiMocks.push([e, s]);
@@ -464,7 +479,7 @@ class m {
     this.transport?.dispose(), this.transport = null, this.initPromise = null, this.launchData = null;
   }
   async performInit(t) {
-    const e = t.ackTimeoutMs ?? I, s = t.launchTimeoutMs ?? q;
+    const e = t.ackTimeoutMs ?? q, s = t.launchTimeoutMs ?? I;
     if (t.transport) {
       const o = t.launch ?? (t.transport instanceof l ? t.transport.rack.launchData() : null);
       if (!o)
@@ -481,7 +496,8 @@ class m {
   async activateMock(t, e) {
     console.info(`[ziprack] running in mock mode (${e})`);
     const s = await x(t.manifestUrl ?? "./manifest.json", t.slug), n = new w(s, new b(), {
-      log: (i, a) => console.info(`[ziprack mock] ${i}`, a)
+      log: (i, a) => console.info(`[ziprack mock] ${i}`, a),
+      ...C()
     });
     for (const [i, a] of this.pendingAiMocks)
       n.mockAi(i, a);
@@ -514,8 +530,15 @@ async function x(r, t) {
     return console.warn(`[ziprack mock] could not load ${r}; mock mode will accept every capability.`, e), null;
   }
 }
-const H = new m();
-function N() {
+function C(r = typeof location > "u" ? "" : location.search) {
+  const t = new URLSearchParams(r), e = (t.get("ziprack-roles") ?? "").split(",").map((s) => s.trim()).filter((s) => s !== "");
+  return {
+    ...e.length > 0 ? { roles: e } : {},
+    ...t.has("ziprack-guest") ? { guest: t.get("ziprack-guest") !== "0" } : {}
+  };
+}
+const N = new m();
+function B() {
   return new m();
 }
 export {
@@ -523,8 +546,8 @@ export {
   P as HostBridge,
   V as PROTOCOL_NAMESPACE,
   W as PROTOCOL_VERSION,
-  H as Rack,
+  N as Rack,
   m as RackClient,
-  N as createRack
+  B as createRack
 };
 //# sourceMappingURL=index.js.map