@ziprack/sdk 0.1.2 → 0.2.1

package/dist/docs/publishing.md

@@ -0,0 +1,127 @@
+# Publishing
+
+- [Introduction](#introduction)
+- [Installing a Version](#installing-a-version)
+- [Capability Diff Review](#capability-diff-review)
+- [Promotion](#promotion)
+- [The Review Queue](#the-review-queue)
+- [Retiring a Version](#retiring-a-version)
+- [The Audit Log](#the-audit-log)
+
+<a name="introduction"></a>
+## Introduction
+
+`cn-sim/1` assumed CN authored every package. Accepting client-authored applets changes the problem
+from untrusted *content* to untrusted *code*, and that calls for process rather than more sandboxing.
+
+The pipeline is deliberately boring: every upload lands inactive, a human promotes it, and anything
+that widens what the applet can reach needs an explicit approval first.
+
+<a name="installing-a-version"></a>
+## Installing a Version
+
+```sh
+php artisan ziprack:install dist-zip/my-applet-1.0.0.zip
+php artisan ziprack:install dist-zip/my-applet-1.0.0.zip --activate   # install and promote
+```
+
+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.
+
+Once files are extracted 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.
+
+<a name="capability-diff-review"></a>
+## Capability Diff Review
+
+**This is the control that actually holds.** When a new version of an existing applet is uploaded,
+the Rack diffs its `requires` block against the current version:
+
+```json
+{
+    "added": ["ai@1", "db@1"],
+    "removed": [],
+    "profile_added": ["business_unit"],
+    "profile_removed": [],
+    "pinning_changed": true,
+    "pinned": true
+}
+```
+
+Any addition — a capability or a profile attribute — blocks promotion until someone approves it.
+This is the Android permissions model, and it catches the realistic attack: a benign v1 that earns
+trust, followed by a v2 that quietly widens its reach.
+
+`pinning_changed` is flagged just as prominently, because adding or removing `attempt@1` changes the
+applet's own update semantics from rolling to pinned or back. See
+[Version Pinning](attempts.md#version-pinning).
+
+Removals need no approval. Narrowing what an applet can reach is always allowed.
+
+<a name="promotion"></a>
+## Promotion
+
+```sh
+php artisan ziprack:promote my-applet 1.1.0
+php artisan ziprack:promote my-applet 1.1.0 --force    # approve the pending review, then promote
+```
+
+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.
+
+What promotion means depends on pinning:
+
+- **Rolling applet** (no `attempt@1`): everyone is on the new version at their next page load.
+- **Pinned applet** (`attempt@1`): new attempts start on the new version; in-progress attempts stay
+  on the one they started on until they complete. Two versions run side by side until the old one
+  drains.
+
+<a name="the-review-queue"></a>
+## The Review Queue
+
+`GET /ziprack/admin/review-queue` collects everything awaiting a human decision rather than hiding
+it behind a modal:
+
+- Versions requesting new capabilities or profile attributes
+- OSV findings from the SBOM
+- The first upload from a publisher
+- Manifest validation warnings that were overridden
+
+A version's own page (`GET /ziprack/admin/applets/{applet}/versions/{version}`) carries the diff,
+the SBOM summary, the findings and the publisher.
+
+Each version records an attributable publisher, so a bad version can be traced and that publisher's
+other applets reviewed.
+
+<a name="retiring-a-version"></a>
+## Retiring a Version
+
+The kill switch:
+
+```sh
+php artisan ziprack:retire my-applet 1.1.0
+```
+
+A retired version can no longer be launched. In-progress attempts pinned to it land on a holding
+screen — a defined state with an explanation, not a blank frame. Retiring the current version leaves
+the applet with no current version until another is promoted, which is deliberate: the operator
+decides what to fall back to.
+
+<a name="the-audit-log"></a>
+## The Audit Log
+
+With `ziprack.audit.enabled` on, capability calls are recorded per applet — type, participant,
+outcome — excluding the high-volume types each capability already persists (`activity:statement`,
+`attempt:state`, `broadcast:heartbeat`). Read it at `GET /ziprack/admin/audit-log`.
+
+This is what an incident response actually needs: what the applet asked for, when, and what the Rack
+answered. AI spend and quota usage are reported alongside it per applet.

package/dist/docs/reporting.md

@@ -0,0 +1,190 @@
+# Reporting
+
+- [Composition](#composition)
+- [The Admin API](#the-admin-api)
+- [Who May Do What](#who-may-do-what)
+- [Preview Runs](#preview-runs)
+- [The CSV Export](#the-csv-export)
+- [Metrics](#metrics)
+- [Response Analysis](#response-analysis)
+- [Building a UI](#building-a-ui)
+
+<a name="composition"></a>
+## Composition
+
+`ziprack/admin` is **headless**: JSON endpoints, export and report services, no pages. The
+deployment skeleton owns the UI, and replacing it entirely is expected — the API is the contract,
+the pages are not.
+
+The admin composes from declared capabilities rather than assuming every applet is a simulation.
+Ask a Rack what to render:
+
+```http
+GET /ziprack/admin/applets/{applet}/panels
+```
+
+```json
+{
+  "declared": ["activity@1", "attempt@1", "auth@1"],
+  "panels": ["activity", "attempt", "auth"],
+  "implemented": ["activity@1", "ai@1", "attempt@1", "auth@1", "broadcast@1", "db@1", "storage@1"]
+}
+```
+
+`panels` is the intersection of what the current version declares and what this Rack implements —
+render exactly those and nothing else.
+
+| Declared | Renders |
+|---|---|
+| `attempt@1` | Attempts started and completed, completion rate, metric cards |
+| `activity@1` | Statement log per attempt; CSV export |
+| `db@1` | Record browser per collection, from the declared JSON Schema |
+| `storage@1` | Uploaded artifact gallery, scoped and permissioned |
+| `ai@1` | Per-prompt spend and call volume |
+| `broadcast@1` | Room history, participation by role, facilitator timeline |
+
+<a name="the-admin-api"></a>
+## The Admin API
+
+All routes sit under `ziprack-admin.prefix` (default `/ziprack/admin`) behind `web`, `auth` and the
+`ziprack.use-admin` gate. Every route with an `{applet}`, including capability routes, also requires
+`ziprack.manage-applet` for that applet. See [Who May Do What](#who-may-do-what).
+
+| Route | Purpose |
+|---|---|
+| `GET status` | Format, core version, capabilities, warnings |
+| `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}/versions/{version}` | Manifest, requires diff, SBOM, OSV findings, publisher |
+| `POST …/{version}/approve` · `…/promote` · `…/retire` | The publishing actions |
+| `GET review-queue` | Everything awaiting a decision |
+| `GET participants` · `GET audit-log` | People and capability calls |
+
+Capability packages add their own, and only when installed:
+
+| Route | Capability |
+|---|---|
+| `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}/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` |
+| `GET participants/{participant}/profile` · `PUT …` | `auth` |
+
+<a name="who-may-do-what"></a>
+## Who May Do What
+
+zipRACK asks, and the Rack answers. Every check goes through one contract,
+`ZipRack\Core\Contracts\AppletAccess`, with the applet in hand when there is one:
+
+| Ability | Gate | Asked for |
+|---|---|---|
+| `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 |
+| `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 |
+
+`scopeVisible()` narrows the applet list, the MCP tools' slug lookups and `list-applets` to what
+the user may see. An applet they may not see reads as not installed.
+
+The default binding, `AdminOnlyAccess`, answers every ability with the `ziprack.admin` gate
+(`$user->is_admin`), so a Rack that binds nothing, or only redefines that gate, behaves as before.
+A Rack with other roles binds its own:
+
+```php
+$this->app->singleton(AppletAccess::class, RackAppletAccess::class);
+```
+
+Applets have an **owner**, a morph like a version's publisher: whoever published the first
+version, or created the empty applet. `$applet->isOwnedBy($user)` is the usual basis for
+`ManageApplet`. A package whose slug already belongs to an applet the publisher cannot manage is
+refused, so an upload cannot land in someone else's applet.
+
+**Participants** are Rack-wide. A user with `ViewRack` sees all of them; anyone else sees the
+participants with audit-log entries on an applet they can see, through `GET participants` and the
+`auth` profile routes. `ZipRack\Core\Access\ParticipantVisibility` applies the rule.
+
+To react to publishing, listen for `ZipRack\Core\Events\VersionInstalled` (with the publisher),
+`VersionApproved` and `VersionPromoted`.
+
+<a name="preview-runs"></a>
+## Preview Runs
+
+Every attempt query above — the table, the overview counts, the metric cards and the CSV export —
+returns **live attempts only** unless told otherwise:
+
+| `?preview=` | Returns |
+|---|---|
+| *(absent)* · `live` | Real runs. The default, and what a report should almost always show. |
+| `preview` | Staff [preview runs](attempts.md#preview-runs) only |
+| `all` | Both, with `is_preview` on each row to tell them apart |
+
+An unrecognised value falls back to `live` rather than erroring, so a stale bookmark cannot quietly
+turn preview data into a report.
+
+The `db@1` record browser (`…/collections` and `…/collections/{name}/records`) takes the same
+`?preview=` with the same default, and the collection `records` counts follow it. `ziprack_statements`
+and `ziprack_records` both carry an `is_preview` column set from the launch session, so preview data
+is saved, never mixed in, and easy to delete in one query when you want it gone.
+
+<a name="the-csv-export"></a>
+## The CSV Export
+
+`GET /ziprack/admin/applets/{applet}/export.csv` produces one row per attempt:
+
+```
+ID, Name, Email, {first segment label}, Status, Started At, Completed At,
+{declared activities in sequence order, headed by label},
+{undeclared activity ids that appeared, appended}
+```
+
+Each activity cell is the **last** `result.response` for that activity in that attempt; non-scalar
+values are JSON-encoded, and duplicate labels are disambiguated so the header row stays usable.
+
+This is the one artifact every applet declaring `activity@1` produces identically, which is what
+makes it worth protecting. The authoring consequences are covered in
+[Designing for the Export](activity.md#designing-for-the-export) and are unchanged from `cn-sim/1`:
+`id` is the data contract, `label` is the header, renaming either has consequences.
+
+<a name="metrics"></a>
+## Metrics
+
+`GET /ziprack/admin/applets/{applet}/metrics` computes each declared
+[metric](activity.md#metrics) over completed attempts: the pre mean, the post mean and the shift,
+sliceable by the primary segment. Metrics need `attempt@1` as well as `activity@1`, which the
+manifest validator enforces at upload rather than leaving to discover at report time.
+
+<a name="response-analysis"></a>
+## Response Analysis
+
+The admin can summarise free-text answers across attempts:
+
+```sh
+php artisan ziprack:response-analysis --applet=my-applet
+```
+
+```http
+GET  /ziprack/admin/applets/{applet}/response-analysis
+POST /ziprack/admin/applets/{applet}/response-analysis/refresh
+```
+
+Summaries regenerate only for applets whose answers changed; schedule the command every few hours.
+
+**This is a Rack feature, not an applet capability.** It operates on collected statements from any
+applet declaring `activity@1`, whether or not that applet uses [`ai@1`](ai.md). The two are budgeted
+and configured separately, and conflating them is the mistake this note exists to prevent.
+
+<a name="building-a-ui"></a>
+## Building a UI
+
+The skeleton ships a reference admin over these endpoints. When you replace it:
+
+1. Call `/panels` first and render from the answer. Hard-coding panels breaks the moment a Rack runs
+   a different capability set.
+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.

package/dist/docs/sdk.md

@@ -0,0 +1,258 @@
+# The JavaScript SDK
+
+- [Installation](#installation)
+- [Booting](#booting)
+- [Launch Data](#launch-data)
+- [Acks and Errors](#acks-and-errors)
+- [Events](#events)
+- [Mock Mode](#mock-mode)
+- [Testing](#testing)
+- [Leaving the Applet](#leaving-the-applet)
+- [The MCP Server](#the-mcp-server)
+
+<a name="installation"></a>
+## Installation
+
+```sh
+npm install @ziprack/sdk
+```
+
+```ts
+import { Rack } from '@ziprack/sdk';
+```
+
+`Rack` is a singleton — one per frame, which is what an applet always is. `createRack()` returns a
+fresh client for tests or unusual multi-frame setups.
+
+A Rack also serves an IIFE build at `/ziprack/assets/sdk.js` that exposes `window.Rack` (and
+`window.ZipRack`), for applets with no build step. It is the same code; prefer the npm package when you have a bundler, because mock
+mode and the test host come with it.
+
+<a name="booting"></a>
+## Booting
+
+```ts
+const launch = await Rack.init({ slug: 'my-applet' });
+```
+
+`init()` announces `rack:ready` to the parent, waits for `rack:launch`, and resolves with the launch
+payload. It is safe to call repeatedly: subsequent calls return the same promise. Calls made before
+the handshake completes are queued, not dropped, so you never have to gate your UI on initialisation
+order.
+
+| Option | Default | Purpose |
+|---|---|---|
+| `slug` | — | Labels the mock session and locates `./manifest.json` when standalone. |
+| `launchTimeoutMs` | `3000` | How long to wait for `rack:launch` before falling back to mock mode. |
+| `ackTimeoutMs` | `5000` | Per-call ack timeout. Streamed calls reset it per chunk. |
+| `manifestUrl` | `./manifest.json` | Where mock mode reads your manifest. |
+| `transport` | — | Inject a transport (tests). Skips the handshake and mock detection. |
+
+`Rack.mode` is `'pending'`, `'host'` or `'mock'`. `Rack.launched` tells you whether launch data has
+arrived.
+
+<a name="launch-data"></a>
+## Launch Data
+
+Everything the Rack is willing to tell you up front arrives in one payload — there is no second
+round trip to fetch the participant, the attempt or the manifest.
+
+```ts
+interface LaunchData {
+    schema: 'ziprack/1';
+    actor: { id: number; name: string };
+    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
+
+    auth?:      { user: LaunchUser };
+    attempt?:   { id, status, state, segment };
+    activity?:  { activities: LaunchActivity[] };
+    db?:        { collections: Array<{ name, scope }> };
+    storage?:   { uploads: Array<{ name, scope, mime, max_bytes }> };
+    ai?:        { prompts: Array<{ id, mode }> };
+    broadcast?: { room, role, members, state, channels };
+}
+```
+
+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.
+
+```ts
+Rack.on('launch', (data) => render(data));   // fires immediately if already launched
+Rack.declares('broadcast');                  // did the manifest declare it?
+```
+
+<a name="acks-and-errors"></a>
+## Acks and Errors
+
+**Every SDK call resolves to an `AckResult` and never throws.** There is no `try`/`catch` ceremony
+around a capability call; there is a branch on `ok`.
+
+```ts
+interface AckResult<T> {
+    ok: boolean;
+    data?: T;
+    error?: AckErrorCode;
+    message?: string;     // human-readable, safe to log, not to show
+    details?: object;     // validation errors, keyed by field
+}
+```
+
+```ts
+const result = await Rack.db.collection('ideas').create({ title, status: 'draft' });
+
+if (! result.ok) {
+    if (result.error === 'quota_exceeded') return showFull();
+    return showRetry();
+}
+
+const idea = result.data.record;
+```
+
+| Code | Means |
+|---|---|
+| `timeout` | No ack within the timeout. The shell retries the batch once; this is what you see after that. |
+| `disposed` | The client was torn down while the call was in flight. |
+| `persist_failed` | The Rack could not process the message. Already reported server-side. |
+| `undeclared_capability` | The manifest does not declare it — a packaging bug, not a runtime condition. |
+| `unknown_type` | Malformed or unimplemented message type. |
+| `validation` | Payload failed the handler's rules or a declared schema. See `details`. |
+| `forbidden` | Permitted by the manifest, refused for this participant (not the owner, not the facilitator). |
+| `completed` | The attempt is finished; state, segment and attempt-scoped records are frozen. |
+| `quota_exceeded` | Collection full, upload slot full, file too large. |
+| `budget_exceeded` | An `ai@1` budget was reached. |
+| `not_found` | Unknown record, file, channel or collection. |
+| `conflict` | A concurrent write lost. |
+
+**Do not block the participant on an ack.** The shell batches messages on a 300 ms window (up to 50
+per request) and coalesces `attempt:state` so only the latest value is sent. Fire and forget for
+progress and state; `await` only what you must confirm — typically the last answer before
+`complete()`.
+
+```ts
+void Rack.attempt.setState({ step: 4 });             // fire and forget
+await Rack.activity.answer('outro.confidence', 5);   // confirm, then:
+await Rack.attempt.complete();
+```
+
+<a name="events"></a>
+## Events
+
+The Rack pushes events into the frame — room broadcasts, presence changes, role grants. Subscribe
+through the capability that owns them (see [Broadcast](broadcast.md)), or read the raw stream:
+
+```ts
+Rack.on('event', ({ event, payload, channel, from }) => {
+    console.log(event, payload, channel, from?.participant_id);
+});
+```
+
+<a name="mock-mode"></a>
+## Mock Mode
+
+Run `npm run dev` and there is no Rack, so the SDK becomes one. Mock mode reads your
+`./manifest.json` and services every capability locally — which means declared capabilities,
+activities, collections, prompts and uploads behave exactly as they will in production, including
+refusing calls the manifest did not declare.
+
+```
+[ziprack] running in mock mode (not embedded in a Rack)
+[ziprack mock] activity:statement { verb: 'answered', … }
+```
+
+| Surface | Mock behaviour |
+|---|---|
+| `attempt` | State and status persist in `localStorage` under `ziprack-mock:{slug}:*`. Refresh resumes. |
+| `activity` | Statements are logged and kept in memory. |
+| `db` | Records persist in `localStorage`, validated against the declared schema. |
+| `storage` | Files are held as blob URLs and marked clean. |
+| `ai` | Returns a stub conforming to `output_schema` — or your own handler. |
+| `broadcast` | Uses `BroadcastChannel`, so **two tabs of your dev server form a room**. |
+
+Two hooks exist only in mock mode:
+
+```ts
+Rack.mock.ai('score_pitch', (vars) => ({ clarity: 4, feedback: `Nice work on "${vars.pitch}"` }));
+Rack.mock.resetAttempt();   // replay a completed attempt
+```
+
+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.
+
+<a name="testing"></a>
+## Testing
+
+`@ziprack/sdk/testing` ships an in-memory Rack you can assert against.
+
+```ts
+import { createRack } from '@ziprack/sdk';
+import { FakeHost } from '@ziprack/sdk/testing';
+import manifest from '../public/manifest.json';
+
+it('records the answer and completes exactly once', async () => {
+    const host = new FakeHost(manifest);
+    const rack = createRack();
+    await rack.init({ transport: host.transport() });
+
+    await rack.activity.answer('intro.confidence', 5);
+    await rack.attempt.complete();
+    await rack.attempt.complete();                      // idempotent
+
+    expect(host.answers()).toEqual({ 'intro.confidence': 5 });
+    expect(host.attempt().status).toBe('completed');
+});
+```
+
+| Member | Gives you |
+|---|---|
+| `host.transport()` | Pass to `rack.init({ transport })`. |
+| `host.statements` | Every statement the applet emitted, in order. |
+| `host.answers()` | The last `answered` value per activity — what reporting would export. |
+| `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. |
+
+<a name="leaving-the-applet"></a>
+## Leaving the Applet
+
+```ts
+Rack.eject();
+```
+
+Asks the Rack to navigate away — back to the applet list, or wherever the deployment sends people.
+It needs no capability and takes no ack. In mock mode it logs what would have happened.
+
+<a name="the-mcp-server"></a>
+## The MCP Server
+
+```sh
+npx ziprack-mcp
+```
+
+The SDK ships a stdio MCP server that gives an AI assistant these docs and the applet authoring
+guidelines. The docs are bundled into the package when it is published, so what the assistant reads
+always matches the SDK version in your `node_modules`, not whatever it remembers of an older one. The
+starter already includes the configuration in `.mcp.json`:
+
+```json
+{
+    "mcpServers": {
+        "ziprack": {
+            "command": "npx",
+            "args": ["ziprack-mcp"]
+        }
+    }
+}
+```
+
+| Tool | Purpose |
+|---|---|
+| `ziprack_guidelines` | The rules every applet follows (`ziprack-1-authoring.md`). Read before writing applet code. |
+| `ziprack_list_docs` | Every doc in reading order, with its section anchors. |
+| `ziprack_search_docs` | The best-matching sections, in full, for one or more phrasings. |
+| `ziprack_read_doc` | One doc, or one section of it by anchor. |
+
+Every answer names the SDK version it came from. `ziprack-studio mcp` includes the same four tools,
+so a Studio project needs only the one server.