@ziprack/sdk 0.1.2 → 0.2.1

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

@@ -0,0 +1,56 @@
+# zipRACK Documentation
+
+zipRACK is a micro app framework: a Laravel host — **the Rack** — that runs sandboxed static web
+apps — **applets** — and services their capability requests over `postMessage`. An applet owns
+everything the participant sees. The Rack owns login, persistence, AI access, real-time coordination
+and reporting.
+
+These docs cover both halves. If you are building an applet, start with
+[Applet Packages](applet-packages.md). If you are standing up or maintaining a Rack, start with
+[Installation](installation.md).
+
+## Prologue
+
+- [Introduction](introduction.md) — the trust boundary, the core model, the objects
+- [Versioning](versioning.md) — the three version axes and why they never couple
+
+## Building an applet
+
+- [Applet Packages](applet-packages.md) — the zip, the installer rules, the starter
+- [The Manifest](manifest.md) — every field, every rule the validator enforces
+- [The JavaScript SDK](sdk.md) — `Rack.init()`, acks, errors, mock mode, testing
+- [zipRACK Studio](studio.md) — the visual builder, the derived manifest, the MCP server
+- [The Bridge Protocol](protocol.md) — the envelope, for anyone not using the SDK
+
+## Capabilities
+
+- [Authentication](auth.md) — `auth@1`
+- [Attempts](attempts.md) — `attempt@1`
+- [Activity](activity.md) — `activity@1`
+- [Database](database.md) — `db@1`
+- [Storage](storage.md) — `storage@1`
+- [AI](ai.md) — `ai@1`
+- [Broadcast](broadcast.md) — `broadcast@1`
+- [Media](media.md) — declared embeds, no capability required
+
+## Running a Rack
+
+- [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
+- [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`
+
+---
+
+Also in this repository: [`ziprack-1-authoring.md`](ziprack-1-authoring.md), a one-page condensed
+brief suitable for dropping into an applet project as `CLAUDE.md`. The same content, expanded, is
+published to the CN IDEAS skills library as an instruction set.

package/dist/docs/activity.md

@@ -0,0 +1,144 @@
+# Activity — `activity@1`
+
+- [Introduction](#introduction)
+- [Declaring Activities](#declaring-activities)
+- [Emitting Statements](#emitting-statements)
+- [Activity Types](#activity-types)
+- [Metrics](#metrics)
+- [Designing for the Export](#designing-for-the-export)
+
+<a name="introduction"></a>
+## Introduction
+
+A **statement** is an append-only record that *an actor did a verb on an activity with a result*.
+It is the audit trail, and because every statement has the same shape, it is also the one export
+that works identically for every applet on every Rack.
+
+Statements are never updated and never deleted. Re-answering is normal: reporting reads the **last**
+`answered` statement per activity per attempt.
+
+`db@1` does not replace this. Statements are what happened; [records](database.md) are what is
+currently true.
+
+<a name="declaring-activities"></a>
+## Declaring Activities
+
+Every question you report on must be declared. At least one activity is required.
+
+```json
+"activities": [
+    { "id": "intro.connection", "type": "rating", "label": "How connected do you feel to patients?",
+      "scale": { "min": 1, "max": 6 }, "sequence": 1 },
+    { "id": "rd.corine.reaction", "type": "text", "label": "What stood out to you about Corine's story?",
+      "segment": "track", "sequence": 2 }
+]
+```
+
+| Field | Rules |
+|---|---|
+| `id` | Required, max 150, unique. **This is the data contract.** |
+| `type` | Required, max 100. Drives how the admin renders and exports the value. |
+| `label` | Required, max 1000. Becomes the CSV header and the analysis heading. |
+| `scale` | Optional object, for `rating` and `scale` types. |
+| `segment` | Optional. Must name a declared [segment](attempts.md#segments) key, or be `null` for shared. |
+| `sequence` | Optional integer ≥ 0. Controls export column order; defaults to array position. |
+
+Use stable, dotted, lowercase ids: `{phase}.{topic}.{question}`. An undeclared id still records, but
+it exports unlabeled and appended after every declared column — useful as a safety net, never as a
+plan.
+
+<a name="emitting-statements"></a>
+## Emitting Statements
+
+```ts
+// The common case: a committed answer.
+await Rack.activity.answer('intro.connection', 5);
+
+// Navigation and progress. Fire and forget.
+void Rack.activity.progress('rd.chapter_2');
+
+// Anything else.
+void Rack.activity.statement({
+    verb: 'viewed',
+    activity: { id: 'rd.corine.video', type: 'media' },
+    result: { duration_seconds: 184 },
+    context: { autoplay: false },
+});
+```
+
+`answer()` emits `verb: 'answered'` with the value in `result.response` — **the only field reporting
+reads** — and fills `activity.type` from your manifest declaration. `progress()` emits
+`verb: 'progressed'` with `activity.type: 'step'`.
+
+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
+Rack.activity.activities();                  // LaunchActivity[]
+Rack.activity.activity('intro.connection');  // { id, type, label, scale, … } | null
+```
+
+Rendering a question from its declared `label` and `scale` keeps the participant's wording and the
+CSV header identical by construction — a small discipline that pays for itself the first time
+someone edits a question.
+
+<a name="activity-types"></a>
+## Activity Types
+
+`type` is free text, but the admin understands these:
+
+| `type` | `result.response` | Used for |
+|---|---|---|
+| `text` | string | Free text. Feeds admin AI response analysis. |
+| `rating` | number within `scale` | Likert or self-rating. Eligible for metrics. |
+| `scale` | number within `scale` | Semantic alias of `rating`. |
+| `choice` | string key, or array of keys | Single or multi-select. |
+| `custom` | any JSON | Anything else. Exported JSON-encoded. |
+
+<a name="metrics"></a>
+## Metrics
+
+A metric pairs a pre and a post rating of the same thing, and gives the admin a shift card rather
+than two columns to eyeball.
+
+```json
+"reporting": {
+    "metrics": [
+        { "key": "connection", "label": "Connection",
+          "pre": "intro.connection", "post": "outro.connection" }
+    ]
+}
+```
+
+`pre` and `post` must be declared activity ids, and metrics require `attempt@1`, because they are
+computed over completed attempts. Both activities should use the same `scale`, or the shift means
+nothing.
+
+<a name="designing-for-the-export"></a>
+## Designing for the Export
+
+The CSV an admin downloads is:
+
+```
+ID, Name, Email, {first segment label}, Status, Started At, Completed At,
+{declared activities in sequence order, headed by label},
+{undeclared activity ids, appended}
+```
+
+Each cell is the last `result.response` for that activity in that attempt; non-scalars are
+JSON-encoded. Which yields three rules worth writing on the wall:
+
+1. **`id` is the data contract.** Renaming one between versions splits a column: old attempts keep
+   the old column, new attempts fill a new one.
+2. **`label` is the header.** Renaming one is free, and changes only how the column reads.
+3. **`sequence` is the column order.** Set it deliberately; the export reads top to bottom the way
+   the experience does.
+
+Write labels as full sentences, exactly as the participant sees them. An admin reading a
+spreadsheet six months later has no other copy of the question.

package/dist/docs/ai.md

@@ -0,0 +1,159 @@
+# AI — `ai@1`
+
+- [Introduction](#introduction)
+- [Declaring Prompts](#declaring-prompts)
+- [Analysis](#analysis)
+- [Chat](#chat)
+- [Budgets](#budgets)
+- [Untrusted Variables](#untrusted-variables)
+- [Not This Capability](#not-this-capability)
+
+<a name="introduction"></a>
+## Introduction
+
+**The applet never sees a key and never sends a prompt.** It calls a prompt template the manifest
+declared and the Rack stores, supplying *variables*, never instructions.
+
+```ts
+const { data } = await Rack.ai.ask('score_pitch', { pitch, track });
+```
+
+Four things fall out of that design at once:
+
+- Prompt injection *from the applet* is structurally impossible — there is no instruction channel.
+- Model, system prompt and output schema are Rack-owned, so they can be tuned or swapped without
+  republishing the applet.
+- Cost is governable: hard caps per prompt, per attempt, per participant, per applet, enforced
+  server-side.
+- **No CSP change is required.** The call travels as a `postMessage`, not a `fetch`.
+
+<a name="declaring-prompts"></a>
+## Declaring Prompts
+
+```json
+"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 }
+    }
+]
+```
+
+| Field | Rules |
+|---|---|
+| `id` | Required. `^[a-z][a-z0-9_.-]*$`, max 100, unique. |
+| `mode` | Required. `analysis` or `chat`. |
+| `template` | Required, max 20 000. `{{placeholder}}` for each variable. |
+| `vars` | Optional JSON Schema (`type: object`). **If present, every placeholder must be declared in it.** |
+| `output_schema` | Required for `analysis`, `type: object`. |
+| `budget` | Optional. `max_calls_per_attempt`, `max_calls_per_participant`, `max_output_tokens`. |
+| `model` | Optional hint. Honoured only if the deployment allowlists it. |
+
+<a name="analysis"></a>
+## Analysis
+
+Structured output, conforming to the declared `output_schema`. For scoring a response, summarising
+back to the participant, or branching on what someone wrote.
+
+```ts
+interface Score { clarity: number; feedback: string }
+
+const result = await Rack.ai.ask<Score>('score_pitch', { pitch, track: 'rd' });
+
+if (! result.ok) {
+    return result.error === 'budget_exceeded'
+        ? showGenericFeedback()
+        : showRetry();
+}
+
+render(result.data.output.feedback, result.data.output.clarity);
+result.data.usage;   // { input_tokens, output_tokens }
+```
+
+The Rack validates the model's output against your schema before it acks, so `output` either matches
+the schema or the call fails. You do not need defensive parsing — you do need a path for the failure
+case, because a model can be unavailable.
+
+Always write the non-AI fallback. An applet whose experience stalls when a call fails has made an
+LLM into a dependency the framework was designed to keep optional.
+
+<a name="chat"></a>
+## Chat
+
+Conversational, with history held by the Rack and scoped to the attempt or room. The applet never
+holds the transcript.
+
+```ts
+const chat = Rack.ai.chat('coach');
+
+const reply = await chat.send(message, (delta, soFar) => {
+    bubble.textContent = soFar;          // streams as it arrives
+});
+
+if (reply.ok) {
+    bubble.textContent = reply.data.text;
+    reply.data.message_id;
+}
+
+await chat.reset();                      // start a fresh conversation
+```
+
+Streaming works through chunked acks: partials carry `delta`, the terminal ack carries the full
+`text` and `usage`. Each chunk resets the ack timeout, and the whole call allows 60 s.
+
+Messages cap at 4000 characters and history at 40 messages (`ziprack-ai.max_message_length`,
+`history_messages`); older turns fall off rather than failing the call.
+
+<a name="budgets"></a>
+## Budgets
+
+Every layer is enforced server-side, and the applet cannot raise any of them:
+
+| Limit | Declared in | Default | Ceiling |
+|---|---|---|---|
+| Calls per attempt | `budget.max_calls_per_attempt` | 20 | — |
+| Calls per participant | `budget.max_calls_per_participant` | 200 | — |
+| Output tokens | `budget.max_output_tokens` | 800 | 2000 (`ziprack-ai.budget.max_output_tokens_cap`) |
+| Calls per applet per day | deployment | 5000 | — |
+| Calls per Rack per month | deployment | 100 000 | — |
+| Variable payload | deployment | 16 KB | — |
+
+Exceeding any of them returns `budget_exceeded`. Declare the budget your experience actually needs:
+a lower cap is a smaller incident, and the number is visible to whoever reviews the capability diff.
+
+Spend is reported per prompt in the admin API (`/ziprack/admin/applets/{applet}/ai/spend`).
+
+<a name="untrusted-variables"></a>
+## Untrusted Variables
+
+Variables still reach a model. Assume a participant will type adversarial text into any field you
+pass through, and design the template so that it would not matter:
+
+- Put participant text **after** the instructions, clearly delimited, and say what it is.
+- Never ask the model to follow instructions found inside a variable.
+- Prefer `analysis` with a tight `output_schema` over free-form text you will parse yourself — a
+  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="not-this-capability"></a>
+## Not This Capability
+
+The admin console's **AI Response Analysis** — summaries of free-text answers across attempts — is a
+Rack feature operating on collected [statements](activity.md). It works for any applet declaring
+`activity@1`, whether or not that applet uses `ai@1` at all, and it is configured and budgeted
+separately. See [Reporting](reporting.md).

package/dist/docs/applet-packages.md

@@ -0,0 +1,118 @@
+# Applet Packages
+
+- [The Zip](#the-zip)
+- [Installer Rules](#installer-rules)
+- [The Starter](#the-starter)
+- [Relative URLs](#relative-urls)
+- [The SBOM](#the-sbom)
+- [Building and Packaging](#building-and-packaging)
+
+<a name="the-zip"></a>
+## The Zip
+
+An applet ships as a single zip, named for the applet and the version it contains:
+
+```
+{slug}-{version}.zip
+├── manifest.json        required, at the zip root
+├── sbom.json            required — CycloneDX, or package-lock.json
+├── index.html           the entry (configurable via manifest.entry)
+└── 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
+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.
+
+<a name="installer-rules"></a>
+## Installer Rules
+
+`PackageInstaller` is security code, identical on every Rack, and it refuses the whole upload rather
+than skipping a bad file:
+
+- **Static extensions only.** `html js mjs css map json wasm txt vtt svg png jpg jpeg gif webp ico
+  woff woff2 ttf mp3 mp4 wav webm ogg pdf`. A `.php` in your `dist/` rejects the package.
+- **No `..`, no absolute paths, no symlinks, no NUL bytes.** Dotfiles and `__MACOSX/` are skipped
+  silently, so a zip built on macOS is fine.
+- **50 MB by default** (`ziprack.max_upload_mb`).
+- **`manifest.entry` must exist** in the zip and end in `.html`.
+- **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.
+
+<a name="the-starter"></a>
+## The Starter
+
+`starter/` is a minimal, working `ziprack/1` applet: plain Vite and TypeScript, `@ziprack/sdk`, one
+question, one statement, one completion.
+
+```sh
+npm install
+npm run dev        # mock mode: the whole experience runs standalone
+npm run package    # dist-zip/{slug}-{version}.zip, ready to upload
+```
+
+Edit `public/manifest.json` first — `slug`, `name`, `version`, and the capabilities you intend to
+call. Everything else follows from there.
+
+<a name="relative-urls"></a>
+## Relative URLs
+
+The Rack serves your package from `/ziprack/pkg/{token}/…`, where `{token}` is a signed, expiring
+value. A root-relative URL like `/assets/app.js` therefore 404s in production while working
+perfectly on your dev server — the single most common packaging mistake.
+
+With Vite, one line prevents it:
+
+```ts
+export default defineConfig({
+    base: './',                  // required
+    build: { outDir: 'dist', emptyOutDir: true },
+});
+```
+
+The same applies to anything you hand-write: `./assets/logo.svg`, never `/assets/logo.svg`.
+
+<a name="the-sbom"></a>
+## The SBOM
+
+Every package carries a `sbom.json` (CycloneDX) or a `package-lock.json` at its root. An applet is
+*built output*, so there is nothing to audit unless the lockfile comes with it — the same reason
+`npm audit` reads a lockfile rather than code.
+
+On install the Rack extracts the purl list and batches it against OSV.dev. Findings land in the
+[review queue](publishing.md) rather than blocking the upload.
+
+Be clear about the limit: the SBOM is self-attested. A hostile publisher can ship an accurate
+lockfile alongside a tampered bundle. This catches negligence, not malice — which is still worth
+having, because negligence is the common case.
+
+<a name="building-and-packaging"></a>
+## Building and Packaging
+
+`npm run package` in the starter does the whole job:
+
+```js
+// scripts/package.js — abbreviated
+const manifest = JSON.parse(readFileSync('dist/manifest.json', 'utf8'));
+
+execSync('npm sbom --sbom-format cyclonedx --omit dev', { cwd: lockDir })  // → dist/sbom.json
+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.
+
+Upload the result through the admin API, or from the deployment:
+
+```sh
+php artisan ziprack:install dist-zip/my-applet-1.0.0.zip
+php artisan ziprack:promote my-applet 1.0.0
+```
+
+Uploads land **unpublished**. Promotion is always a separate, deliberate action — see
+[Publishing](publishing.md).

package/dist/docs/attempts.md

@@ -0,0 +1,187 @@
+# Attempts — `attempt@1`
+
+- [Introduction](#introduction)
+- [The Lifecycle](#the-lifecycle)
+- [Resume State](#resume-state)
+- [Segments](#segments)
+- [Preview Runs](#preview-runs)
+- [Completion](#completion)
+- [Version Pinning](#version-pinning)
+
+<a name="introduction"></a>
+## Introduction
+
+An **attempt** is one participant's run of an applet. It holds three things: a `status`, a `state`
+blob you own, and a `segment` map. The Rack creates it on first launch, hands it back on every
+subsequent launch, and freezes it when you complete it.
+
+Declaring `attempt@1` is also the only way an applet becomes version-pinned. That is not a side
+note; see [Version Pinning](#version-pinning).
+
+An applet without `attempt@1` is an *app*: no run, no completion, everyone always on the current
+version.
+
+<a name="the-lifecycle"></a>
+## The Lifecycle
+
+```
+launch → in_progress → …work… → complete() → completed → (relaunch lands on the final screen)
+```
+
+```ts
+const launch = await Rack.init({ slug: 'my-applet' });
+
+Rack.attempt.id;          // number | null
+Rack.attempt.status;      // 'in_progress' | 'completed' | null
+Rack.attempt.state();     // your blob, exactly as last saved
+Rack.attempt.segment();   // Record<string, string> | null
+```
+
+Every applet declaring `attempt@1` owes the participant this at boot:
+
+```ts
+if (Rack.attempt.status === 'completed') {
+    return renderFinalScreen();
+}
+
+const saved = Rack.attempt.state<State>() ?? initialState();
+renderStep(saved.step);
+```
+
+<a name="resume-state"></a>
+## Resume State
+
+`state` is a JSON object, capped at **64 KB encoded** (`ziprack-attempt.max_state_bytes`). It is for
+resuming position, plus anything cheap that makes a return visit feel continuous — a draft in a
+textarea, a scroll offset, which cards are flipped.
+
+```ts
+void Rack.attempt.setState({ step: 4, draft: textarea.value });
+```
+
+Call it after every transition. You do not need to debounce: the shell coalesces pending
+`attempt:state` messages so only the latest value is sent in each batch. You do not need to await
+it either — the local copy updates immediately, so `Rack.attempt.state()` reflects your write even
+before the ack lands.
+
+**State is not data capture.** An answer the participant committed belongs in a
+[statement](activity.md); if it exists only in `state`, it will not appear in any export, and a
+completed attempt will freeze it out of reach. The test: if someone would want it in a CSV, it is a
+statement.
+
+<a name="segments"></a>
+## Segments
+
+Segments are the dimensions admins filter and group by — track, cohort, region. Declare them:
+
+```json
+"segments": [
+    {
+        "key": "track",
+        "label": "Track",
+        "values": [
+            { "key": "rd", "label": "R&D" },
+            { "key": "commercial", "label": "Commercial" }
+        ]
+    }
+]
+```
+
+and set them as soon as they are known:
+
+```ts
+await Rack.attempt.setSegment({ track: 'rd' });
+```
+
+At most 20 keys, string values up to 100 characters. The admin UI filters by the **first** declared
+segment, so put the one people will actually slice by first.
+
+Segments also drive activity scoping: an activity declaring `"segment": "track"` is understood to
+exist only for participants in that track, which keeps export columns honest.
+
+<a name="preview-runs"></a>
+## Preview Runs
+
+A participant gets exactly one attempt per applet, which is correct for them and useless for the
+person who has to check the thing works. Staff get a second track:
+
+```
+GET /a/{slug}?preview=1      resume my open preview run
+GET /a/{slug}?preview=new    start a fresh one
+```
+
+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
+it carries a Rack-owned `is_preview` flag, and that flag is not the applet's to set. `attempt@1`
+gives you `setSegment()`; it does not give you a way to declare yourself a preview. An applet cannot
+tell the difference and should not try.
+
+Reporting hides them. The attempts table, the overview counts, the metric cards and the CSV export
+all default to live attempts only:
+
+```http
+GET /ziprack/admin/applets/{applet}/attempts              live runs (the default)
+GET /ziprack/admin/applets/{applet}/attempts?preview=preview
+GET /ziprack/admin/applets/{applet}/attempts?preview=all
+```
+
+Rows carry `is_preview` so a UI showing `preview` or `all` can badge them.
+
+The live attempt keeps `attempt_number` 1 for the lifetime of the applet; preview runs take the
+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.
+
+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.
+
+<a name="completion"></a>
+## Completion
+
+```ts
+await Rack.activity.answer('outro.confidence', 5);   // confirm the last answer first
+await Rack.attempt.complete({ score: 42 });          // optional summary
+```
+
+`complete()` is **idempotent** — calling it twice is not an error, and the second call returns the
+same result. After it:
+
+- `setState()` and `setSegment()` are refused with `completed`.
+- Attempt-scoped [records](database.md) freeze.
+- The Rack flips its own completion chrome, and a relaunch lands on the final screen rather than
+  restarting the experience.
+
+That last point is a contract, not a courtesy: build a final screen worth landing on.
+
+Which is why the Rack's completion card is **dismissible**. It announces the moment once, over the
+top of whatever you just rendered; "Keep looking around" (or Escape) shrinks it to a corner toast
+that keeps the way out without covering your screen. Nothing reopens it, and a relaunch of a
+completed attempt shows no card at all — so the last thing the participant sees is yours, not the
+Rack's.
+
+<a name="version-pinning"></a>
+## Version Pinning
+
+> **Requesting `attempt@1` implies pinned. Its absence implies rolling.**
+
+One rule, derived rather than declared, with no manifest field to get wrong.
+
+**Why they are opposed.** An attempt must stay on the version it started on: activity ids cannot
+shift mid-run without corrupting the export. An app must roll: every participant on the current
+version, always, or people are stranded on stale builds.
+
+Consequences worth knowing before you ship:
+
+- An applet that adds `attempt@1` in a later version changes its own update semantics. The
+  [capability diff](publishing.md#capability-diff-review) flags this prominently, and it requires
+  re-approval.
+- In-progress attempts continue to pin to their starting version after you promote a new one. Two
+  versions run side by side until the last one drains.
+- Changing an activity `id` between versions splits export columns. Changing a `label` only changes
+  the header.