@mieweb/pulsevault 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -7,6 +7,102 @@ breaking changes, called out explicitly below.
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-09-30
+
+Protocol 2.2 (`PROTOCOL.md` §7.4). Protocol 2 records the `uploadUnit`
+removal below as the breaking change it is; clients built for protocol 1
+can't pair with this release.
+
+### Added
+
+- **Read-only view links** (protocol 2.2). The pairing token is a full
+  capability, so a watch link carrying it let anyone holding the link
+  upload to the artifact or delete it. The new `issueViewLink` option turns
+  on `POST {prefix}/artifacts/:id/view-link` (authorized as the new
+  `"share"` phase): for a finished artifact it returns `{ token, expiresAt }`,
+  a token that only opens the artifact and the artifacts `relatedTo` it
+  (`GET ?token=`). The host decides each link's lifetime, or refuses one;
+  PulseVault sets none. `createViewLinkIssuer` / `issueViewToken` /
+  `verifyViewToken` implement it for capability tokens: view tokens carry
+  `use: "view"`, are signed with a key derived from the same secret (so a
+  verifier that predates them rejects one), and `createCapabilityAuthorize`
+  accepts them only for `resolve`. `/capabilities` reports `viewLinks`, and
+  `protocol/schemas/view-link.schema.json` defines the response.
+- **Opt-in cleanup of abandoned uploads.** The `retention` option
+  (`{ abandonedAfterSeconds, sweepIntervalSeconds? }`, on the plugin and
+  `createPulseVaultCore`) sweeps on a timer, removing uploads left
+  unfinished past the cutoff and the related artifacts (never videos) of a
+  video that never finished; finished videos are never touched.
+  `sweepAbandonedUploads` runs one sweep for your own scheduler. Storage
+  adapters gain an optional `listArtifacts`, implemented by both built-in
+  adapters.
+- **`onArtifactEvent` reports removals:** `phase: "remove"`, with `reason:
+  "deleted"` (`DELETE /artifacts/:id` or a TUS `DELETE`) or `"abandoned"` (the
+  `retention` sweep), so a host keeping its own index of artifacts can drop
+  one. A consumer that switches exhaustively on `phase` sees a new value.
+
+- **The protocol is written down as files, and CI keeps it honest.**
+  `protocol/schemas/*.schema.json` define `/capabilities`, pairing links,
+  `Upload-Metadata`, the beat manifest, capability-token claims and the
+  `Pulse-Client` header; `protocol/openapi.json` is generated from the
+  route schemas (`npm run protocol`), and so are the field tables in
+  `PROTOCOL.md`. `scripts/check-protocol.mjs` fails a change that alters the
+  protocol without the right version bump (oasdiff decides what's breaking
+  for the HTTP routes). The `protocol/` folder is published with the package.
+- **`Pulse-Client` request header and `426 Upgrade Required`** (protocol
+  2.1). A client that says its newest protocol is older than this server's
+  oldest gets 426 with the supported range on uploads and artifact
+  requests; `/capabilities` always answers. No header, no change.
+- **`Upload-Metadata.appVersion`** (protocol 2.1): stored with the artifact
+  by both storage adapters and reported on the `complete`/`reject` events
+  (`PulseVaultArtifactEvent.appVersion`).
+- **`protocolRevision`** in `/capabilities`: the spec revision, `major.minor`.
+- **CI** (`.github/workflows/ci.yml`): tests on Node 22 and 24, the protocol
+  checks, the e2e against Postgres, and the Pulse app's contract suite
+  against each PR's build.
+
+### Changed
+
+- **A TUS `DELETE` is authorized as `"delete"`, not `"patch"`.** It now
+  removes the artifact (below), the same as `DELETE /artifacts/:id`, so an
+  `authorize` hook sees one phase for every removal — and a rejected one is
+  reported on `onArtifactEvent` like any other rejected delete. If your hook
+  allows `"patch"` but refuses `"delete"`, clients can no longer cancel an
+  upload through TUS; allow `"delete"` for the artifact's own token.
+- **Breaking: protocol 2.** `/capabilities` reports `protocolVersion: 2` and
+  accepts protocol majors 2–2, read from the new `package.json`
+  `pulseProtocol` field (`{ "version": "2.1", "min": 2, "max": 2 }`).
+
+### Removed
+
+- **Breaking: `uploadUnit` is gone — a pulse uploads as one video; beats are
+  timestamps within it** (#64). A pulse is one video (the artifact named by
+  the pairing link) plus its related captions, beat manifest and thumbnail;
+  a beat is a `startMs`/`endMs` range inside that video, not an upload
+  strategy (`PROTOCOL.md` §8). Concretely:
+  - The `uploadUnit` option is removed from the Fastify plugin and from
+    `createPulseVaultCore`. Passing it now throws a `TypeError` at boot
+    ("`uploadUnit` was removed — delete the option") instead of being
+    silently ignored — delete the option from your config.
+  - `buildUploadLink` no longer accepts or emits an `uploadUnit` param.
+    Links minted by older releases stay valid: clients ignore unknown params
+    (`PROTOCOL.md` §3).
+  - `GET /capabilities` no longer returns an `uploadUnit` field.
+  - Needs Pulse 2.1.0 or later (mieweb/pulse#213) —
+    older Pulse builds require `uploadUnit` in `/capabilities`.
+
+### Fixed
+
+- **A TUS `DELETE` removes the whole artifact.** It used to reach only the
+  tus datastore, so PulseVault's sidecar stayed behind: the artifactId
+  answered every later create with `409`, a finished upload deleted on the
+  local adapter kept a `ready` sidecar pointing at nothing, and on S3 a
+  finished upload wasn't deleted at all (aborting its completed multipart
+  upload fails with `NoSuchUpload` before anything is removed). Termination
+  now runs `storage.remove` under tus's per-upload lock — bytes, tus record
+  and sidecar, in flight or finished. The S3 adapter's `remove` also deletes
+  the incomplete `.part` object @tus/s3-store parks between PATCHes.
+
 ## [0.3.0] - 2026-09-16
 
 ### Changed
