@ziprack/sdk 0.1.1 → 0.2.0

package/dist/docs/attempts.md

@@ -0,0 +1,184 @@
+# 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 the `ziprack.admin` ability. 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.
+
+What preview does **not** do is partition capability storage. Statements and records belong to their
+attempt and follow it, but per-applet aggregates — [`ai@1`](ai.md) spend, the
+[`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.

package/dist/docs/auth.md

@@ -0,0 +1,106 @@
+# Authentication — `auth@1`
+
+- [Introduction](#introduction)
+- [Declaring Attributes](#declaring-attributes)
+- [Reading the Participant](#reading-the-participant)
+- [Degrading Gracefully](#degrading-gracefully)
+- [Rack Side](#rack-side)
+
+<a name="introduction"></a>
+## Introduction
+
+`auth@1` answers one question for the applet — *who is this, and what am I allowed to know about
+them* — and one question for the deployment: *what can applets see about our people?* The second is
+the question a client's procurement team will ask, and this capability is where it has a single
+answer.
+
+Profile attributes are **Rack-owned and applet-requested**. Never applet-written. There is no
+`Rack.auth.set()`, and there never will be within `auth@1`.
+
+This capability has no runtime messages at all: the released profile travels in the launch payload.
+
+<a name="declaring-attributes"></a>
+## Declaring Attributes
+
+```json
+"requires": {
+    "capabilities": ["auth@1"],
+    "profile": ["display_name", "business_unit", "locale"]
+}
+```
+
+Keys match `^[a-z][a-z0-9_]*$`. Requesting an attribute is not obtaining it: the deployment's
+`ziprack-auth.php` lists what may ever be released, and anything outside that list is withheld
+silently.
+
+```php
+// config/ziprack-auth.php
+'releasable' => ['display_name', 'email', 'locale'],   // ZIPRACK_AUTH_RELEASABLE
+
+'claim_map' => [
+    'display_name' => 'name',
+    'email' => 'email',
+],
+```
+
+`display_name` is always released. Values stored through a roster import or `ziprack:profile:set`
+override the claim map, which is how attributes that do not exist on the user model — cohort,
+business unit, region — reach an applet.
+
+<a name="reading-the-participant"></a>
+## Reading the Participant
+
+```ts
+const launch = await Rack.init({ slug: 'my-applet' });
+
+launch.actor;                 // { id, name } — always present, no capability needed
+Rack.auth.user();             // { id, display_name, …released attributes } | null
+
+Rack.auth.attribute('business_unit');              // unknown → null
+Rack.auth.attribute('locale', 'en');               // unknown → 'en'
+Rack.auth.attribute<string[]>('regions', []);      // typed
+```
+
+Both are synchronous reads of launch data, so they are free to call in a render path.
+
+`actor` is the participant the Rack resolved: a logged-in user, or a cookie-keyed guest when the
+deployment enables guests. `Rack.auth.user()` is the *profile*, and exists only when `auth@1` is
+declared.
+
+<a name="degrading-gracefully"></a>
+## Degrading Gracefully
+
+An attribute you requested may be absent because the deployment does not release it, because nobody
+imported it, or because this participant is a guest. All three look the same to you, and all three
+must work.
+
+```ts
+const unit = Rack.auth.attribute<string>('business_unit');
+
+const intro = unit
+    ? `Here is what the ${unit} team said last quarter.`
+    : `Here is what your colleagues said last quarter.`;
+```
+
+Design the withheld path first and treat personalisation as an enhancement. An applet that renders
+`Hello, undefined` when an attribute is missing has failed validation of a kind the Rack cannot
+perform for you.
+
+<a name="rack-side"></a>
+## Rack Side
+
+```sh
+php artisan ziprack:profile:set ada@example.com business_unit "R&D"
+php artisan ziprack:roster:import people.csv      # email column + one column per attribute
+```
+
+Admin endpoints:
+
+| Route | Purpose |
+|---|---|
+| `GET /ziprack/admin/participants/{participant}/profile` | Current attributes and their sources. |
+| `PUT /ziprack/admin/participants/{participant}/profile` | Set attributes for one person. |
+
+To source attributes from SSO claims instead, bind
+`ZipRack\Auth\Contracts\ProfileAttributeSource`; `ClaimMapSource` is the default implementation and
+a reasonable starting point.

package/dist/docs/broadcast.md

@@ -0,0 +1,226 @@
+# Broadcast — `broadcast@1`
+
+- [Introduction](#introduction)
+- [Rooms](#rooms)
+- [Declaring Channels and Facilitator Events](#declaring-channels-and-facilitator-events)
+- [Joining and Publishing](#joining-and-publishing)
+- [Inviting People In](#inviting-people-in)
+- [Presence](#presence)
+- [Shared State](#shared-state)
+- [The Facilitator Role](#the-facilitator-role)
+- [Developing Against Rooms](#developing-against-rooms)
+
+<a name="introduction"></a>
+## Introduction
+
+`broadcast@1` is what makes group work repeatable: a climb with base camps, teams on separate
+boards, a live trivia round, a facilitated card game. It gives an applet rooms, presence, published
+events, a facilitator role and a shared key/value state.
+
+**The Rack holds the WebSocket, not the applet.** You publish and subscribe over `postMessage`; the
+Rack owns the socket and its authentication. An applet can never obtain or leak a channel token,
+and the trust model is identical to every other capability.
+
+Transport is Laravel Reverb. That is a deployment concern: nothing in the applet API mentions it.
+
+<a name="rooms"></a>
+## Rooms
+
+A **room** is an applet version 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.
+
+Rooms are created by an admin, or from the console:
+
+```sh
+php artisan ziprack:room:create team-summit --name="Boston cohort" --mode=first_in
+# → join code: 7FQK2M   →  https://rack.example.com/r/7FQK2M
+```
+
+Participants arrive by code or QR, which is how CN already runs events.
+
+| Mode | Facilitator assignment |
+|---|---|
+| `opt_in` | Anyone in the room may claim the role. |
+| `first_in` | Granted automatically to the first joiner. |
+| `roster` | A preset list of people, resolved through `auth@1`. |
+
+Only `roster` depends on `auth@1`, so light group activities can run without an identity source at
+all — see [guests](installation.md#participants-and-guests).
+
+The room arrives in launch data:
+
+```ts
+Rack.broadcast.room;            // { id, code, name, status, mode } | null
+Rack.broadcast.role;            // 'participant' | 'facilitator' | null
+Rack.broadcast.isFacilitator;
+Rack.broadcast.members();       // RoomMember[]
+```
+
+`room` is `null` when the applet was launched outside a room. Handle it: the same applet is often
+launched both ways.
+
+<a name="declaring-channels-and-facilitator-events"></a>
+## Declaring Channels and Facilitator Events
+
+```json
+"broadcast": {
+    "channels": ["main", "board"],
+    "facilitator_events": ["advance", "lock", "reveal"]
+}
+```
+
+Channels default to `["main"]` if you declare none, cap at 20, and are namespaced to the room — an
+applet cannot address another room's channel. `$room` is reserved for the Rack.
+
+**`facilitator_events` is enforcement, not documentation.** An event named there is refused with
+`forbidden` unless the sender currently holds the facilitator role. Facilitator control is therefore
+not a separate capability: advancing, locking and revealing are ordinary events the Rack polices,
+and the applet decides what they mean.
+
+<a name="joining-and-publishing"></a>
+## Joining and Publishing
+
+```ts
+const main = await Rack.broadcast.join('main');
+
+const stop = main.listen<{ step: number }>('advance', (payload, from) => {
+    goToStep(payload.step);                       // from.participant_id, from.role
+});
+
+main.listen('*', ({ event, payload }) => log(event, payload));
+
+if (Rack.broadcast.isFacilitator) {
+    await main.publish('advance', { step: 3 });
+}
+
+stop();                 // unsubscribe one listener
+await main.leave();     // leave the channel
+```
+
+Payloads cap at 16 KB (`ziprack-broadcast.max_event_bytes`). Every published event is persisted, so
+the admin can replay a session's facilitator timeline afterwards.
+
+Events are delivered to everyone in the room, including the sender. Design handlers to be idempotent
+and to tolerate arriving out of order relative to your own optimistic updates.
+
+<a name="inviting-people-in"></a>
+## Inviting People In
+
+An applet on a projector often *is* the way people get into the room. Ask the Rack where to
+point them:
+
+```ts
+const { ok, data } = await Rack.broadcast.invite();
+// data → { code: '7FQK2M', url: 'https://rack.example.com/r/7FQK2M' }
+```
+
+The Rack holds the URL because a sandboxed applet cannot see the Rack's host, and the join
+prefix is a deployment setting (`ZIPRACK_ROOM_PREFIX`). What you do with it is yours: print the
+code on a slide, render the URL as a QR with whatever library you already bundle, or both.
+
+```ts
+if (ok) {
+    board.append(qr(data.url));       // your encoder, your styling
+    code.textContent = data.code;
+}
+```
+
+There is no facilitator gate. The room code is already in every member's launch payload and can
+be read aloud in two seconds, so refusing the URL would protect nothing and would break the rule
+that an applet stays usable while nobody holds the role.
+
+The call is **refused with `conflict` once the room is locked or closed**, because `/r/{code}`
+turns those scanners away. Handle it — that is the signal to take a stale QR off the screen:
+
+```ts
+Rack.broadcast.on('status', async ({ status }) => {
+    board.hidden = status !== 'open';
+});
+```
+
+Non-members get `forbidden`, as they do for `presence`. In mock mode the invite is the dev
+server page itself, so scanning it opens the second tab that forms the room.
+
+<a name="presence"></a>
+## Presence
+
+```ts
+const { data } = await Rack.broadcast.presence();
+data.members;   // [{ id, name, role, present }]
+
+Rack.broadcast.on('presence', ({ members }) => renderRoster(members));
+```
+
+A member counts as present when seen within 45 s (`ziprack-broadcast.presence_window_seconds`); the
+shell heartbeats for you. Treat presence as approximate — it is a roster, not a lock.
+
+Room-level events you can subscribe to:
+
+| Event | Payload |
+|---|---|
+| `presence` | `{ members }` |
+| `state` | `{ key, value, version }` |
+| `role` | `{ role, participant_id }` |
+| `status` | `{ status }` — `open`, `locked`, `closed` |
+
+<a name="shared-state"></a>
+## Shared State
+
+Server-authoritative, last write wins **per key**, with the Rack stamping a version.
+
+```ts
+await Rack.broadcast.state.set('phase', 'voting');
+
+const { data } = await Rack.broadcast.state.get(['phase', 'timer']);
+Rack.broadcast.state.snapshot();       // launch snapshot + everything pushed since, synchronously
+
+Rack.broadcast.on('state', ({ key, value, version }) => apply(key, value));
+```
+
+Up to 200 keys, 16 KB per value. Use it for the small facts everyone must agree on — the current
+phase, which card is face up, whether submissions are open — and use [`db@1`](database.md) room
+collections for the content itself.
+
+This is deliberately not a CRDT. If two people write the same key at the same moment, one of them
+wins and everyone converges on that value. Design keys so that matters as little as possible:
+one writer per key is the intended shape, and a facilitator-only key is the easiest way to get it.
+
+<a name="the-facilitator-role"></a>
+## The Facilitator Role
+
+```ts
+await Rack.broadcast.claim();                 // opt_in rooms
+await Rack.broadcast.transfer(participantId); // hand it on
+
+Rack.broadcast.on('role', ({ role, participant_id }) => {
+    if (participant_id === launch.actor.id) renderFacilitatorControls(role === 'facilitator');
+});
+```
+
+**The grant must survive a dropped connection.** A facilitator unseen for 60 s
+(`ziprack-broadcast.facilitator_grace_seconds`) is vacated by `ziprack:rooms:tick`, and in a
+`first_in` room the role is reassigned automatically. Schedule that command every minute, or a
+closed laptop strands a room.
+
+Build the participant view first and layer facilitator controls on top of it. Every applet using
+rooms must be usable in the window where nobody holds the role.
+
+<a name="developing-against-rooms"></a>
+## Developing Against Rooms
+
+Mock mode implements rooms over `BroadcastChannel`, so **two tabs of your dev server form a room**.
+Presence, published events, shared state and role transfer all work between them; the first tab to
+open takes the facilitator role by default.
+
+```json
+"broadcast": { "channels": ["main"], "facilitator_events": ["advance"], "mock_mode": "opt_in" }
+```
+
+`mock_mode` is read only by the mock and lets you rehearse `opt_in` claiming locally. For automated
+tests, drive the other side explicitly:
+
+```ts
+host.push({ event: 'advance', payload: { step: 2 }, channel: 'main',
+            from: { participant_id: 99, role: 'facilitator' } });
+```

package/dist/docs/conformance.md

@@ -0,0 +1,102 @@
+# Conformance
+
+- [Why It Exists](#why-it-exists)
+- [Running the Suite](#running-the-suite)
+- [What It Checks](#what-it-checks)
+- [In CI](#in-ci)
+- [Fleet Visibility](#fleet-visibility)
+
+<a name="why-it-exists"></a>
+## Why It Exists
+
+zipRACK's central promise is that an applet built against one Rack runs on another. Without
+something that verifies it, "standalone Racks united by a common format" is an aspiration.
+
+`ziprack/conformance` is a dev dependency every Rack installs and runs in CI. It asserts the
+deployment still honours `ziprack/1` — including a Rack someone has customised, which is exactly the
+case where you want proof rather than good intentions.
+
+<a name="running-the-suite"></a>
+## Running the Suite
+
+```sh
+php artisan ziprack:conformance
+php artisan ziprack:conformance --json
+```
+
+The suite runs inside a transaction that is rolled back, so it is safe against a live database. Each
+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
+```
+
+<a name="what-it-checks"></a>
+## What It Checks
+
+Core checks run on every Rack:
+
+| Check | Asserts |
+|---|---|
+| `ManifestRequiresSchema` | A manifest missing or misstating `schema` fails validation with the expected error. |
+| `InstallerRejectsUnsafeZips` | A zip containing `..`, an absolute path or a symlink is refused. |
+| `UnimplementedCapabilityIsRefused` | An applet requesting a capability this Rack lacks is refused at install. |
+| `UndeclaredCapabilityIsRefused` | A runtime call the manifest did not declare acks `undeclared_capability`. |
+| `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. |
+
+Each installed capability contributes its own, so the suite grows with the Rack:
+
+| Check | Capability |
+|---|---|
+| `CompletedAttemptIsFrozen`, `AttemptsArePinned` | `attempt` |
+| `StatementsAreAppendOnly` | `activity` |
+| `RecordsAreScopedAndValidated` | `db` |
+| `UploadsAreScopedAndTyped` | `storage` |
+| `AiBudgetsAreEnforced` | `ai` |
+| `FacilitatorEventsAreEnforced` | `broadcast` |
+
+<a name="in-ci"></a>
+## In CI
+
+Publish a test that runs the suite inside the deployment's own Pest or PHPUnit run:
+
+```sh
+php artisan ziprack:conformance:install
+```
+
+which writes `tests/Feature/ZipRackConformanceTest.php`. From then on the deployment's normal test
+command is also its conformance gate, and a customisation that breaks the contract fails the build
+rather than a client's security review.
+
+<a name="fleet-visibility"></a>
+## Fleet Visibility
+
+```sh
+php artisan ziprack:status
+php artisan ziprack:status --json
+```
+
+```http
+GET /ziprack/health        # Authorization: Bearer {ZIPRACK_HEALTH_TOKEN}
+```
+
+Both report the format string, the core version, every installed capability package with the
+capability versions it implements, and any warnings a capability raises — for example
+`storage@1` running the null scanner, or a CSP host configuration that would reopen an exfiltration
+channel.
+
+The question this answers is **"which deployments still need the fix?"** without SSH-ing into eight
+machines. That question gets asked during a client security review, usually with a deadline
+attached.