@mieweb/pulsevault 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,106 @@ breaking changes, called out explicitly below.
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-05
+
+Protocol 2.3 (`PROTOCOL.md` §7.4). What every host rebuilt around PulseVault
+(#80), in the core: the shape of a pulse, a completion that survives a throw
+or a restart, a lock on finished pulses, the token's own context, a status
+route, background web-ready, a poster route and `getPulse`, and the content
+types phones send. Two defaults change; both have an escape hatch.
+
+### Changed (breaking)
+
+- **A create must have the shape of a pulse** (`pulseShape`, on by default):
+  a video with no `relatedTo`; a thumbnail, beat manifest or captions under
+  its own id, `relatedTo` the video. With `createCapabilityAuthorize` the ids
+  are also tied to the token: the video only under the token's own
+  `artifactId`, the rest only `relatedTo` it. Before, one token could create
+  any number of artifacts under ids the client picked, or take the video's
+  own id with a thumbnail so the real video answered `409` for good. The
+  Pulse app has always uploaded in this shape. For uploads that aren't
+  pulses, pass `pulseShape: false` to the plugin or core *and* to
+  `createCapabilityAuthorize`.
+- **A create reclaims an idle unfinished upload of the same artifactId**
+  (`reclaim`, `{ idleSeconds: 300 }` by default): an app killed mid-upload
+  sends no TUS `DELETE`, so re-scanning the same link answered `409` until
+  `retention` ran. Only an upload of the same kind and `relatedTo` is taken
+  over (the same token authorized both), and only once the local adapter has
+  seen no bytes for `idleSeconds`. `reclaim: false` keeps the old `409`.
+- **`onUploadComplete` is at-least-once.** PulseVault records that the hook
+  returned (`acknowledged` in the sidecar) and fires it again, with
+  `ctx.replay: true`, for a finished artifact it never recorded: the hook
+  threw, or the process stopped first. Every 300 seconds, with the first pass
+  shortly after start (`replayCompletions`; `false` turns it off, and
+  `core.replayCompletions()` / `fastify.pulseVaultCore.replayCompletions()`
+  runs a pass on demand). Hosts must check their own record before writing
+  it again. Finished sidecars written before this release read as acknowledged, so an
+  upgrade replays nothing; one still uploading at the upgrade completes
+  normally. A retried final `PATCH` no longer fires the hook a
+  second time.
+- **`authorize` gains the `status` phase** (`GET /artifacts/:id/status`).
+  An exhaustive `switch` on the phase needs a case for it.
+- **Content types**: the `.pulse` beat manifest is served as
+  `application/json`, and `.mov`, `.m4v` and `.srt` — when a host allows them
+  in `allowedExtensions`; the defaults stay what the Pulse app sends — as
+  `video/quicktime`, `video/x-m4v` and `application/x-subrip`, instead of
+  `application/octet-stream`, which `<video>` downloads instead of playing.
+
+### Added
+
+- **Hook context**: `authorize` and `onUploadComplete` receive `relatedTo`,
+  `name`, `appVersion`, `filename`, `ext` and the token's `context`, so a
+  host maps a finished file to its own record without reading storage back.
+- **`context` in the capability token** (`issueCapabilityToken(id, secret,
+  { context })`, the `ctx` claim, at most 1 KiB of JSON): an owner, a
+  destination — signed, stored with the artifact at create (`authorize` may
+  return `{ context }`), and handed to every hook, `getStatus` and `getPulse`.
+  Most hosts need no table keyed by artifactId any more.
+- **`GET /artifacts/:id/status`** and `core.getStatus(id)`: `unknown`,
+  `uploading` (with `bytesReceived` against `size`), `processing` or
+  `ready`, plus `acknowledged` and whatever the host recorded with
+  `recordOutcome(id, outcome)`. Authorized as `status`;
+  `createCapabilityAuthorize` grants it to the pairing token and a view token.
+- **`webReady`**: the conversion `ensureWebReady` does, run by the core in
+  the background after the final `PATCH` is answered, `concurrency` at a
+  time, with a `processing` status meanwhile, a `processed` event when done,
+  and `completeAfter: true` to hold `onUploadComplete` until the conversion
+  has finished (`ctx.webReady` says what it did). Whether it finished is
+  recorded on the sidecar (`converted`), so a conversion a restart
+  interrupted is redone by the replay. Local storage only.
+- **`lockWhenReady`**: a finished artifact, and anything `relatedTo` a
+  finished video, can't be deleted through the routes (`403`); the host
+  removes through `storage.remove` on its own terms.
+- **`core.getPulse(videoId)`** → `{ video, thumbnail, captions, manifest }`
+  and **`GET /artifacts/:videoId/poster`**, both from a relation index the
+  adapters keep at reserve time (`storage.listRelated`), so neither scans
+  storage and nothing is backfilled.
+- **Storage adapter contract**: optional `describeArtifact`, `patchArtifact`
+  and `listRelated`, and `context` in `reserveUpload` (both built-in
+  adapters implement them). The local adapter's relation index lives at
+  `.pulsevault/related/<videoId>/<artifactId>`; the S3 adapter's under the
+  same key prefix.
+- **`onArtifactEvent`**: `phase: "processed"` (with `webReady`), and
+  `reason: "reclaimed"` on `remove`.
+- **Fastify**: `fastify.pulseVaultCore` (`coreDecoratorName`) exposes
+  `getStatus`, `getPulse`, `recordOutcome` and `replayCompletions`.
+- **`examples/meteor-demo`** is now the reference host integration, shaped
+  like a team app: people, destinations, a reserve that signs the owner and
+  destination into the token, delivery from `onUploadComplete`, status
+  polling, and video cards with posters — with no table of uploads, no shape
+  check, no stale-upload cleanup and no content-type fix-up of its own.
+
+## [0.4.2] - 2026-10-02
+
+### Added
+
+- **The Pulse logo and the store badges ship with the package**: the logo in
+  full colour and one colour (`assets/pulse-logo.svg`,
+  `assets/pulse-logo-mono.svg`), and the App Store and Google Play badges
+  (`assets/badge-app-store.svg`, `assets/badge-google-play.png`), exported as
+  `@mieweb/pulsevault/assets/*`. An app can put the logo on the button that
+  opens Pulse and link the badges to Pulse's listings. See `assets/README.md`.
+
 ## [0.4.1] - 2026-09-30
 
 ### Fixed
@@ -400,7 +500,8 @@ 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.4.1...HEAD
+[Unreleased]: https://github.com/mieweb/pulsevault/compare/v0.4.2...HEAD
+[0.4.2]: https://github.com/mieweb/pulsevault/compare/v0.4.1...v0.4.2
 [0.4.1]: https://github.com/mieweb/pulsevault/compare/v0.4.0...v0.4.1
 [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

package/OPERATIONS.md

@@ -183,25 +183,29 @@ logs one warning and the original bytes keep serving exactly as before.
 `brew install ffmpeg` (macOS). Nothing else changes; the hook detects it at
 first use.
 
-**New uploads** — wire it into `onUploadComplete` (the fastify-demo ships with
-this enabled):
+**New uploads** — turn on the `webReady` option (the fastify-demo and the
+meteor-demo ship with it enabled). The core runs the conversion in the
+background after the final `PATCH` is answered, one video at a time by
+default, and reports the artifact as `processing` on the status route
+meanwhile:
 
 ```js
-const storage = createLocalStorage({ workspaceDir: dataDir });
 await app.register(pulseVault, {
-  storage,
-  onUploadComplete: async (_request, { artifactId, kind }) => {
-    if (kind !== "video") return;
-    const localPath = await storage.getLocalPath(artifactId);
-    if (localPath) await ensureWebReady(localPath, { logger: app.log });
-  },
+  storage: createLocalStorage({ workspaceDir: dataDir }),
+  webReady: { concurrency: 1, completeAfter: true },
 });
 ```
 
 Options: `{ transcode: false }` restricts it to the lossless remux (no CPU
 cost beyond a file rewrite); `crf`/`preset` tune the transcode
 (defaults `23`/`veryfast`); `ffmpegPath`/`ffprobePath` point at binaries off
-`PATH`.
+`PATH`; `concurrency` runs several at once; `completeAfter: true` holds
+`onUploadComplete` until the conversion has finished, for a host that
+publishes the video from the hook. `onArtifactEvent` fires `processed` with
+what was done. A conversion a restart interrupted is resumed by the
+completion replay (`replayCompletions`). Calling `ensureWebReady` yourself
+from `onUploadComplete` still works, but holds the client's final `PATCH`
+for the whole conversion.
 
 **Existing artifacts** — uploads that landed before the hook existed are fixed
 once with the bundled migration script (idempotent; interrupt and rerun
@@ -231,6 +235,16 @@ integrity for artifacts this feature has touched.
 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.
+Separately, a create that arrives for an unfinished upload of the same id
+(the person scanned the same link again after the app died) takes it over
+once it has been idle for `reclaim.idleSeconds` (300 by default), so nobody
+waits for the sweep.
+
+**Completions the host never recorded** — an `onUploadComplete` that threw,
+or a restart between the final byte and the hook — are fired again by the
+completion replay (`replayCompletions`, every 300 seconds by default, and
+`pulseVaultCore.replayCompletions()` on demand). Nothing to schedule; make the
+hook idempotent.
 
 How long to keep **finished** content is a policy decision `pulsevault`
 leaves to the operator (see `PROTOCOL.md` §1 on lifecycle ownership). A

package/PROTOCOL.md

@@ -3,7 +3,7 @@
 <!-- BEGIN GENERATED: protocol-version (from package.json pulseProtocol — edit that, then run `npm run protocol`) -->
 | | |
 |---|---|
-| Spec revision | `2.2` |
+| Spec revision | `2.3` |
 | Protocol majors accepted | 2 |
 <!-- END GENERATED: protocol-version -->
 
@@ -246,6 +246,18 @@ the token's `artifactId` as its `relatedTo` (§8) — this lets one token cover
 an entire upload session (a pulse's video plus its captions, beat manifest and
 thumbnail) rather than requiring one token per artifact.
 
+A token MAY also carry an opaque `ctx` claim (protocol 2.3): host data signed
+with the rest — who the upload is for, where it goes — that the server stores
+with the artifact the token creates and hands back to its own hooks, so the
+host needs no table keyed by artifactId. A client never reads it.
+
+When a token names a pulse's video, a server SHOULD hold the token to the
+shape of a pulse (§8): the video only under the token's own `artifactId`, with
+no `relatedTo`, and a thumbnail, beat manifest or captions only under another
+id, `relatedTo` the token's. Otherwise one token can create any number of
+artifacts under ids of the client's choosing, or take the video's own id with a
+thumbnail so the video itself can never land.
+
 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.
@@ -312,6 +324,29 @@ 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.
 
+### 6.5 Status and poster (optional, protocol 2.3)
+
+A server MAY expose `GET {prefix}/artifacts/<artifactId>/status`, authorized
+like opening the artifact (§5.1; a view token, §5.5, is enough), reporting
+where an upload is so a page waiting on it needs nothing from the host. Its
+body is defined by
+[`protocol/schemas/artifact-status.schema.json`](protocol/schemas/artifact-status.schema.json):
+`state` is `unknown`, `uploading`, `processing` (the server is converting the
+bytes for the web) or `ready`, with the bytes received against the declared
+length while uploading, and whatever outcome the host recorded once finished.
+The response MUST NOT be cached.
+
+A server MAY also expose `GET {prefix}/artifacts/<videoId>/poster`: the finished
+thumbnail `relatedTo` the video (§8), served exactly as §6.2 serves an artifact
+and authorized as opening the video, so whoever may watch it may see its poster.
+It returns `404` until the thumbnail has landed.
+
+An unfinished upload whose client died (an app killed mid-upload sends no
+TUS `DELETE`) would otherwise answer `409` to every later create of the same
+`artifactId`. A server SHOULD let a create authorized by the same token take
+over such an upload once it has been idle for a while, instead of refusing it
+until cleanup runs.
+
 ## 7. Versioning
 
 The protocol has a version `major.minor`, written once in `@mieweb/pulsevault`'s
@@ -371,6 +406,7 @@ a server it paired with earlier: a server can be upgraded in between.
 | File | Defines |
 |---|---|
 | [`openapi.json`](protocol/openapi.json) | Every HTTP route, generated from the plugin |
+| [`artifact-status.schema.json`](protocol/schemas/artifact-status.schema.json) | GET /artifacts/<id>/status response |
 | [`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 |
@@ -388,6 +424,7 @@ a server it paired with earlier: a server can be upgraded in between.
 | 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). |
+| 2.3 | Added `GET {prefix}/artifacts/<id>/status` and `GET {prefix}/artifacts/<id>/poster` (§6.5), the capability token's `ctx` claim (§5.4), and the pulse-shape rule for creates (§5.4). |
 
 ## 8. Artifact relationships (`relatedTo`)
 

package/README.md

@@ -188,13 +188,17 @@ Four runnable example servers live under [`examples/`](examples):
   query instead of a sidecar crawl), uploads grouped by recording session
   via `relatedTo`, WebVTT captions, Swagger UI, and an `onArtifactEvent`
   live feed.
-- [`examples/express-demo`](examples/express-demo) and
-  [`examples/meteor-demo`](examples/meteor-demo) — the same demo on
-  `@mieweb/pulsevault/core` instead of the plugin, proving the core needs
-  about the same amount of glue code under a different framework. Both are
-  verified against the real frameworks, not just the test suite —
-  `meteor-demo` in particular against a real `meteor create` app, since
-  Meteor's bundler needed the compatibility fixes described above.
+- [`examples/meteor-demo`](examples/meteor-demo) — the **reference host
+  integration**, on `@mieweb/pulsevault/core` under Meteor: shaped like a
+  team app (people, destinations), it reserves an upload by signing the owner
+  and destination into the capability token, delivers the video from
+  `onUploadComplete` to where it was started, polls the status route from
+  the pairing popup, and shows every video as a card with its poster — with
+  no table of uploads, no shape check, no stale-upload cleanup and no
+  content-type fix-up of its own. Verified against a real `meteor create`
+  app, since Meteor's bundler needed the compatibility fixes described above.
+- [`examples/express-demo`](examples/express-demo) — the fastify-demo on
+  `@mieweb/pulsevault/core` under Express.
 
 ## How a pairing + upload session flows
 
@@ -231,7 +235,9 @@ The plugin mounts the following routes under `prefix` (`@mieweb/pulsevault/core`
 | `PATCH` / `HEAD` / `DELETE` \* | `/pulsevault/upload/:id` | Upload chunks, probe offset, delete the upload (TUS) |
 | `GET` | `/pulsevault/artifacts/:artifactId` | Stream or redirect to the uploaded artifact (any kind) |
 | `POST` | `/pulsevault/artifacts/:artifactId/view-link` | Mint a read-only view link to a finished artifact (only with [`issueViewLink`](#issueviewlink)) |
-| `DELETE` | `/pulsevault/artifacts/:artifactId` | Delete a finalized upload (bytes + sidecar) |
+| `GET` | `/pulsevault/artifacts/:artifactId/status` | Where an upload is: `uploading` (with progress), `processing`, `ready`, plus the host's recorded outcome (see [Status, outcome and pulses](#status-outcome-and-pulses)) |
+| `GET` | `/pulsevault/artifacts/:artifactId/poster` | A video's poster frame: the finished thumbnail `relatedTo` it, served like the artifact route |
+| `DELETE` | `/pulsevault/artifacts/:artifactId` | Delete a finalized upload (bytes + sidecar); refused once finished with [`lockWhenReady`](#lockwhenready) |
 
 \* `DELETE /pulsevault/upload/:id` is TUS termination, addressed by the upload URL: it removes the artifact whether the upload is still in flight (a cancel) or finished, exactly as `DELETE /pulsevault/artifacts/:artifactId` does by artifactId.
 
@@ -250,12 +256,20 @@ type PulseVaultPluginOptions = {
   allowedExtensions?:
     | string[]                                                                              // legacy — treated as video-only
     | { video?: string[]; project?: string[]; captions?: string[]; thumbnail?: string[] };  // per-kind (recommended)
-  // defaults: { video: [".mp4"], project: [".pulse", ".zip"], captions: [".vtt"], thumbnail: [".jpg", ".jpeg", ".png"] }
+  // defaults: { video: [".mp4"], project: [".pulse", ".zip"], captions: [".vtt"], thumbnail: [".jpg", ".jpeg", ".png"] } — what Pulse sends
   cache?: PulseVaultCacheOptions;
   authorize?: PulseVaultAuthorize;
   validatePayload?: PulseVaultValidatePayload;          // runs for every kind; branch on ctx.kind
-  onUploadComplete?: PulseVaultOnUploadComplete;        // runs for every kind; branch on ctx.kind
+  onUploadComplete?: PulseVaultOnUploadComplete;        // runs for every kind; branch on ctx.kind; at-least-once
   onArtifactEvent?: PulseVaultOnArtifactEvent;          // low-frequency hook for metrics + audit logging
+  issueViewLink?: PulseVaultIssueViewLink;              // read-only view links
+  retention?: { abandonedAfterSeconds: number; sweepIntervalSeconds?: number };
+  pulseShape?: boolean;                                 // default true: creates must have the shape of a pulse
+  reclaim?: { idleSeconds?: number } | false;           // default { idleSeconds: 300 }: a create takes over an idle unfinished upload
+  lockWhenReady?: boolean;                              // default false: a finished pulse can't be deleted through the routes
+  webReady?: PulseVaultWebReadyOptions | boolean;       // default off: background faststart remux / H.264 transcode
+  replayCompletions?: { intervalSeconds?: number } | false; // default every 300 s: re-fire unacknowledged completions
+  coreDecoratorName?: string;                           // default "pulseVaultCore": getStatus, getPulse, recordOutcome, replayCompletions
   /** @deprecated use validatePayload + ctx.kind === "project" */
   validateProjectPayload?: PulseVaultValidatePayload;
   /** @deprecated use onUploadComplete + ctx.kind === "project" */
@@ -322,7 +336,7 @@ Upload filenames are keyed by UUID, so `immutable: true` is safe when `maxAge` i
 
 Optional async hook called before TUS create/patch, before GET resolve, before DELETE, and before minting a view link. Throw to reject — a `statusCode` or `status_code` number on the thrown error is used as the HTTP status (default `403`).
 
-Phase mapping: `"create"` is the initial TUS `POST`; `"patch"` covers `PATCH` chunks and `HEAD` offset queries on the upload routes; `"resolve"` is `GET {prefix}/artifacts/<id>`; `"delete"` is **both** ways of removing an artifact — `DELETE {prefix}/artifacts/<id>` and the TUS `DELETE {prefix}/upload/<id>` (a cancel of an in-flight upload, or removal of a finished one). Gating `phase === "delete"` gates every removal. `"share"` is `POST {prefix}/artifacts/<id>/view-link` — minting a read-only link — and only happens when [`issueViewLink`](#issueviewlink) is set.
+Phase mapping: `"create"` is the initial TUS `POST`; `"patch"` covers `PATCH` chunks and `HEAD` offset queries on the upload routes; `"resolve"` is `GET {prefix}/artifacts/<id>` and the poster route (authorized on the video); `"status"` is `GET {prefix}/artifacts/<id>/status`; `"delete"` is **both** ways of removing an artifact — `DELETE {prefix}/artifacts/<id>` and the TUS `DELETE {prefix}/upload/<id>` (a cancel of an in-flight upload, or removal of a finished one). Gating `phase === "delete"` gates every removal. `"share"` is `POST {prefix}/artifacts/<id>/view-link` — minting a read-only link — and only happens when [`issueViewLink`](#issueviewlink) is set.
 
 ```ts
 type PulseVaultAuthorize = (
@@ -333,15 +347,22 @@ type PulseVaultAuthorize = (
   // `http.IncomingMessage`, etc.) — the same hook works under either.
   request: PulseVaultRequest,
   ctx: {
-    phase: "create" | "patch" | "resolve" | "delete" | "share";
+    phase: "create" | "patch" | "resolve" | "status" | "delete" | "share";
     artifactId: string;
-    kind: "video" | "project" | "captions";  // artifact kind; always present
-    token?: string;             // only on "resolve" phase
-    relatedTo?: string;         // the session-anchor artifact this one belongs to, if any
+    kind: "video" | "project" | "captions" | "thumbnail";  // artifact kind; always present
+    token?: string;             // only on the "resolve" and "status" phases
+    relatedTo?: string;         // the video this artifact belongs to, if it declared one
+    name?: string;              // Upload-Metadata.name, when sent
+    appVersion?: string;        // Upload-Metadata.appVersion, when sent
+    filename?: string;          // Upload-Metadata.filename
+    ext?: string;               // its lowercase extension, with the dot
+    context?: unknown;          // the token's context, read back from storage (absent on "create")
   },
-) => void | Promise<void>;
+) => void | { context?: unknown } | Promise<void | { context?: unknown }>;
 ```
 
+On `create` the hook may return `{ context }`: opaque host data (an owner, a destination) stored with the artifact and handed to every later `authorize`, to `onUploadComplete`, to `getStatus` and to `getPulse`. `createCapabilityAuthorize` returns the token's own `context` claim (see [Capability tokens](#capability-tokens)), so most hosts never touch this.
+
 ```ts
 await app.register(pulseVault, {
   // ...
@@ -414,25 +435,42 @@ Optional async hook fired once the final byte is written, `validatePayload` has
 
 ```ts
 type PulseVaultOnUploadComplete = (
-  request: PulseVaultRequest, // see the note under `authorize` above
-  ctx: { artifactId: string; kind: "video" | "project" | "captions"; size: number; uploadId: string },
+  request: PulseVaultRequest, // see the note under `authorize` above; `{ headers: {} }` on a replay
+  ctx: {
+    artifactId: string;
+    kind: "video" | "project" | "captions" | "thumbnail";
+    size: number;
+    uploadId: string;
+    filename: string;        // Upload-Metadata.filename
+    ext: string;             // its lowercase extension, with the dot
+    relatedTo?: string;      // the video a thumbnail, beat manifest or captions belongs to
+    name?: string;           // Upload-Metadata.name (the draft's title), when sent
+    appVersion?: string;     // Upload-Metadata.appVersion, when sent
+    context?: unknown;       // the capability token's context (see Capability tokens)
+    replay: boolean;         // true when PulseVault is firing a completion it never recorded
+    webReady?: WebReadyResult; // with `webReady.completeAfter`: what the conversion did
+  },
 ) => void | Promise<void>;
 ```
 
+**Completion is at-least-once.** PulseVault records that the hook returned (`acknowledged` in the artifact's sidecar). A finished artifact whose hook never returned — it threw, or the process stopped between the final byte and the hook — is fired again later with `ctx.replay: true` (see [`replayCompletions`](#replaycompletions)). So the hook must check its own record before writing it again: an upsert, or a claim that only one caller wins. A retried final `PATCH` for an acknowledged upload does not fire the hook a second time.
+
 ### `onArtifactEvent`
 
 Optional low-frequency hook — fired on authorize rejection (every phase but per-chunk `patch`), upload completion, payload-validation rejection, and removal. One hook covers both ops metrics and a compliance audit trail instead of hand-wiring both from the lower-level hooks above, and `remove` is where a host keeping its own index of artifacts drops one:
 
 ```ts
 type PulseVaultArtifactEvent = {
-  phase: "authorize" | "complete" | "reject" | "remove";
+  phase: "authorize" | "complete" | "reject" | "remove" | "processed";
   artifactId: string;
   kind: "video" | "project" | "captions" | "thumbnail";
   size?: number;
   // present for "authorize" and "reject"; on "remove", "deleted" (DELETE /artifacts/:id or a
-  // TUS DELETE) or "abandoned" (the `retention` sweep)
+  // TUS DELETE), "abandoned" (the `retention` sweep) or "reclaimed" (a create took over an
+  // idle unfinished upload); on "processed", what the web-ready conversion did
   reason?: string;
   appVersion?: string; // the uploading app's version, on "complete"/"reject" (protocol 2.1)
+  webReady?: WebReadyResult; // on "processed": { action, reason }
 };
 
 onArtifactEvent: (event) => {
@@ -482,6 +520,59 @@ Finished videos, and anything whose video finished, are never touched; this is n
 
 A sweep reads the metadata of every artifact older than the cutoff — one `GetObject` each on S3 — so on a large bucket sweep daily (or off-peak from a cron job) rather than hourly. Several instances may sweep the same storage (a removal that finds nothing is a no-op), but each instance caches metadata: on S3, an id another instance removed can still answer `409` on this one until the entry is evicted — the same as for `DELETE /artifacts/:id`. To schedule it yourself (a cron job, a queue), call `sweepAbandonedUploads(storage, { abandonedAfterSeconds, onRemoved? })` instead; it resolves the removed artifactIds.
 
+### `pulseShape`
+
+On by default. Every create must have the shape of a pulse (`PROTOCOL.md` §8): a video is created with no `relatedTo`, and a thumbnail, beat manifest or captions under its own id, `relatedTo` the video it belongs to. Anything else is refused at create with `403`, before any bytes move. With [`createCapabilityAuthorize`](#capability-tokens) the ids are also tied to the token: the video only under the token's own `artifactId`, the rest only `relatedTo` it. Without this, one token could create any number of videos under ids the client picks (never attached to anything, still converted, never removed), or take the video's own id with a thumbnail so the real video answers `409` for good.
+
+The Pulse app has always uploaded in this shape. For uploads that aren't pulses, pass `pulseShape: false` here **and** to `createCapabilityAuthorize`.
+
+### `reclaim`
+
+`{ idleSeconds: 300 }` by default; `false` turns it off. An app killed mid-upload sends no TUS `DELETE`, so its unfinished upload keeps its artifactId and every later create of that id — the person scanning the same link again — answers `409` until `retention` removes it. With `reclaim`, a create takes over an unfinished upload of the same artifactId once it has been idle for `idleSeconds` — no bytes received: the bytes file's mtime on the local adapter, the newest multipart part (or the incomplete part parked between `PATCH`es) on S3: the old upload is removed (`onArtifactEvent` `remove` with `reason: "reclaimed"`) and the new one starts from byte 0. Only an upload of the same kind and `relatedTo` is taken over, so the token that authorized the new create authorized the old one; only one whose last activity the adapter knows; and creates for one artifactId run one at a time per instance, so two rescans can't both take it over.
+
+### `lockWhenReady`
+
+Off by default. Once an artifact is finished, `DELETE {prefix}/artifacts/<id>` and the TUS `DELETE` answer `403` for it, and for anything `relatedTo` a finished video: a pulse that landed stays, whatever token is presented. Removal then goes through `storage.remove` on the host's own terms (an admin action, a retention policy). The check reads storage (not the per-instance cache) just before the removal. For the TUS `DELETE` it runs inside tus's per-upload lock, so a cancel racing the final chunk of the same upload waits for it and then finds the artifact finished. `DELETE {prefix}/artifacts/<id>` takes no such lock — the Pulse app never uses it while uploading — so a delete and a final chunk arriving in the same instant can both succeed there.
+
+### `webReady`
+
+Off by default. `true`, or `ensureWebReady`'s options plus:
+
+```ts
+webReady: {
+  concurrency: 1,        // conversions at once; a transcode is CPU-bound
+  completeAfter: false,  // true: run onUploadComplete only once the conversion has finished
+  transcode: true, crf: 23, preset: "veryfast", ffmpegPath: "ffmpeg", ffprobePath: "ffprobe",
+},
+```
+
+Every finished video is made web-playable in the background, after the final `PATCH` is answered: a lossless faststart remux when the `moov` atom is at the end, or a one-time H.264 transcode when the codec is one browsers can't play (see `OPERATIONS.md`). While it runs the artifact's status is `processing` (the original bytes serve meanwhile; the rewrite is atomic), and when it's done `onArtifactEvent` fires `processed` with what it did. With `completeAfter: true`, `onUploadComplete` waits for the conversion and receives `ctx.webReady`, so a host that publishes from the hook never publishes a video that's still being rewritten. A conversion a restart interrupted is resumed by the replay below. Needs the local storage adapter and ffmpeg on the host; without ffmpeg it logs once and serves the original bytes.
+
+### `replayCompletions`
+
+On by default, every 300 seconds, with the first pass shortly after start; `{ intervalSeconds }` changes the interval and `false` turns it off. Each pass applies the one completion rule to every finished artifact that isn't settled: convert it if `webReady` applies and it isn't converted yet, then fire `onUploadComplete` again (`ctx.replay: true`) if the host hasn't acknowledged it. Both facts live on the artifact's sidecar (`converted`, `acknowledged`), written `false` at reserve, so nothing depends on what a process remembered. Turning `webReady` on later converts, on the first pass, the videos uploaded since this release that weren't. `fastify.pulseVaultCore.replayCompletions()` (or `core.replayCompletions()`) runs a pass on demand, for example at boot once the host's own services are up. Finished sidecars written before PulseVault recorded acknowledgements read as acknowledged, so an upgrade replays nothing (one still uploading at the upgrade completes normally).
+
+### Status, outcome and pulses
+
+The core behind the routes is `fastify.pulseVaultCore` (rename it with `coreDecoratorName`; non-Fastify hosts have it as the object `createPulseVaultCore` returns):
+
+```ts
+// Where an upload is — what GET /artifacts/:id/status reports — for a host that polls server-side.
+await app.pulseVaultCore.getStatus(videoId);
+// → { artifactId, state: "unknown" | "uploading" | "processing" | "ready", kind, relatedTo?, name?,
+//     bytesReceived?, size?, acknowledged, outcome?, context? }
+// `context` (the token's) is for the host — an owner check is a comparison on it; the route leaves it out.
+
+// Where it went, or why it didn't: any JSON, reported as `outcome` by the status route. `null` clears it.
+await app.pulseVaultCore.recordOutcome(videoId, { state: "done", note: "Posted to Huddle" });
+
+// A video and the finished files relatedTo it, by kind — from the adapters' relation index, never a scan.
+const { video, thumbnail, captions, manifest } = await app.pulseVaultCore.getPulse(videoId);
+// One per kind; when a file was re-sent, the one that finished last (`readyAt`) wins.
+```
+
+A page waiting on an upload polls `GET {prefix}/artifacts/<id>/status` (never cached) with the pairing token or a view token, and reads `outcome` once the host recorded one — no table, SSE route or polling method of the host's own. `GET {prefix}/artifacts/<videoId>/poster` serves the video's thumbnail the way the artifact route serves it, authorized as `resolve` on the video, and `404`s until the poster has landed, so a card asks by the video's id and nothing is copied onto the host's records.
+
 ### `validateProjectPayload` / `onProjectUploadComplete` (deprecated)
 
 Same lifecycle as `validatePayload`/`onUploadComplete`, but only fired for `kind=project` uploads. **Deprecated** — use the generic `validatePayload`/`onUploadComplete` with a `ctx.kind === "project"` branch instead. Still honored this release (passing either emits a one-time `DeprecationWarning` at registration); will be removed in a future major version.
@@ -492,7 +583,7 @@ When the final PATCH lands the plugin runs the following steps in order, for eve
 
 1. **`validatePayload`** (optional, runs for every kind) — throws → `storage.remove(artifactId)`, HTTP 4xx (default 422).
 2. **`storage.markReady(artifactId)`** — flips the sidecar so `resolve()` will serve the bytes.
-3. **`onUploadComplete`** (optional, runs for every kind) — throws → HTTP 500; bytes remain ready unless the consumer removes them.
+3. **`onUploadComplete`** (optional, runs for every kind) — throws → HTTP 500; bytes remain ready unless the consumer removes them, and the completion is replayed later (`ctx.replay: true`). Once it returns, the artifact is acknowledged. With `webReady`, the conversion is queued here; with `webReady.completeAfter`, the hook runs after it instead.
 
 (`validateProjectPayload`/`onProjectUploadComplete`, if passed, run instead of the generic hooks specifically for `kind=project` — see the deprecation note above.)
 
@@ -568,7 +659,19 @@ app.post("/pair", async (_req, reply) => {
 });
 ```
 
-A token authorizes either the artifact it names, or any artifact that declares that one as its `relatedTo` — so one token issued for a pulse's video also covers its captions, beat manifest and thumbnail in the same session, without minting a token per artifact. See `PROTOCOL.md` §5.4 for the full claim shape (`kid`/`iat`/`exp`/`issuer`/`artifactId`) and rationale.
+A token authorizes either the artifact it names, or any artifact that declares that one as its `relatedTo` — so one token issued for a pulse's video also covers its captions, beat manifest and thumbnail in the same session, without minting a token per artifact. With [`pulseShape`](#pulseshape) (the default, on both the plugin and `createCapabilityAuthorize`), a create is held to that shape: the video only under the token's own `artifactId`, with no `relatedTo`; the rest only under other ids, `relatedTo` it. See `PROTOCOL.md` §5.4 for the full claim shape (`kid`/`iat`/`exp`/`issuer`/`artifactId`/`ctx`) and rationale.
+
+**Context.** The token can carry the host's own data about the upload — who it's for, where it goes — signed with the rest, so whoever holds the token can't change it:
+
+```ts
+const token = issueCapabilityToken(artifactId, keys["2026-06"], {
+  keyId: "2026-06",
+  issuer,
+  context: { userId: user.id, destination: { kind: "huddle", teamId } }, // any JSON, at most 1 KiB encoded
+});
+```
+
+`createCapabilityAuthorize` returns it from the `create` phase, PulseVault stores it with the artifact (and with every file uploaded `relatedTo` it under the same token), and every later `authorize`, `onUploadComplete` (`ctx.context`, on replays too), `getStatus` and `getPulse` get it back. Most hosts then keep no table keyed by artifactId, and "is this the person who uploaded it?" is a comparison, not a lookup.
 
 ## Upload-Metadata protocol
 
@@ -612,7 +715,9 @@ The local adapter writes uploads into flat kind-scoped subdirectories. Downstrea
 
 ```text
 <workspaceRoot>/
-  .pulsevault/<id>.json           # sidecar: { version, ext, filename, status, kind, relatedTo, checksum, name }
+  .pulsevault/<id>.json           # sidecar: { version, ext, filename, status, kind, relatedTo, checksum, name,
+                                  #            appVersion, context, acknowledged, converted, readyAt, outcome }
+  .pulsevault/related/<videoId>/<id>  # relation index: an empty marker per artifact relatedTo the video
   video/<id><ext>                 # video upload bytes    (kind="video")
   video/<id><ext>.json            # @tus/file-store offset/metadata sidecar
   project/<id><ext>               # project bundle bytes  (kind="project")
@@ -623,7 +728,7 @@ The local adapter writes uploads into flat kind-scoped subdirectories. Downstrea
 
 `status` is `"uploading"` between `reserveUpload` and the successful final PATCH; `"ready"` thereafter. `GET /artifacts/:id` only serves `"ready"` uploads. `kind` defaults to `"video"` when absent (back-compat with pre-kind sidecars).
 
-The adapter exposes `storage.workspaceRoot` (absolute, resolved from `workspaceDir`) so consumers can compute per-resource paths without re-implementing the layout. `storage.getKind(id)` returns `"video" | "project" | "captions" | null`; `storage.getRelatedTo(id)`, `storage.getChecksum(id)`, and `storage.getName(id)` return the corresponding sidecar fields, each `null` if absent/unknown.
+The adapter exposes `storage.workspaceRoot` (absolute, resolved from `workspaceDir`) so consumers can compute per-resource paths without re-implementing the layout. `storage.describeArtifact(id)` returns everything the sidecar holds plus `ready`, `acknowledged`, `processing` and `updatedAt` (`null` if unknown); `storage.listRelated(videoId)` walks the relation index; `storage.getKind(id)`, `storage.getRelatedTo(id)`, `storage.getChecksum(id)` and `storage.getName(id)` return single fields, each `null` if absent/unknown.
 
 **Horizontal scaling**: this adapter requires sticky-session routing or a shared filesystem across instances — see `OPERATIONS.md`.
 
@@ -760,9 +865,13 @@ const storage: PulseVaultStorage = {
   async shutdown() {
     /* optional teardown */
   },
-  async reserveUpload({ artifactId, filename, ext, kind, relatedTo, checksum, name }) {
-    // Called by the TUS naming function. Return the file id for the datastore.
-    await db.createArtifact({ artifactId, filename, kind, relatedTo, checksum, name, status: "uploading" });
+  async reserveUpload({ artifactId, filename, ext, kind, relatedTo, checksum, name, appVersion, context }) {
+    // Called by the TUS naming function. Return the file id for the datastore. `context` is what
+    // `authorize` returned for this create (the capability token's context); keep it with the row.
+    await db.createArtifact({
+      artifactId, filename, ext, kind, relatedTo, checksum, name, appVersion, context,
+      status: "uploading", acknowledged: false, converted: false,
+    });
     return `${kind}/${artifactId}${ext}`;
   },
   async resolve(artifactId): Promise<PulseVaultResolution | null> {
@@ -793,13 +902,36 @@ const storage: PulseVaultStorage = {
   async getRelatedTo(artifactId) { return (await db.findArtifact(artifactId))?.relatedTo ?? null; },
   async getChecksum(artifactId) { return (await db.findArtifact(artifactId))?.checksum ?? null; },
   async getName(artifactId) { return (await db.findArtifact(artifactId))?.name ?? null; },
-  // Optional — needed only by `retention` / `sweepAbandonedUploads`. `updatedAt` is when the
-  // upload started while it's unfinished, and when it finished once ready (ms since epoch).
+  // Optional — needed by `retention` / `sweepAbandonedUploads` and by the completion replay.
+  // `updatedAt` is when the upload last received bytes (or started) while it's unfinished, and
+  // when it finished once ready (ms since epoch).
   async *listArtifacts({ changedBefore } = {}) {
     for (const row of await db.listArtifacts({ changedBefore })) {
       yield { artifactId: row.id, kind: row.kind, relatedTo: row.relatedTo, ready: row.ready, updatedAt: row.updatedAt };
     }
   },
+  // Optional — the richer hook context, `getStatus`, `getPulse`, `reclaim`, `webReady` and the
+  // completion replay need these three.
+  async describeArtifact(artifactId) {
+    const row = await db.findArtifact(artifactId);
+    if (!row) return null;
+    return {
+      artifactId, kind: row.kind, ext: row.ext, filename: row.filename, relatedTo: row.relatedTo,
+      checksum: row.checksum, name: row.name, appVersion: row.appVersion, context: row.context,
+      ready: row.status === "ready", acknowledged: row.acknowledged, converted: row.converted,
+      outcome: row.outcome, updatedAt: row.updatedAt, readyAt: row.readyAt,
+    };
+  },
+  async patchArtifact(artifactId, { acknowledged, converted, outcome }) {
+    // Each field is optional; `outcome: null` clears it. Return false for an unknown id.
+    return (await db.updateArtifact(artifactId, { acknowledged, converted, outcome })).matched;
+  },
+  async *listRelated(artifactId) {
+    // Every artifact whose `relatedTo` is this one — from an index, not a scan.
+    for (const row of await db.listArtifacts({ relatedTo: artifactId })) {
+      yield { artifactId: row.id, kind: row.kind, relatedTo: artifactId, ready: row.ready, updatedAt: row.updatedAt };
+    }
+  },
 };
 ```
 
@@ -822,6 +954,13 @@ const uploadLink = buildUploadLink({
 // pulsecam://?v=1&artifactId=...&server=https%3A%2F%2Fexample.com%2Fpulsevault&token=secret
 ```
 
+## Pulse logo and store badges
+
+The package ships the Pulse logo for the button that opens Pulse
+(`@mieweb/pulsevault/assets/pulse-logo.svg` in full colour,
+`pulse-logo-mono.svg` in one colour), and the App Store and Google Play badges
+to link to Pulse's listings. See [assets/README.md](assets/README.md).
+
 ## Tests
 
 ```sh

package/assets/README.md

@@ -0,0 +1,33 @@
+# Pulse assets
+
+For any app that pairs with Pulse through PulseVault: the Pulse logo, to put
+on the button that opens Pulse, and the store badges, to link people who
+don't have Pulse yet to its listings.
+
+| File                    | What it is                                                    |
+| ----------------------- | ------------------------------------------------------------- |
+| `pulse-logo.svg`        | Full colour, the Pulse red gradient. Use it on light or dark. |
+| `pulse-logo-mono.svg`   | One colour, `currentColor` (black when used as an `<img>`).   |
+| `badge-app-store.svg`   | Apple's "Download on the App Store" badge (black).            |
+| `badge-google-play.png` | Google's "Get it on Google Play" badge.                       |
+
+The logos are 87 × 100 (width × height) and scale to any size. The heartbeat
+is cut out, so whatever is behind the logo shows through it.
+
+The badges are Apple's and Google's own artwork, used under their badge
+guidelines: show them unaltered, at the same height side by side, and link
+them to Pulse's listings:
+
+- App Store: `https://apps.apple.com/us/app/pulse-cam/id6748621024`
+- Google Play: `https://play.google.com/store/apps/details?id=com.mieweb.pulse`
+
+They ship in the package, so a bundler can import them:
+
+```js
+import pulseLogo from "@mieweb/pulsevault/assets/pulse-logo.svg";
+
+button.innerHTML = `<img src="${pulseLogo}" alt="" width="14" height="16"> Record with Pulse`;
+```
+
+Inline the mono file's markup to colour it with CSS `color`, or use it as a
+CSS `mask-image` over any background.