@@ -290,6 +386,7 @@ if you've evaluated against an intermediate build.
   lock, so this is now at least surfaced: a one-time `console.warn` fires
   per process the first time a deployment falls into this degraded mode.
 
-[Unreleased]: https://github.com/mieweb/pulsevault/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/mieweb/pulsevault/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/mieweb/pulsevault/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/mieweb/pulsevault/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/mieweb/pulsevault/compare/v0.0.1...v0.2.0

package/OPERATIONS.md

@@ -157,8 +157,8 @@ The entire state of the local adapter lives under `workspaceDir`:
 (bytes). Back it up as a normal filesystem tree — there's no separate database to keep in
 sync. To restore, copy the tree back and restart; in-progress uploads at
 backup time will resume correctly via the normal TUS `HEAD`-then-resume path
-once the client retries, or will simply sit as abandoned partial uploads
-(see "Retention" below) if the client never retries.
+once the client retries, or will sit as abandoned partial uploads until
+`retention` removes them (see "Retention" below) if the client never retries.
 
 ## Web-ready playback (faststart remux + H.264 transcode)
 
@@ -227,11 +227,16 @@ integrity for artifacts this feature has touched.
 
 ## Retention
 
-`pulsevault` has no built-in retention/expiry feature — this is intentionally
-left to the operator (see `PROTOCOL.md` §1 on lifecycle ownership). A sample
-cron script for the local adapter, deleting artifacts whose sidecar has been
-`"uploading"` for longer than a cutoff (abandoned uploads) or that are older
-than a retention window (compliance-driven deletion):
+**Abandoned uploads** — unfinished uploads a client gave up on, and the
+captions, manifest or thumbnail of a video that never finished — are cleaned
+up by the opt-in `retention` option (or `sweepAbandonedUploads` from your own
+scheduler); see the README's `retention` option. Both adapters support it.
+
+How long to keep **finished** content is a policy decision `pulsevault`
+leaves to the operator (see `PROTOCOL.md` §1 on lifecycle ownership). A
+sample cron script for the local adapter, deleting artifacts older than a
+retention window (compliance-driven deletion), alongside the abandoned-upload
+cutoff it predates:
 
 ```ts
 import { readdir, readFile, stat } from "node:fs/promises";
@@ -263,7 +268,9 @@ for (const file of await readdir(sidecarDir)) {
 
 Run this on whatever schedule your retention policy requires. For S3/R2
 storage, prefer your bucket provider's native lifecycle-policy feature (S3
-Lifecycle Rules, R2 Object Lifecycle) over a custom script where available.
+Lifecycle Rules, R2 Object Lifecycle) over a custom script where available —
+and let `retention` handle abandoned uploads, which a lifecycle rule can't tell
+apart from finished ones (it doesn't read the sidecar's status).
 
 ## Secrets management
 
@@ -286,3 +293,12 @@ async function loadKey(kid: string) {
 Rotate by adding the new `kid` to your lookup table alongside the old one,
 switching issuance to the new `kid`, and removing the old entry only after
 its longest-lived outstanding token has expired.
+
+View links (`issueViewLink` / `createViewLinkIssuer`) are signed with a key
+derived from the same secrets, so they rotate with them — and since they can
+be much longer-lived than an upload token, keep a retired `kid` in the table
+as long as the view links you still want working, or remove it to revoke
+every view link signed under it at once. Deleting a video stops its view
+links opening the video (the `GET` then 404s), but the links keep opening its
+related captions, manifest and thumbnail until those are deleted too — by the
+client, or by `retention` once the video has been gone past its cutoff.

package/PROTOCOL.md

@@ -1,6 +1,11 @@
 # Pulse Upload Protocol
 
-**Version 1**
+<!-- BEGIN GENERATED: protocol-version (from package.json pulseProtocol — edit that, then run `npm run protocol`) -->
+| | |
+|---|---|
+| Spec revision | `2.2` |
+| Protocol majors accepted | 2 |
+<!-- END GENERATED: protocol-version -->
 
 This document specifies the wire contract between a Pulse client and any
 server that wants to receive uploads from it. It is independent of
@@ -30,41 +35,33 @@ never the policy behind it.
 ## 2. Capability discovery
 
 A server MUST expose an unauthenticated `GET {prefix}/capabilities` endpoint.
-The response body MUST be a JSON object with at least the following fields:
-
-```json
-{
-  "protocolVersion": 1,
-  "minSupportedVersion": 1,
-  "maxSupportedVersion": 1,
-  "uploadUnit": "segment",
-  "kinds": ["video", "project", "captions", "thumbnail"],
-  "allowedExtensions": { "video": [".mp4"], "project": [".pulse", ".zip"], "captions": [".vtt"], "thumbnail": [".jpg", ".jpeg", ".png"] },
-  "maxUploadSize": 5368709120,
-  "checksum": { "algorithms": ["sha256", "sha1", "md5"] }
-}
-```
-
-- `protocolVersion` (integer, REQUIRED): the version of this document the
-  server implements.
-- `minSupportedVersion`/`maxSupportedVersion` (integer, REQUIRED): the
-  inclusive range of client protocol versions this server accepts. A client
-  SHOULD refuse to pair if its own version falls outside this range, and
-  SHOULD show the user an actionable message ("update the app" /
-  "this server needs an update") rather than a generic error.
-- `uploadUnit` (`"segment"` or `"merged"`, REQUIRED): which upload strategy this
-  deployment expects (§8). The client MUST read this before doing any
-  merge/upload work and branch accordingly. (Note: "beat" no longer refers to
-  an upload unit — it now names a timecode range on the merged timeline; see §8.)
-- `kinds` (array of string, REQUIRED): artifact kinds this server accepts.
-- `allowedExtensions` (object, REQUIRED): allowed file extensions per kind.
-- `maxUploadSize` (integer, REQUIRED): maximum artifact size in bytes.
-- `checksum.algorithms` (array of string, OPTIONAL): digest algorithms this
-  server can verify (§6.3). Absent or empty means the server does not
-  support checksum verification. Note for implementers: this field
-  describes capability, not whether verification is actually wired in for
-  every upload — a server MAY list an algorithm it's capable of checking
-  even for a deployment where the operator hasn't enabled that check.
+Its JSON body is defined by
+[`protocol/schemas/capabilities.schema.json`](protocol/schemas/capabilities.schema.json):
+
+<!-- BEGIN GENERATED: capabilities (from protocol/schemas/capabilities.schema.json — edit that, then run `npm run protocol`) -->
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `protocolVersion` | integer | Yes | Protocol major this server implements. Also sent as the `Protocol-Version` header on every response. |
+| `protocolRevision` | string | Yes | Spec revision this server implements, `major.minor`. The minor counts additions older clients can ignore. |
+| `minSupportedVersion` | integer | Yes | Oldest protocol major this server accepts. Clients whose newest protocol is older get 426 Upgrade Required. |
+| `maxSupportedVersion` | integer | Yes | Newest protocol major this server accepts. |
+| `kinds` | string[] | Yes | Artifact kinds this server accepts. |
+| `allowedExtensions` | object | Yes | Allowed file extensions per kind, lowercase with the leading dot. |
+| `maxUploadSize` | number | Yes | Largest artifact the server accepts, in bytes. |
+| `checksum` | object | Yes | Checksum algorithms accepted in `Upload-Metadata.checksum`. |
+| `viewLinks` | boolean | No | Whether `POST {prefix}/artifacts/<id>/view-link` mints read-only view links (§6.4). Absent before protocol 2.2, which a client treats as false. |
+<!-- END GENERATED: capabilities -->
+
+A client pairs only if its protocol range overlaps
+`[minSupportedVersion, maxSupportedVersion]` (§7). If it doesn't, the client
+MUST NOT pair, and SHOULD show an actionable message ("update the app" /
+"this server needs an update") rather than a generic error. A client MUST
+ignore fields it doesn't recognize.
+
+`checksum.algorithms` describes capability, not whether verification is
+actually wired in for every upload — a server MAY list an algorithm it's
+capable of checking even where the operator hasn't enabled that check. A
+client MUST treat an absent or empty list as "no checksum verification".
 
 A server response to this endpoint MUST NOT include any secret. Every other
 response from the server MUST include a `Protocol-Version` header carrying
@@ -75,7 +72,7 @@ the integer from `protocolVersion`.
 A server presents a pairing link or QR code of the form:
 
 ```
