@ziprack/sdk 0.2.0 → 0.3.0

package/dist/auth/index.d.ts

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

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

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

package/dist/core/rack.d.ts

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

package/dist/core/types.d.ts

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

package/dist/db/index.d.ts

@@ -14,7 +14,8 @@ export interface ListQuery {
 export interface RecordRow<T extends object = JsonObject> {
     id: string;
     data: T;
-    owner_id: number;
+    /** The participant who created it; null for records seeded from the package. */
+    owner_id: number | null;
     created_at: string;
     updated_at: string;
 }

package/dist/docs/README.md

@@ -24,10 +24,10 @@ These docs cover both halves. If you are building an applet, start with
 
 ## Capabilities
 
-- [Authentication](auth.md) — `auth@1`
+- [Authentication](auth.md) — `auth@1`, and roles
 - [Attempts](attempts.md) — `attempt@1`
 - [Activity](activity.md) — `activity@1`
-- [Database](database.md) — `db@1`
+- [Database](database.md) — `db@1`, data across versions, migrations, snapshots
 - [Storage](storage.md) — `storage@1`
 - [AI](ai.md) — `ai@1`
 - [Broadcast](broadcast.md) — `broadcast@1`
@@ -37,13 +37,17 @@ These docs cover both halves. If you are building an applet, start with
 
 - [Installation](installation.md) — composing a Rack from capability packages
 - [Security](security.md) — the sandbox, the CSP, the threats it does not cover
-- [Publishing](publishing.md) — install, capability diff, review queue, promotion, kill switch
+- [Publishing](publishing.md) — install, capability diff, review queue, promotion and the data cutover, kill switch
 - [Reporting](reporting.md) — the admin API, CSV export, metrics
+- [Who may do what](reporting.md#who-may-do-what) — `AppletAccess`, abilities, applet owners
 - [Conformance](conformance.md) — proving a deployment is still a Rack
+- [The Rack MCP Server](mcp.md) — agents that read applet data and upload packages, over OAuth or minted tokens
 
 ## Extending
 
 - [Writing a Capability](extending.md) — the `Capability` interface, end to end
+- [Contributing MCP tools](mcp.md#contributing-tools) — `ProvidesMcpTools`
+- [Adding MCP tools from the Rack](mcp.md#adding-tools-from-the-rack) — `ToolRegistry`
 
 ---
 

package/dist/docs/activity.md

@@ -73,6 +73,10 @@ reads** — and fills `activity.type` from your manifest declaration. `progress(
 Verbs match `^[a-z][a-z0-9_.:-]*$`. `occurred_at` defaults to now, in ISO 8601; pass it yourself only
 when replaying something that genuinely happened earlier.
 
+A statement emitted while staff [preview](attempts.md#preview-runs) the applet is stored with
+`is_preview` set, with or without an attempt, so an audit trail can leave it out. The applet does
+nothing different.
+
 Read your own declarations when you need them:
 
 ```ts

package/dist/docs/applet-packages.md

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

package/dist/docs/attempts.md

@@ -110,7 +110,7 @@ GET /a/{slug}?preview=1      resume my open preview run
 GET /a/{slug}?preview=new    start a fresh one
 ```
 
-Both require the `ziprack.admin` ability. For anyone else the parameter is **ignored rather than
+Both require `ziprack.manage-applet` for the applet. For anyone else the parameter is **ignored rather than
 refused**, so a link pasted into a chat never dead-ends a participant on an error page.
 
 A preview run is a real attempt — same pinning, same statements, same records, same AI budget — but
@@ -133,8 +133,11 @@ The live attempt keeps `attempt_number` 1 for the lifetime of the applet; previe
 numbers above it. Starting a fresh preview never touches the live run, so you can hammer the preview
 button on an applet you have already completed for real without disturbing your own record of it.
 
-What preview does **not** do is partition capability storage. Statements and records belong to their
-attempt and follow it, but per-applet aggregates — [`ai@1`](ai.md) spend, the
+The preview comes from the launch, not the attempt, so it reaches capabilities that have no attempt
+at all. Statements and `db@1` records written during a preview carry their own `is_preview`, and the
+record browser hides them by default too (see [Reporting](reporting.md#preview-runs)).
+
+What preview does **not** do is partition every capability's storage. Per-applet aggregates — [`ai@1`](ai.md) spend, the
 [`storage@1`](storage.md) gallery — count preview activity like any other. Budget accordingly on a
 Rack where people preview a lot.
 

package/dist/docs/auth.md

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

package/dist/docs/broadcast.md

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

package/dist/docs/conformance.md

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