@ziprack/sdk 0.2.1 → 0.4.0

package/dist/ai/index.d.ts

@@ -4,15 +4,34 @@ export interface Usage {
     input_tokens: number;
     output_tokens: number;
 }
+/**
+ * Where a grounded answer's evidence came from: a passage in one of the
+ * manifest's knowledge slots. Present only on prompts bound to knowledge, and
+ * empty when nothing relevant was found or retrieval was unavailable.
+ */
+export interface Citation {
+    slot: string;
+    title: string | null;
+    ref: string | null;
+    sources: Array<{
+        title: string;
+        ref?: string;
+    }>;
+    url: string | null;
+    t_start: number | null;
+    t_end: number | null;
+}
 export interface ChatReply {
     message_id: string;
     text: string;
     usage: Usage;
+    citations?: Citation[];
 }
 export declare class Chat {
     private readonly link;
     readonly promptId: string;
-    constructor(link: Link, promptId: string);
+    private readonly vars;
+    constructor(link: Link, promptId: string, vars?: JsonObject);
     /**
      * Send a participant message. onDelta receives text as it streams; the
      * resolved result carries the full text.
@@ -30,12 +49,25 @@ export declare class AiApi {
     prompts(): Array<{
         id: string;
         mode: 'analysis' | 'chat';
+        knowledge?: string[];
+    }>;
+    /** The knowledge slots the manifest declares. Their contents stay on the Rack. */
+    knowledge(): Array<{
+        id: string;
+        label: string | null;
     }>;
-    /** Analysis prompt: structured JSON conforming to the declared output_schema. */
+    /**
+     * Analysis prompt: structured JSON conforming to the declared output_schema.
+     * A prompt bound to knowledge also returns the citations it was grounded in.
+     */
     ask<T extends object = JsonObject>(promptId: string, vars?: JsonObject): Promise<AckResult<{
         output: T;
         usage: Usage;
+        citations?: Citation[];
     }>>;
-    /** Chat prompt: conversation history is held by the Rack. */
-    chat(promptId: string): Chat;
+    /**
+     * Chat prompt: conversation history is held by the Rack. `vars` fill the
+     * template's placeholders on every turn, e.g. which persona to speak as.
+     */
+    chat(promptId: string, vars?: JsonObject): Chat;
 }

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

