@ziprack/sdk 0.1.1 → 0.2.0

package/dist/docs/introduction.md

@@ -0,0 +1,124 @@
+# Introduction
+
+- [The Shape of a Rack](#the-shape-of-a-rack)
+- [The Trust Boundary](#the-trust-boundary)
+- [Objects](#objects)
+- [Capabilities](#capabilities)
+- [What zipRACK Is Not](#what-ziprack-is-not)
+
+<a name="the-shape-of-a-rack"></a>
+## The Shape of a Rack
+
+A **Rack** is one deployed Laravel application. It authenticates people, stores every byte an
+applet produces, makes every outbound call, holds the WebSocket, and renders the admin reporting.
+
+An **applet** is a zip containing a static web app. It is uploaded, validated, extracted and served
+inside a sandboxed iframe at `/a/{slug}`. It owns layout, branding, media, navigation and
+interaction — the entire participant-facing experience — and nothing else.
+
+```
+┌─ Rack (Laravel) ───────────────────────────────────────────┐
+│  auth · attempts · records · files · prompts · rooms       │
+│  ┌─ chrome ────────────────────────────────────────────┐   │
+│  │ ┌─ iframe (opaque origin, no allow-same-origin) ──┐ │   │
+│  │ │  applet: index.html + assets                    │ │   │
+│  │ │  @ziprack/sdk  ⇄  postMessage  ⇄  shell         │ │   │
+│  │ └─────────────────────────────────────────────────┘ │   │
+│  └─────────────────────────────────────────────────────┘   │
+└────────────────────────────────────────────────────────────┘
+```
+
+Every deployment is standalone: its own database, its own domain, its own capability set. There is
+no shared multi-tenant monolith. What unites deployments is the format string `ziprack/1` and the
+set of capability versions each Rack implements — which is why an applet built against one Rack runs
+on another.
+
+<a name="the-trust-boundary"></a>
+## The Trust Boundary
+
+The iframe is rendered with:
+
+```html
+<iframe sandbox="allow-scripts allow-forms allow-popups allow-popups-to-escape-sandbox"
+        allow="autoplay; fullscreen; picture-in-picture; encrypted-media">
+```
+
+Note the absence of `allow-same-origin`. The applet document has an **opaque origin**: no cookies,
+no `localStorage`, no `IndexedDB`, no credentialed requests, no way to call the Rack over HTTP.
+Everything an applet needs, it asks for over `postMessage`:
+
+```ts
+await Rack.activity.answer('intro.connection', 5);
+```
+
+That call becomes a `ziprack` envelope posted to the parent window, which the shell batches into a
+`POST /ziprack/s/{session}/messages`, which `MessageDispatcher` checks against the applet's manifest
+before handing to the capability's handler. The applet asks; the Rack decides, enforces and persists.
+
+Trust runs on `event.source`, never `event.origin` — the applet's origin is opaque by design, so
+origin comparison is meaningless. A nested frame (a Vimeo player, say) that tries to talk to the
+Rack is ignored, because its window is not the applet's `contentWindow`.
+
+**This is why new capabilities are cheap.** Adding an LLM surface does not loosen the CSP, because
+the call never leaves the frame as HTTP — it leaves as a `postMessage` the Rack fulfils server-side.
+An applet can never obtain an API key, a channel token or a database handle, because none of those
+ever cross the boundary.
+
+<a name="objects"></a>
+## Objects
+
+| Object | What it is | Capability |
+|---|---|---|
+| **Applet** | One experience or app, identified by an immutable `slug`. Has many versions. | core |
+| **Version** | One uploaded zip. Immutable. Exactly one is current. | core |
+| **Participant** | The person in front of the applet, resolved from the Rack's own users (or a guest cookie). | core |
+| **Attempt** | One participant's run. Holds `status`, `state`, `segment`. Pinned to the version it started on. | `attempt@1` |
+| **Statement** | Append-only record: actor did verb on activity with result. The audit trail and the uniform export. | `activity@1` |
+| **Record** | A mutable row in a declared collection, at a declared scope. Working state. | `db@1` |
+| **Stored file** | A participant upload, addressable only once scanned clean. | `storage@1` |
+| **Room** | A shared session: an applet version plus its members, each `participant` or `facilitator`. | `broadcast@1` |
+| **Profile attribute** | A Rack-owned fact about the participant, released only if requested and permitted. | `auth@1` |
+
+Statements and records coexist because they answer different questions. A statement is *what
+happened*; a record is *what is currently true*. Statements are append-only and uniformly shaped, so
+they export to one CSV per applet. Records are mutable and arbitrarily shaped, which is why `db@1`
+requires a JSON Schema — the schema is what buys back the column headers.
+
+<a name="capabilities"></a>
+## Capabilities
+
+Seven surfaces. An applet declares the ones it uses in its manifest, and the Rack refuses at runtime
+any call the manifest did not declare.
+
+| Capability | Covers | Entry point |
+|---|---|---|
+| [`auth@1`](auth.md) | Who the participant is; released profile attributes | `Rack.auth.user()` |
+| [`attempt@1`](attempts.md) | Lifecycle, resume state, completion, version pinning | `Rack.attempt.complete()` |
+| [`activity@1`](activity.md) | Append-only statements and the CSV export | `Rack.activity.answer(id, value)` |
+| [`db@1`](database.md) | CRUD records in declared collections | `Rack.db.collection('ideas').create({…})` |
+| [`storage@1`](storage.md) | Participant file uploads | `Rack.storage.put('photos', file)` |
+| [`ai@1`](ai.md) | Declared prompt templates: analysis and chat | `Rack.ai.ask('summarize', vars)` |
+| [`broadcast@1`](broadcast.md) | Rooms, presence, facilitator control, shared state | `Rack.broadcast.join('main')` |
+
+Capability versions are independent of the format string and of the Composer package version. See
+[Versioning](versioning.md).
+
+Two things need no capability: [declared media](media.md) (`Rack.media.embedUrl(id)`) and
+`Rack.eject()`, which asks the Rack to leave the applet.
+
+<a name="what-ziprack-is-not"></a>
+## What zipRACK Is Not
+
+These were considered and settled. Reopening them needs new information, not a fresh opinion.
+
+- **Not multi-tenant.** Standalone Racks per engagement. Isolation is infrastructure, not
+  application code. Say *deployment*, *Rack* or *fleet* — never *tenant*.
+- **Not two standards.** There is no "experience profile" and "app profile". An experience is an
+  applet declaring `attempt@1` and `activity@1`; an app is one declaring `db@1` and not `attempt@1`.
+- **No CRDTs in v1.** Shared room state is server-authoritative, last write wins per key.
+- **No static analysis of applet JS.** Minified bundles defeat it (`window["ev"+"al"]`); the CSP
+  does that work at runtime where it cannot be evaded.
+- **No display or kiosk role.** Rooms have participants and facilitators. Multi-screen AV work stays
+  bespoke. The general test: *if a capability requires an applet author to reason about device
+  identity, transport or deployment topology, it does not belong in zipRACK.*
+- **No offline mode.** Participants are in offices with reliable connectivity.

package/dist/docs/manifest.md

@@ -0,0 +1,209 @@
+# The Manifest
+
+- [Introduction](#introduction)
+- [Core Fields](#core-fields)
+- [The Requires Block](#the-requires-block)
+- [Capability Sections](#capability-sections)
+- [A Complete Example](#a-complete-example)
+- [Validation Errors](#validation-errors)
+
+<a name="introduction"></a>
+## Introduction
+
+`manifest.json` sits at the root of the zip and is the applet's entire declaration of intent. It
+names the applet, states which capabilities it calls, and describes the shape of everything the Rack
+will need to validate, store, index, report on and render.
+
+**Declaration is mandatory, not advisory.** A call to a capability the manifest did not declare is
+refused at runtime with `undeclared_capability`. That is also what makes capability-diff review at
+upload meaningful: the manifest is a contract a reviewer can read.
+
+<a name="core-fields"></a>
+## Core Fields
+
+```json
+{
+    "schema": "ziprack/1",
+    "slug": "my-applet",
+    "name": "My Applet",
+    "version": "1.0.0",
+    "entry": "index.html",
+    "requires": { "capabilities": [], "profile": [] },
+    "media": []
+}
+```
+
+| Field | Rules |
+|---|---|
+| `schema` | Required. Exactly `ziprack/1`. |
+| `slug` | Required. `^[a-z0-9]+(-[a-z0-9]+)*$`, max 100. Becomes `/a/{slug}`. **Immutable.** |
+| `name` | Required, max 255. Shown to participants and admins. |
+| `version` | Required. `MAJOR.MINOR.PATCH` with optional `-prerelease`, max 50. Unique per applet. |
+| `entry` | Optional, default `index.html`. Relative, no `..`, ends in `.html`. |
+| `requires` | Required, even if empty. See below. |
+| `media` | Optional. See [Media](media.md). |
+
+Everything else at the top level belongs to a capability. A section whose owning capability is not
+declared is a validation error, and so is a section no installed capability owns.
+
+<a name="the-requires-block"></a>
+## The Requires Block
+
+```json
+"requires": {
+    "capabilities": ["auth@1", "attempt@1", "activity@1", "ai@1"],
+    "profile": ["display_name", "business_unit", "locale"]
+}
+```
+
+- Each capability reference matches `^[a-z][a-z0-9_]*@\d+$`. Declaring a capability twice is an
+  error, and so is declaring one this Rack does not implement — the error names what it does.
+- `profile` lists the attribute keys you want released, and requires `auth@1`. Keys match
+  `^[a-z][a-z0-9_]*$`. A key the deployment does not release is simply absent at launch;
+  [degrade gracefully](auth.md).
+- Declaring `attempt@1` has a side effect: it pins every participant to the version they started on.
+  See [Versioning](versioning.md#version-pinning).
+
+<a name="capability-sections"></a>
+## Capability Sections
+
+| Section | Capability | Shape |
+|---|---|---|
+| `segments[]` | `attempt@1` | `{key, label, values[{key,label}]}` — dimensions the admin filters by |
+| `activities[]` | `activity@1` | `{id, type, label, scale?, segment?, sequence?}` — required, at least one |
+| `reporting.metrics[]` | `activity@1` (+ `attempt@1`) | `{key, label, pre, post}` — pairs two declared activities |
+| `collections[]` | `db@1` | `{name, scope, schema, indexed?, quota?, permissions?}` |
+| `uploads[]` | `storage@1` | `{name, scope, mime[], max_bytes?, max_files?}` |
+| `prompts[]` | `ai@1` | `{id, mode, template, vars?, output_schema?, budget?, model?}` |
+| `broadcast` | `broadcast@1` | `{channels?, facilitator_events?}` |
+
+Each is specified in full on its capability's page. Two cross-cutting rules are worth stating here:
+
+**Scopes are declarations, not runtime choices.** `db@1` collections and `storage@1` uploads each
+declare a scope — `attempt`, `user`, `room` or `applet` — and an `attempt` scope requires
+`attempt@1` while a `room` scope requires `broadcast@1`. The scope answers, at declaration time,
+what happens to the data when an attempt completes.
+
+**Quotas and budgets are ceilings you may lower, not raise.** The deployment's config sets hard
+maxima; a manifest asking for more fails validation, and a manifest asking for nothing gets the
+deployment's defaults.
+
+<a name="a-complete-example"></a>
+## A Complete Example
+
+An applet exercising every capability at once. Most applets need three or four.
+
+```json
+{
+    "schema": "ziprack/1",
+    "slug": "team-summit",
+    "name": "Team Summit",
+    "version": "2.1.0",
+    "entry": "index.html",
+
+    "requires": {
+        "capabilities": ["auth@1", "attempt@1", "activity@1", "db@1", "storage@1", "ai@1", "broadcast@1"],
+        "profile": ["display_name", "business_unit", "locale"]
+    },
+
+    "media": [
+        { "id": "intro.welcome", "provider": "vimeo", "key": "912345678" },
+        { "id": "debrief.clip", "provider": "youtube", "key": "dQw4w9WgXcQ" }
+    ],
+
+    "segments": [
+        {
+            "key": "track",
+            "label": "Track",
+            "values": [
+                { "key": "rd", "label": "R&D" },
+                { "key": "commercial", "label": "Commercial" }
+            ]
+        }
+    ],
+
+    "activities": [
+        { "id": "intro.confidence", "type": "rating", "label": "How confident do you feel about the new operating model?", "scale": { "min": 1, "max": 6 }, "sequence": 1 },
+        { "id": "team.pitch", "type": "text", "label": "In one sentence, what is your team's pitch?", "segment": "track", "sequence": 2 },
+        { "id": "outro.confidence", "type": "rating", "label": "How confident do you feel about the new operating model?", "scale": { "min": 1, "max": 6 }, "sequence": 3 }
+    ],
+
+    "reporting": {
+        "metrics": [
+            { "key": "confidence", "label": "Confidence", "pre": "intro.confidence", "post": "outro.confidence" }
+        ]
+    },
+
+    "collections": [
+        {
+            "name": "ideas",
+            "scope": "room",
+            "schema": {
+                "type": "object",
+                "properties": {
+                    "title":  { "type": "string", "maxLength": 120 },
+                    "body":   { "type": "string", "maxLength": 2000 },
+                    "status": { "type": "string", "enum": ["draft", "posted", "picked"] },
+                    "votes":  { "type": "integer", "minimum": 0 }
+                },
+                "required": ["title", "status"]
+            },
+            "indexed": ["status", "votes"],
+            "quota": { "max_records": 500, "max_bytes": 16384 },
+            "permissions": { "update": "owner", "delete": "facilitator" }
+        }
+    ],
+
+    "uploads": [
+        { "name": "artifacts", "scope": "room", "mime": ["image/png", "image/jpeg"], "max_bytes": 5242880, "max_files": 10 }
+    ],
+
+    "prompts": [
+        {
+            "id": "score_pitch",
+            "mode": "analysis",
+            "template": "Score this team pitch for clarity and specificity.\n\nPitch: {{pitch}}\nTrack: {{track}}",
+            "vars": {
+                "type": "object",
+                "properties": { "pitch": { "type": "string" }, "track": { "type": "string" } },
+                "required": ["pitch"]
+            },
+            "output_schema": {
+                "type": "object",
+                "properties": {
+                    "clarity":  { "type": "integer", "minimum": 1, "maximum": 5 },
+                    "feedback": { "type": "string" }
+                },
+                "required": ["clarity", "feedback"]
+            },
+            "budget": { "max_calls_per_attempt": 3, "max_output_tokens": 400 }
+        }
+    ],
+
+    "broadcast": {
+        "channels": ["main", "board"],
+        "facilitator_events": ["advance", "lock", "reveal"]
+    }
+}
+```
+
+<a name="validation-errors"></a>
+## Validation Errors
+
+The validator runs core rules first, then the rules of every declared capability, then cross-field
+checks. All errors are reported at once, keyed by manifest path, and the installer surfaces them as
+one message. The checks that catch people out:
+
+| Error | Cause |
+|---|---|
+| `Unknown manifest section [x]` | No installed capability owns that top-level key. |
+| `Manifest section [collections] requires the [db] capability` | The section is there; the declaration is not. |
+| `This Rack does not implement [db@1]. Implemented: …` | Wrong capability or wrong version for this deployment. |
+| `Activity references unknown segment [track]` | `activities[].segment` must name a declared segment key. |
+| `Metric references unknown activity [outro.x]` | `pre` and `post` must be declared activity ids. |
+| `reporting.metrics needs the attempt capability` | Metrics are computed over completed attempts. |
+| `A room-scoped collection requires the [broadcast] capability` | Scope implies capability. |
+| `Indexed path [votes] must be a string, integer, number or boolean property declared in the schema` | You can only index what you declared, and only scalars. |
+| `Placeholder {{pitch}} is not declared in vars.properties` | Prompt templates and their `vars` schema must agree. |
+| `Analysis prompts need an output_schema of type object` | `mode: "analysis"` is structured output by definition. |
+| `The $room channel is reserved for the Rack` | Pick another channel name. |

package/dist/docs/media.md

@@ -0,0 +1,85 @@
+# Media
+
+- [Introduction](#introduction)
+- [Declaring Media](#declaring-media)
+- [Rendering a Player](#rendering-a-player)
+- [Why the Rack Builds the URL](#why-the-rack-builds-the-url)
+- [Privacy Defaults](#privacy-defaults)
+
+<a name="introduction"></a>
+## Introduction
+
+Vimeo and YouTube embeds are a routine requirement, and they need no capability. What they do need
+is a declaration: the applet names a video by id, and the Rack builds the player URL.
+
+Everything else — your own images, audio and video — ships inside the zip and is referenced
+relatively. The CSP allows `img-src`/`media-src` of `'self' data: blob:` plus whatever hosts the
+deployment has allowlisted, and nothing else.
+
+<a name="declaring-media"></a>
+## Declaring Media
+
+```json
+"media": [
+    { "id": "corine.diagnosis", "provider": "vimeo",   "key": "912345678" },
+    { "id": "intro.welcome",    "provider": "youtube", "key": "dQw4w9WgXcQ" }
+]
+```
+
+| Field | Rules |
+|---|---|
+| `id` | Required. `^[a-z0-9][a-z0-9_.:-]*$`, max 150, unique. |
+| `provider` | Required. Must be in the deployment's `ziprack.media.providers` — `vimeo`, `youtube`. |
+| `key` | Required. `^\d+$` for Vimeo, `^[\w-]{11}$` for YouTube. |
+
+Validation happens at upload, not at runtime, so a typo in a video id fails the package rather than
+the participant's session. Where `ziprack.media.resolve_oembed` is on, the Rack also performs the
+oEmbed lookup server-side at install and caches the title, thumbnail and duration.
+
+<a name="rendering-a-player"></a>
+## Rendering a Player
+
+```ts
+const url = Rack.media.embedUrl('corine.diagnosis');
+if (url) {
+    frame.src = url;
+}
+
+const embed = Rack.media.get('corine.diagnosis');
+embed?.meta?.title;        // cached oEmbed metadata, when resolved
+embed?.meta?.duration;
+
+Rack.media.all();          // every declared embed, by id
+```
+
+Both reads are synchronous — the embeds arrive in launch data.
+
+```html
+<iframe id="player" allow="autoplay; fullscreen; picture-in-picture; encrypted-media"></iframe>
+```
+
+The Rack sets a matching `allow` on the applet's own iframe. Permissions Policy has to be chained
+through both frames: if the outer frame does not carry it, your nested player silently loses
+autoplay and fullscreen, which is a genuinely hard bug to diagnose from inside the applet.
+
+Nested players inherit the applet's sandbox flags, so the player also runs with an opaque origin —
+no cookies, no storage of its own. Both providers' JS APIs are `postMessage`-driven, so they
+continue to work. A nested frame cannot talk to the Rack: the bridge checks `event.source`.
+
+<a name="why-the-rack-builds-the-url"></a>
+## Why the Rack Builds the URL
+
+Because a URL the applet controls is a channel the applet controls. An applet could otherwise encode
+data in a player URL — `player.vimeo.com/video/123?h=<something>` — and while that request lands in
+a provider's logs the attacker cannot read, the cleanest answer is to remove the path and query
+string from the applet's reach entirely. With declared media there is nothing to encode.
+
+It also buys back `connect-src 'self'`: the oEmbed lookup happens server-side at upload, so the
+applet never needs to talk to `vimeo.com` at runtime.
+
+<a name="privacy-defaults"></a>
+## Privacy Defaults
+
+The Rack builds YouTube URLs against `youtube-nocookie.com` and Vimeo URLs with `dnt=1`. For pharma
+and financial-services clients this is frequently procurement-gating rather than a nicety, and it is
+not configurable per applet.

package/dist/docs/protocol.md

@@ -0,0 +1,121 @@
+# The Bridge Protocol
+
+- [When You Need This](#when-you-need-this)
+- [The Envelope](#the-envelope)
+- [Handshake](#handshake)
+- [Calls and Acks](#calls-and-acks)
+- [Streaming](#streaming)
+- [Events](#events)
+- [What the Shell Does](#what-the-shell-does)
+
+<a name="when-you-need-this"></a>
+## When You Need This
+
+Almost never. Use [`@ziprack/sdk`](sdk.md) — it is the reference implementation of everything below,
+plus mock mode and a test host. This page exists for two cases: you are implementing the applet side
+in a language or runtime the SDK does not cover, and you are working on the Rack itself.
+
+<a name="the-envelope"></a>
+## The Envelope
+
+Every message in both directions is one JSON object:
+
+```json
+{ "ns": "ziprack", "v": 1, "type": "activity:statement", "requestId": "b1f0…", "payload": { } }
+```
+
+| Field | Rules |
+|---|---|
+| `ns` | Always `ziprack`. Anything else is ignored. |
+| `v` | Always `1`. Versioned with the format string, not with capabilities. |
+| `type` | `rack:*` for lifecycle, or `{capability}:{action}` matching `^[a-z][a-z0-9_]*:[a-z][a-z0-9_.]*$`. |
+| `requestId` | Present when you want an ack. The SDK uses `crypto.randomUUID()`. |
+| `payload` | Type-specific object. |
+
+The applet posts to `window.parent` with target origin `*`, because it has no origin of its own to
+assert. **The host trusts by `event.source`**: a message is honoured only when it came from the
+applet iframe's `contentWindow`. `event.origin` is never consulted — the applet's origin is opaque
+by design, so comparing it would be theatre. The same rule protects the applet in reverse: ignore
+any message whose source is not `window.parent`, which is what makes a nested Vimeo player unable to
+impersonate the Rack.
+
+<a name="handshake"></a>
+## Handshake
+
+```
+applet → host   { type: "rack:ready" }
+host   → applet { type: "rack:launch", payload: { …launch data… } }
+```
+
+The applet announces readiness as early as it can; the host replies with the full launch payload
+(see [Launch Data](sdk.md#launch-data)). Do not send capability calls before `rack:launch` arrives —
+queue them, as the SDK does.
+
+<a name="calls-and-acks"></a>
+## Calls and Acks
+
+```
+applet → host   { type: "db:create", requestId: "r1", payload: { collection: "ideas", data: {…} } }
+host   → applet { type: "rack:ack",  requestId: "r1", payload: { ok: true, data: { record: {…} } } }
+```
+
+An ack always carries the `requestId` it answers. On failure:
+
+```json
+{ "ok": false, "error": "quota_exceeded", "message": "Collection [ideas] is full (500 records)." }
+```
+
+Error codes are listed in [Acks and Errors](sdk.md#acks-and-errors) and are part of the contract:
+they do not change within `ziprack/1`.
+
+A message sent without a `requestId` is fire-and-forget — the host processes it and sends nothing
+back. `rack:eject` is the usual example.
+
+<a name="streaming"></a>
+## Streaming
+
+A streamed call receives multiple acks under one `requestId`:
+
+```json
+{ "ok": true, "partial": true, "delta": "Well, " }
+{ "ok": true, "partial": true, "delta": "that depends…" }
+{ "ok": true, "done": true, "data": { "message_id": "m_1", "text": "Well, that depends…", "usage": {…} } }
+```
+
+Only the terminal ack resolves the call; each partial resets the ack timeout. `ai:chat` is the only
+streaming surface in `ziprack/1`.
+
+<a name="events"></a>
+## Events
+
+Unsolicited messages from the host carry no `requestId`:
+
+```json
+{ "ns": "ziprack", "v": 1, "type": "rack:event",
+  "payload": { "event": "advance", "payload": { "step": 3 }, "channel": "main",
+               "from": { "participant_id": 42, "role": "facilitator" } } }
+```
+
+The reserved channel `$room` carries Rack-generated room events — `presence`, `state`, `role`,
+`status`. An applet cannot publish to it.
+
+<a name="what-the-shell-does"></a>
+## What the Shell Does
+
+Between the frame and the Rack sits the shell, a small script the Rack serves with the player page.
+Knowing its behaviour explains timings you would otherwise find surprising:
+
+- **Batching.** Calls are queued for up to 300 ms and posted together to
+  `POST /ziprack/s/{session}/messages`, maximum 50 per request. Acks come back in order and are
+  relayed individually.
+- **Coalescing.** Only the latest pending `attempt:state` survives a batch, so calling `setState()`
+  on every keystroke is safe.
+- **Retry.** A failed batch is retried once after 1 s; after that every message in it acks
+  `persist_failed`.
+- **Keepalive.** On page hide the pending batch flushes with `keepalive: true`.
+- **Files.** `storage:put` is intercepted and re-sent as multipart to
+  `POST /ziprack/s/{session}/files`; the `File` never travels as JSON.
+- **Streams.** When an ack carries `data.stream === true`, the shell opens an `EventSource` against
+  `/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.

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.