-pulsecam://?v=1&artifactId=<uuid>&server=<origin>&token=<opaque>&uploadUnit=<segment|merged>
+pulsecam://?v=1&artifactId=<uuid>&server=<origin>&token=<opaque>
 ```
 
 - `v` (REQUIRED): the deep-link schema version. A client MUST refuse and
@@ -97,17 +94,10 @@ pulsecam://?v=1&artifactId=<uuid>&server=<origin>&token=<opaque>&uploadUnit=<seg
   `artifactId` (or a session it anchors, §5.4), not a standing general
   credential — see §5.4 for the recommended (but not required) capability-
   token shape.
-- `uploadUnit` (OPTIONAL, `"segment"` or `"merged"`): per-session override of the
-  deployment-wide value reported by `GET /capabilities` (§2, §8). When
-  present, a client MUST use this value for the session anchored to this
-  link instead of whatever `/capabilities` currently reports, and MUST NOT
-  perform a separate `/capabilities` fetch just to decide merge/upload
-  strategy for it. When absent, a client MUST fall back to `/capabilities`
-  exactly as before this field existed — an operator that never sets it sees
-  no change in client behavior. This lets one deployment run "segment" and
-  "merged" sessions concurrently (e.g. a staged rollout) without racing a
-  single, deployment-wide `/capabilities` value against whichever moment a
-  client happened to fetch it.
+
+A client SHOULD ignore query params it does not recognize, so links minted by
+an older or newer server stay valid. The parameters are defined by
+[`protocol/schemas/deep-link.schema.json`](protocol/schemas/deep-link.schema.json).
 
 A client SHOULD display the server's origin (and, where feasible, its TLS
 certificate fingerprint) to the user before uploading anything, rather than
@@ -124,7 +114,7 @@ core protocol (creation + core resumable upload). A server MUST mount:
 | `POST` | `{prefix}/upload` | Create a resumable upload |
 | `PATCH` | `{prefix}/upload/<id>` | Append a chunk at `Upload-Offset` |
 | `HEAD` | `{prefix}/upload/<id>` | Query the current offset |
-| `DELETE` | `{prefix}/upload/<id>` | Cancel an in-flight upload |
+| `DELETE` | `{prefix}/upload/<id>` | Delete the upload and its artifact, in flight or finished |
 
 `PATCH` bodies MUST be the raw bytes for that offset
 (`Content-Type: application/offset+octet-stream`) — never base64-encoded or
@@ -135,14 +125,21 @@ wrapped in another envelope.
 The TUS `Upload-Metadata` header (comma-separated `<key> <base64(value)>`
 pairs) MUST be parsed for at least:
 
-| Key | Required | Description |
-|---|---|---|
-| `artifactId` | Yes (or a legacy `videoid`/`projectid` alias) | UUID for this artifact. |
-| `filename` | Yes | Original filename; extension validated against `kind`'s allowed list. |
-| `kind` | No, defaults to `video` | `video`, `project`, `captions`, or `thumbnail`. |
-| `relatedTo` | No | UUID of another artifact this one belongs to (§8). |
-| `checksum` | No | `<algorithm>:<hex digest>` of the finished file (§6.3). |
-| `name` | No | Free-form UTF-8 display title for the artifact (e.g. the draft name typed on the capture device). Trimmed and length-capped by the server; persisted for consumers to label the artifact. Display metadata only — it MUST NOT influence storage paths, routing, or authorization, and consumers MUST escape it for their output context. |
+<!-- BEGIN GENERATED: upload-metadata (from protocol/schemas/upload-metadata.schema.json — edit that, then run `npm run protocol`) -->
+| Key | Type | Required | Description |
+|---|---|---|---|
+| `artifactId` | string (uuid) | Yes | The artifact's id. For the video it's the pairing link's `artifactId`; related artifacts use a fresh UUID. Legacy aliases `videoid` and `projectid` are still accepted. |
+| `filename` | string | Yes | Original file name. Its extension must be allowed for `kind` (see `/capabilities`). |
+| `kind` | `video`, `project`, `captions`, `thumbnail` | No | Artifact kind. Defaults to `video`. |
+| `relatedTo` | string (uuid) | No | The artifact this one belongs to: the video, for its captions, beat manifest and thumbnail. A capability token for the video also authorizes artifacts related to it. |
+| `checksum` | string | No | `<algorithm>:<hex digest>` of the finished file, verified by servers that check checksums. |
+| `name` | string | No | Display title (the draft name), sent on the video. Display-only; servers trim and cap it. |
+| `appVersion` | string | No | Since 2.1. Version of the app that uploaded it, e.g. `2.1.0 (45)`. Stored with the artifact. Display-only; servers trim and cap it. |
+<!-- END GENERATED: upload-metadata -->
+
+`name` and `appVersion` are display metadata only: they MUST NOT influence
+storage paths, routing, or authorization, and consumers MUST escape them for
+their output context.
 
 Metadata values are base64 per the TUS spec; a free-form value such as `name`
 MUST be base64 of its **UTF-8** bytes. A client that base64-encodes a raw
@@ -151,9 +148,9 @@ emoji), so encode the UTF-8 bytes explicitly.
 
 A client MUST always send `artifactId` (not only the legacy aliases) on new
 uploads. A server MUST continue accepting `videoid`/`projectid` as aliases
-for `artifactId` for back-compat with clients built against protocol
-version 1 before this alias was the only spelling — this alias requirement
-holds for the lifetime of protocol version 1.
+for `artifactId` for back-compat with clients built before `artifactId`
+was the only spelling — this alias requirement holds until a protocol major
+removes it (§7).
 
 ### 4.2 Resumption
 
@@ -246,14 +243,27 @@ expired token. `issuer` prevents a token minted by one deployment from being
 replayed against a different one that happens to share a secret. A token MAY
 authorize an artifact other than the one it names if that artifact declares
 the token's `artifactId` as its `relatedTo` (§8) — this lets one token cover
-an entire upload session (a merged video plus its captions, beat manifest and
-thumbnail, or every clip plus the ordering manifest under
-`uploadUnit: "segment"`) rather than requiring one token per artifact.
+an entire upload session (a pulse's video plus its captions, beat manifest and
+thumbnail) rather than requiring one token per artifact.
 
 This shape is exactly what `@mieweb/pulsevault`'s `issueCapabilityToken`/
 `verifyCapabilityToken`/`createCapabilityAuthorize` implement, but any server
 is free to use its own scheme entirely — only §5.1–§5.3 are normative.
 
+### 5.5 View tokens (non-normative)
+
+The pairing token is a full capability: whoever holds it can upload to the
+artifact, delete it, and create artifacts related to it. A watch link that
+carries it is unsafe to share. A server that offers view links (§6.4) mints a
+separate **view token** that only opens an artifact and the artifacts
+`relatedTo` it. `@mieweb/pulsevault`'s view token has the §5.4 claims plus
+`"use": "view"`, and is signed with a key derived from the deployment's
+secret, so a verifier that predates view tokens rejects one outright instead of
+treating it as an upload capability. `createCapabilityAuthorize` accepts it
+only for `GET {prefix}/artifacts/<id>` (the `resolve` phase); minting a view
+link (`share`) needs the pairing token itself, so a view link can't extend
+itself.
+
 ## 6. Storage and validation
 
 ### 6.1 Readiness
@@ -269,6 +279,8 @@ A server MUST expose `GET {prefix}/artifacts/<artifactId>` returning either
 the bytes directly or a redirect to a URL serving them (e.g. a presigned
 object-storage URL). The kind is resolved server-side; it is not encoded in
 this URL. A server MUST also expose `DELETE {prefix}/artifacts/<artifactId>`.
+A TUS `DELETE {prefix}/upload/<id>` removes the artifact the same way,
+whether its upload is in flight or finished.
 
 ### 6.3 Checksum (optional)
 
@@ -280,63 +292,133 @@ verification on the finished artifact — it does not substitute for
 in-transit (TLS) integrity, and does not verify individual chunks as they
 arrive.
 
-## 7. Versioning
+### 6.4 View links (optional, protocol 2.2)
 
-A server MUST report `protocolVersion`, `minSupportedVersion`, and
-`maxSupportedVersion` via `/capabilities` (§2) and `Protocol-Version` on
-every response. A client encountering a server whose supported range
-excludes its own version MUST NOT attempt to pair, and SHOULD surface a
-clear, specific message rather than a generic failure.
-
-## 8. Artifact relationships (`relatedTo`) and `uploadUnit`
-
-A pulse (a short composed of one or more recorded **segments**) MAY be uploaded
-as a single pre-merged video (`uploadUnit: "merged"`) or as individual
-per-segment artifacts plus an ordering manifest (`uploadUnit: "segment"`) — the
-operator declares which via `/capabilities` (§2), optionally overridden per
-session via the pairing link's `uploadUnit` param (§3); this document does not
-prefer one over the other.
-
-> **Terminology:** a **segment** is a recorded clip (the source unit). A
-> **beat** is a *timecode range on the merged timeline* — one recorded
-> segment's start/end within the merged video — carried only in the merged
-> mode's beat manifest below. (Earlier revisions used "beat" for what is now
-> called the `segment` upload unit; that meaning is retired.)
-
-Under `uploadUnit: "segment"`, a client uploads each segment under its own
-`artifactId`, plus exactly one **ordering manifest** artifact (`kind:
-"project"`, e.g. `<draftId>-segments.pulse`, a JSON document listing the
-ordered segment `artifactId`s). Segmented mode carries **no** captions and
-**no** thumbnail.
+A server that reports `viewLinks: true` in `/capabilities` (§2) MUST expose
+`POST {prefix}/artifacts/<artifactId>/view-link`. Authorized with the pairing
+token (§5.1), it returns a read-only link to a **finished** artifact:
 
 ```json