@@ -39,12 +39,25 @@ export interface MockManifest {
         id: string;
         mode: 'analysis' | 'chat';
         output_schema?: JsonObject;
+        knowledge?: Array<{
+            slot: string;
+        }>;
+    }>;
+    knowledge?: Array<{
+        id: string;
+        label?: string;
     }>;
     broadcast?: {
         facilitator_events?: string[];
         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 +69,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 +110,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?: {
@@ -107,10 +114,16 @@ export interface LaunchData {
             max_bytes: number;
         }>;
     };
+    /** `knowledge` lists the slots a prompt is grounded in (Racks with knowledge support). */
     ai?: {
         prompts: Array<{
             id: string;
             mode: 'analysis' | 'chat';
+            knowledge?: string[];
+        }>;
+        knowledge?: Array<{
+            id: string;
+            label: string | null;
         }>;
     };
     broadcast?: LaunchBroadcast;

package/dist/docs/README.md

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

package/dist/docs/ai.md

@@ -6,6 +6,7 @@
 - [Chat](#chat)
 - [Budgets](#budgets)
 - [Untrusted Variables](#untrusted-variables)
+- [Knowledge](#knowledge)
 - [Not This Capability](#not-this-capability)
 
 <a name="introduction"></a>
@@ -150,6 +151,89 @@ pass through, and design the template so that it would not matter:
   schema-constrained answer is a much smaller blast radius.
 - Show model output as model output. Do not render it as if it were Rack-authored guidance.
 
+<a name="knowledge"></a>
+## Knowledge
+
+A prompt can be **grounded** in documents the Rack holds: before the model is called, the Rack
+retrieves the most relevant passages and hands them over as quoted reference material. The applet
+still sends only variables — it never sees the documents, the search or the filter.
+
+Declare **slots** (named collections the Rack fills) and bind prompts to them:
+
+```json
+"knowledge": [
+    {
+        "id": "factbook",
+        "label": "Fact Book",
+        "fields": {
+            "stage": { "enum": ["s3_misdiagnosis", "s5_initial_treatment"] },
+            "stakeholders": { "type": "array", "items": { "enum": ["patient", "caregiver", "hepatologist"] } },
+            "persona_eligible": { "type": "boolean" }
+        }
+    }
+],
+"prompts": [
+    {
+        "id": "persona_chat",
+        "mode": "chat",
+        "template": "You are a composite {{persona}} from the fact book...",
+        "vars": { "type": "object", "properties": { "persona": { "enum": ["patient_neuro", "caregiver_parent"] } } },
+        "knowledge": [{
+            "slot": "factbook",
+            "top_k": 6,
+            "filter": { "persona_eligible": true },
+            "filter_by": { "persona": {
+                "patient_neuro":    { "stakeholders": { "contains": "patient" } },
+                "caregiver_parent": { "stakeholders": { "contains": "caregiver" } }
+            } }
+        }]
+    }
+]
+```
+
+| Field | Rules |
+|---|---|
+| `knowledge[].id` | Required. `^[a-z][a-z0-9_]*$`, unique. |
+| `knowledge[].source` | `rack` (the default): documents are loaded after install, from the Rack or over MCP. |
+| `knowledge[].fields` | The metadata a document may tag and a filter may use: `type` (`string`, `number`, `boolean`, `array`) and an optional `enum` (`items.enum` for arrays). `sensitivity`, `content`, `embedding`, `text` and `id` are reserved. |
+| `prompts[].knowledge[].slot` | A declared slot. Up to three per prompt. |
+| `top_k` | Passages to retrieve, up to the Rack's ceiling. |
+| `query` | Analysis prompts: what to search for, with `{{var}}` placeholders. Default: the string variables. Chat prompts search with the participant's message. |
+| `filter` | Fixed conditions: a value (equals), `{ "in": [...] }`, or `{ "contains": value }` for an array field. |
+| `filter_by` | Maps each value of an **enum** variable to more conditions. Every enum value must be mapped. This is how one prompt serves several personas without the applet writing filters. |
+
+```ts
+const coach = Rack.ai.chat('persona_chat', { persona: 'caregiver_parent' });
+const reply = await coach.send('What was the hardest moment?');
+
+reply.data?.citations;   // [{ slot, title, ref: 'slide 105', sources: [...], url, t_start, t_end }]
+Rack.ai.knowledge();     // [{ id: 'factbook', label: 'Fact Book' }]
+```
+
+**Citations** come back on every grounded call — empty when nothing relevant was found or the
+Rack's index was unavailable, in which case the model answered ungrounded. Show them; they are how a
+participant can check an answer.
+
+**Loading documents** happens on the Rack, not in the package: an author uploads to a slot from the
+applet's AI tab or with the `create-knowledge-upload` MCP tool. The Rack accepts prepared JSONL (one
+chunk per line: `id`, `text`, and optionally `context`, `title`, `ref`, `sources`, `url`, `t_start`,
+`t_end`, `sensitivity`, `metadata` using the slot's fields), Markdown, plain text, HTML, and WebVTT or
+SRT transcripts. Heavy sources — slide decks, PDFs, video — are prepared locally and arrive as JSONL
+or a transcript; the Rack never parses them. The `get-knowledge-prep-skill` MCP tool installs an
+agent skill that does that preparation, validation and loading. Chunks above the Rack's sensitivity ceiling are refused
+and never leave the Rack, and each applet can be held to a lower ceiling for retrieval.
+
+A Rack without a knowledge-capable ai package refuses a manifest with a `knowledge` section at
+install, naming the unowned section, rather than answering ungrounded.
+
+### Untrusted Passages
+
+Retrieved text is document content, not Rack instruction. It travels in a quoted `<reference>` block
+of the user message — never the system prompt — and the model is told to use it as evidence and never
+to follow instructions inside it. Delimiting reduces indirect prompt injection; it does not eliminate
+it. Load only documents you would be comfortable having quoted back to a participant, and use
+`sensitivity` to keep anything that must not be quoted out of the index altogether.
+
 <a name="not-this-capability"></a>
 ## Not This Capability
 

package/dist/docs/applet-packages.md

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

package/dist/docs/auth.md

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

package/dist/docs/broadcast.md

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

package/dist/docs/conformance.md

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