-{ "version": 1, "segments": [ { "artifactId": "<uuid>", "order": 0 } ] }
+{ "token": "<view token>", "expiresAt": 1790000000 }
+```
+
+The token opens the artifact, and the artifacts `relatedTo` it, as
+`GET {prefix}/artifacts/<artifactId>?token=<token>` until `expiresAt` (seconds
+since the Unix epoch) — and does nothing else, so it is safe to share (§5.5).
+The server decides how long each link works. It returns `404` for an artifact
+that isn't finished (or when view links aren't enabled), and `403` when it
+won't link to that artifact. A client that wants a shareable link asks for one
+right after the upload finishes, while its pairing token is still valid; a
+server without `viewLinks` offers no shareable link, and the client MUST NOT
+share the pairing token in its place.
+
+## 7. Versioning
+
+The protocol has a version `major.minor`, written once in `@mieweb/pulsevault`'s
+`package.json` (`pulseProtocol`) — the reference implementation reads it from
+there, and npm keeps it for every published release.
+
+- The **major** changes only for breaking changes. It's `protocolVersion` in
+  `/capabilities` and the `Protocol-Version` header, and it's what pairing
+  compares.
+- The **minor** counts additions an older client or server can safely ignore
+  (a new optional field, key or header). It's `protocolRevision`.
+
+A server MUST report `protocolVersion`, `protocolRevision`,
+`minSupportedVersion` and `maxSupportedVersion` via `/capabilities` (§2), and
+`Protocol-Version` on every response. A client supports a range of majors;
+it pairs only if that range overlaps the server's, and speaks the highest
+major both support. If they don't overlap, it MUST NOT pair, and SHOULD
+surface a clear, specific message rather than a generic failure.
+
+### 7.1 Changing the protocol
+
+Every fact about the protocol lives in `protocol/`: the JSON Schemas in
+`protocol/schemas/`, and `protocol/openapi.json`, generated from the plugin's
+route schemas. The field tables in this document are generated from the same
+files (`npm run protocol`). CI enforces the rules:
+
+- Anything under `protocol/` changes → `pulseProtocol.version` MUST change.
+- A **breaking** change — removing a field, key or parameter; making one
+  required; removing an allowed value; changing a type — MUST bump the major.
+  Anything else bumps the minor.
+- Every version MUST have a row in the history below saying what changed.
+
+### 7.2 `Pulse-Client` (since 2.1)
+
+A client SHOULD send `Pulse-Client` on every request, saying what it is and
+which protocol majors it speaks:
+
+```
+Pulse-Client: Pulse/2.1.0 (45; ios); protocol=1-2
 ```
 
-Under `uploadUnit: "merged"`, a client uploads one pre-merged video as the
-session anchor, plus (all as related artifacts):
+On uploads and artifact requests, a server MUST answer
+`426 Upgrade Required` when the client's newest major is older than the
+server's `minSupportedVersion`, with a JSON body carrying `error`,
+`minSupportedVersion` and `maxSupportedVersion`. `/capabilities` MUST always
+answer, so the client can learn why. A request without the header is handled
+as before this header existed. A client that gets `426` SHOULD tell the user
+to update the app. See
+[`protocol/schemas/pulse-client.schema.json`](protocol/schemas/pulse-client.schema.json).
+
+A client SHOULD also check `/capabilities` again before starting an upload to
+a server it paired with earlier: a server can be upgraded in between.
+
+### 7.3 Where it's defined
+
+<!-- BEGIN GENERATED: schemas (from protocol/schemas/ — edit that, then run `npm run protocol`) -->
+| File | Defines |
+|---|---|
+| [`openapi.json`](protocol/openapi.json) | Every HTTP route, generated from the plugin |
+| [`beat-manifest.schema.json`](protocol/schemas/beat-manifest.schema.json) | Beat manifest |
+| [`capabilities.schema.json`](protocol/schemas/capabilities.schema.json) | GET /capabilities response |
+| [`capability-token.schema.json`](protocol/schemas/capability-token.schema.json) | Capability token claims |
+| [`deep-link.schema.json`](protocol/schemas/deep-link.schema.json) | Pairing link query parameters |
+| [`pulse-client.schema.json`](protocol/schemas/pulse-client.schema.json) | Pulse-Client request header |
+| [`upload-metadata.schema.json`](protocol/schemas/upload-metadata.schema.json) | TUS Upload-Metadata keys |
+| [`view-link.schema.json`](protocol/schemas/view-link.schema.json) | POST /artifacts/<id>/view-link response |
+<!-- END GENERATED: schemas -->
+
+### 7.4 History
+
+| Version | Change |
+|---|---|
+| 1.0 | First version. `/capabilities` and pairing links carried `uploadUnit` (`segment` or `merged`). |
+| 2.0 | **Breaking:** `uploadUnit` removed from `/capabilities` and pairing links — a pulse always uploads as one video (§8). Clients built for 1.0 required it. |
+| 2.1 | Added `protocolRevision` to `/capabilities`, the `Pulse-Client` header with `426 Upgrade Required` (§7.2), and `Upload-Metadata.appVersion` (§4.1). |
+| 2.2 | Added read-only view links: `viewLinks` in `/capabilities`, `POST {prefix}/artifacts/<id>/view-link` (§6.4), and the view token's `use` claim (§5.5). |
+
+## 8. Artifact relationships (`relatedTo`)
+
+A pulse (a short composed of one or more recorded clips) uploads as **one
+video** — the session anchor, named by the pairing link's `artifactId` (§3) —
+plus these related artifacts:
 
 - **captions** (`kind: "captions"`, `<draftId>.vtt`) — WebVTT for the whole
-  merged video, OPTIONAL (absent when the video has no speech or no on-device
-  model was available); MAY carry word-level inline cue timestamps like
+  video, OPTIONAL (absent when the video has no speech or no on-device model
+  was available); MAY carry word-level inline cue timestamps like
   `<00:00:01.500>word` for karaoke rendering;
-- a **beat manifest** (`kind: "project"`, e.g. `<draftId>-beats.pulse`) giving
-  each recorded segment's precise `startMs`/`endMs` on the merged timeline,
-  contiguous and summing to the true merged `durationMs` (groundwork for
-  keyframe-aligned deep links / HLS);
+- a **beat manifest** (`kind: "project"`, e.g. `<draftId>-beats.pulse`)
+  listing the pulse's beats (below);
 - a **thumbnail** (`kind: "thumbnail"`, `<draftId>.jpg`) — the pulse's poster
   frame.
 
+A **beat** is a timestamp range inside the video: where one recorded clip
+starts and ends (`startMs`/`endMs`). A pulse's beats are contiguous and sum to
+the video's `durationMs`. The beat manifest is groundwork for keyframe-aligned
+deep links / HLS; it does not change how the video is uploaded.
+
 ```json
 { "version": 1, "type": "beat-manifest", "durationMs": 47320,
   "beats": [ { "segmentId": "<local id>", "order": 0, "startMs": 0, "endMs": 4210 } ] }
 ```
 
-Every non-anchor artifact in either session SHOULD declare `relatedTo` pointing
-at the session's anchor `artifactId` (the one named in the pairing link) so a
-single capability token can authorize the whole session (§5.4).
+Every non-anchor artifact SHOULD declare `relatedTo` pointing at the anchor
+`artifactId` so a single capability token can authorize the whole session
+(§5.4).
 
-The relational graph of replies between segments/pulses (who replied to what,
+The relational graph of replies between pulses (who replied to what,
 rendering a thread) is explicitly **out of scope** for this document. That
 graph is a query/relational concern for the operator's own systems, built
 from `relatedTo` and whatever additional metadata the operator chooses to
@@ -347,5 +429,5 @@ record — not something a Pulse-compatible server is required to implement.
 A client or server MAY support additional, non-normative extensions to this
 contract (additional `Upload-Metadata` keys, additional kinds, additional
 `/capabilities` fields) as long as doing so does not break a client/server
-that only implements what's written here. New REQUIRED fields MUST NOT be
-added to a response without a `protocolVersion` bump.
+that only implements what's written here. Changes to the protocol itself
+follow §7.1.